ZhileTime.IE.Core 1.1.6

ZhileTime.IE

面向 .NET 10 的文件导入导出 SDK。Excel 与 CSV 支持数据导入、模板生成和校验；Excel、CSV、HTML、Word、PDF 支持导出；ASP.NET Core 适配层负责将导出结果交付为 HTTP 下载。

本页依据当前公开接口、服务注册和测试重写。业务系统负责权限、数据查询、导入结果落库与任务调度，SDK 负责文件解析、转换、渲染和输出。

NuGet · 源码 · 原件报告 · 云原生构建 · 变更记录

CI/CD 提供自动版本候选、测试与覆盖率报告、逐包 SBOM 原件及发布恢复；维护者可在构建报告查看 NuGet 凭据到期状态。日常推送、发布和恢复操作见完整教程。

安装

当前源码版本：1.1.6。公开可用状态以 NuGet 和发布报告为准。

dotnet add package ZhileTime.IE.Excel --version 1.1.6

版本、包名和目标框架由 common.props、build/packages.json 与实际项目文件生成。中央包管理项目将版本放入 Directory.Packages.props，业务项目使用 PackageReference，无需检出本仓库或添加本地 ProjectReference。

选择模块

Core 承载属性、导入结果和流内容契约；Runtime 承载导出文档与格式 Provider 契约；EPPlus 是底层工作簿实现。通常由所选格式包传递引入这些依赖。

从 DTO 导出并回读 Excel

下面是一个可放入 .NET 10 控制台项目的完整示例。安装 ZhileTime.IE.Excel 后运行，会写出并回读 employees.xlsx。

using System.ComponentModel.DataAnnotations;
using ZhileTime.IE.Core.Attributes;
using ZhileTime.IE.Excel;

var rows = new List<EmployeeRow>
{
    new() { Name = "张三", Email = "zhangsan@example.com" }
};
var exporter = new ExcelExporter();
await using (var output = File.Create("employees.xlsx"))
{
    await exporter.ExportToStreamAsync(rows, output);
}

var importer = new ExcelImporter();
var result = await importer.ImportAsync<EmployeeRow>("employees.xlsx");
if (result.HasError)
{
    Console.WriteLine($"导入未通过：模板错误 {result.TemplateErrors.Count}，行错误 {result.RowErrors.Count}");
    return;
}
foreach (var row in result.Data)
{
    Console.WriteLine($"{row.Name}: {row.Email}");
}

public sealed class EmployeeRow
{
    [Required]
    [ExportHeader("姓名")]
    [ImportHeader(Name = "姓名")]
    public string Name { get; set; } = "";

    [EmailAddress]
    [ExportHeader("邮箱")]
    [ImportHeader(Name = "邮箱")]
    public string Email { get; set; } = "";
}

ImportResult<T> 同时包含 Data、TemplateErrors、RowErrors、Exception 和 HasError。成功解析出部分行不等于整批导入成功；先评审错误结果，再由业务系统决定是否持久化。

需要用户先填写标准模板时，调用 GenerateTemplateFileAsync<EmployeeRow>("template.xlsx")。需要返回标注文件时，使用 ImportAsync<T>(输入流, 标注输出流, ...)，或指定标注输出文件路径。模板级结构检查可单独使用 IExcelTemplateValidator。

流与资源所有权

优先根据消费方式选择 API：

• 已有目标流：ExportToStreamAsync 直接写入，由调用方管理目标流。
• 希望延后读取：ExportStreamAsync 返回 IExportStreamContent，调用方必须释放内容对象和打开的读取流。
• 小文件需要字节数组：ExportAsBytesAsync 等便利扩展会将结果载入内存，不适合作为所有大文件的默认出口。

using var content = await exporter.ExportStreamAsync(rows);
using var input = content.OpenReadStream();
await using var output = File.Create("employees-copy.xlsx");
await input.CopyToAsync(output);

接口接受 CancellationToken；Web 请求应沿调用链传递 HttpContext.RequestAborted。返回流接口不代表工作簿计算过程是恒定内存，应按实际行数、图片和模板规模验证资源预算。

在依赖注入中使用

using Microsoft.Extensions.DependencyInjection;
using ZhileTime.IE.Excel;

services.AddExcelExporter();
services.AddExcelImporter();

导出器、导入器为作用域服务。除 IExcelExporter / IExcelImporter 聚合入口外，可以只注入需要的能力，例如 IExcelWorkbookExporter、IExcelTemplateExporter、IExcelDataImporter、IExcelTemplateGenerator；同一作用域的别名复用对应实现实例。

CSV、HTML、Word、PDF 分别提供 AddCsvExporter / AddCsvImporter、AddHtmlExporter、AddWordExporter、AddPdfExporter。PDF 转换调度器由容器管理，不应在每次请求里另建队列。

Excel 进阶入口

动态导入通过 AddDynamicExcelImporter 注册。脚本与规则能力分别显式调用 AddCSharpScriptImportTransformCompiler、AddRuleEngineImportTransformCompiler；只安装包不会自动信任或执行上传者提供的代码。定义、类型解析和可调用服务必须由应用控制。

