ZhileTime.IE.Extensions.CSharpScript 1.1.2

ZhileTime.IE

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

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

NuGet · 源码 · CI · 变更记录

安装

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

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

版本、包名和目标框架由 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 配置。增加工作线程需要结合实际原生转换负载评估。

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

开发与发布

使用 global.json 指定的 SDK、PowerShell 7、Python 3，以及工具镜像中固定的 Gitleaks。

# 修改版本或包清单后刷新本页安装区域
python build/ci_report.py docs-update
# 与 CODING 相同的构建、测试、包内容和报告入口
pwsh -NoProfile -File build/ci.ps1

CI 执行脚本回归、元数据检查、密钥扫描、依赖审计、IE/Web/EPPlus 测试及 13 个包的打包，输出 JUnit、HTML、步骤日志、包清单与 SHA256 原件归档。测试数量和跳过项以每次真实报告为准。

NuGet 发布由独立 CD 执行主干标签验证、审批、推送及公开内容核验。版本不可覆盖，重试使用原构建归档；CHANGELOG 是版本说明的评审来源，README 自动区域只生成客观包信息，不自动编写能力说明。

• 源码导览与文档入口
• 构建与 NuGet 发布
• CI/CD 对照审查
• 贡献指南

许可证

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