ASP.NET Core 下载

安装 ZhileTime.IE.AspNetCore，一次注册全局选项，再组合需要的格式：

using ZhileTime.IE.AspNetCore;

builder.Services.AddIEHttpExport(options =>
{
    options.MemoryThresholdBytes = 4 * 1024 * 1024;
    options.ResponseBufferMemoryThresholdBytes = 1024 * 1024;
})
.AddExcelHttpExport()
.AddCsvHttpExport();

不要在同一服务集合重复调用 AddIEHttpExport。以上只启用 Excel/CSV；HTML、Word、PDF 通过对应 Add*HttpExport 显式加入。

若控制器已经有查询结果，可安装 ZhileTime.IE.Excel.AspNetCore，注入 IExcelWorkbookExporter，直接返回 new XlsxFileResult<EmployeeRow>(rows, exporter, "employees.xlsx")。响应写出层处理内容类型、文件名、请求取消和导出内容释放。

PDF 与部署边界

PDF 依赖 wkhtmltopdf 原生库和可用字体。Linux CI 的确切依赖维护在 Dockerfile.ci，部署应用应按目标操作系统与架构准备运行库，不能把 Linux x64 验证推断为所有平台均可用。

PdfConversionDispatcherOptions 默认一个工作线程、自动推导队列容量（默认四个）、入队等待 30 秒；可通过 AddPdfExporter 或 HttpExportOptions.PdfDispatcher 配置。增加工作线程需要结合实际原生转换负载评估。

上传文件大小、远程图片来源、模板来源、脚本权限、输出目录和临时磁盘容量属于应用边界。不要将未验证的导入数据直接落库，也不要把外部输入直接作为脚本或任意文件路径执行。

构建状态与报告

上方徽标动态显示最近一次原件报告状态，可能来自主干或 MR；请进入云原生构建页按分支和源码提交核对。构建通过不代表包已发布；正式发布以整批包内容核验通过及对应 Release 为准。

详细报告需要 CODING 项目访问权限。CI 同时采集行与分支覆盖率，按模块和运行时生成独立 HTML 明细、JSON 和 SVG 徽标。进入同一构建的“通用报告 → 代码覆盖率”查看；徽标绑定该次构建，不把历史值冒充当前主干状态。详见覆盖率说明。云原生执行 MR、主干和定时构建，既有 CI 接收同一原件并展示报告；独立 CD 提升已验证包。详见云原生交付与恢复。

开发、自动构建与发布

维护本仓请先读 完整 CI/CD 使用手册：包含计划用途、触发矩阵、版本与说明、审批、报告、缓存升级及失败恢复。完整教程集中在手册，README 保留日常步骤。

1. 从最新 master 建立功能分支，用 fix(sdk): …、feat(sdk): … 等明确提交标题推送代码。
2. 在 CODING 创建“功能分支 → master”的 MR。MR 创建及源分支更新自动运行云原生构建、测试、覆盖率和打包；没有 MR 的普通分支 push 不触发构建。
3. CI 通过后合并功能 MR。主干自动构建并规划版本；产品变更创建版本候选 MR，仅文档/测试/流水线变更不自动发版，未知分类需人工确认。
4. 评审并合并候选 MR，主干 CI 保存原件，编排自动创建注解标签并触发 CD。
5. 发布者完成推包审批后，CD 发布同一原件，等待 NuGet 全部可用、核验内容，再自动创建 Release 和说明。功能 MR 与候选 MR 合并时均应勾选删除源分支。

当前保留候选评审与正式推包审批；不要手工改版本、随意打标签或上传本地包代替发布流程。ie-ci 是原件报告接收器，ie-release-flow 负责候选和标签，ie-nuget-release 负责发布，ie-ci-toolchain 仅维护工具镜像；这些不是重复构建计划。

本地按 工具镜像配方准备 .NET SDK、PowerShell 7、Python 3 和固定版本工具；完整 CI 还需要镜像中的运行时及系统依赖。按变更选择必要验证，云端负责完整 Linux 验收：

# 检查版本、CHANGELOG 和 README 自动区；修改包清单后用 docs-update 刷新
python build/ci_report.py metadata
# 完整构建、测试、覆盖率与打包：使用已准备工具链的干净工作区
pwsh -NoProfile -File build/ci.ps1

已有原始覆盖率的工作区会被完整入口拒绝，避免混入旧结果；不要清理其他任务的在用产物。Windows 与 Hope 共用开发机时，使用 Hope 构建协调入口并声明实际产物根。报告和正式发布状态的区别见上方“构建状态与报告”。

• CI/CD 使用手册 · 自动版本规则
• 云原生交付与恢复 · 覆盖率
• 文档中心 · 分阶段验收记录 · 贡献指南

许可证

仓库许可证见 LICENSE。本项目维护 ZhileTime 包发行线并保留上游版权声明；底层组件与传递依赖仍需遵守各自许可证。