使用 Doconut 的 .NET 服务器端文档转换

介绍

服务器端文档转换使应用程序能够在不自动化 Microsoft Office 或将源文件发送到独立在线转换服务的情况下生成标准化输出。这可以简化文档门户、后台任务和受控导出工作流——但宿主应用仍然负责访问控制、存储、保留、监控以及结果的交付。

Doconut 的 .NET 8 转换插件通过依赖注入的 DocumentConverter 服务公开转换功能。本指南侧重于当前的注册方式和 API 模型，并避免将转换与查看器会话耦合。

安装匹配的包

安装基础查看器和转换器包：

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Converter

确保两个包使用相同的发布版本。当可重复构建很重要时，在项目文件中固定版本或向两个命令传递相同的 --version 参数。

注册转换插件

插件在 AddDoconut 选项回调中注册。没有单独的 AddConverter() 注册方法：

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "doconut.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

应用程序必须使用授予转换功能的许可证。在接受转换任务之前解决启动和授权错误；不要将其推迟到后台队列中，以免诊断困难。

从 C# 转换文件

将 DocumentConverter 注入拥有转换请求的端点或服务中。转换器的构造函数是 internal 的，应用代码不应直接实例化它。

app.MapPost("/api/convert", async (
    DocumentConverter converter,
    CancellationToken ct) =>
{
    await using Stream pdf = await converter.ConvertAsync(
        "documents/contract.docx",
        ConversionTarget.Pdf,
        ct: ct);

    using var copy = new MemoryStream();
    await pdf.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "contract.pdf");
});

返回的流是可定位的，且位于起始位置。调用方拥有该流，应在复制或返回内容后进行释放。

转换上传的流

流重载需要源文件的扩展名（包括前导点），因为转换器使用它来解析源格式：

app.MapPost("/api/convert-upload", async (
    IFormFile file,
    DocumentConverter converter,
    CancellationToken ct) =>
{
    var extension = Path.GetExtension(file.FileName);
    await using var source = file.OpenReadStream();
    await using Stream output = await converter.ConvertAsync(
        source,
        extension,
        ConversionTarget.Pdf,
        password: null,
        ct: ct);

    using var copy = new MemoryStream();
    await output.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "converted.pdf");
});

将文件名和扩展名视为不可信输入。强制上传限制，验证源类型，授权请求用户，并避免使用提交的文件名作为存储路径。

根据实际能力选择目标

插件公开了 ConversionTarget 枚举，但并非每种源格式都能生成每个目标。自定义 UI 应仅显示上传源文件允许的目标，而不是展示所有枚举值。

使用 Doconut 的可选转换小部件时，其打开响应包含 allowedTargets。请将该响应作为当前文件的真实来源。

将后台转换设计为应用工作流

转换器可以从应用服务或队列工作者中调用。一个健壮的任务通常包括：

经过身份验证的请求，记录源文件和期望的目标。
队列消息包含应用作业 ID，而非原始凭证。
工作者通过授权的存储抽象获取源文件。
带有取消功能的受限转换操作。
具有明确保留规则的持久化输出存储。
状态更新不暴露内部路径或敏感异常细节。

在确定工作者数量之前，使用具有代表性的文档测量并发度。转换成本因源格式、文档复杂度、字体、图像以及输出目标而异。

精准维护安全声明

在 .NET 应用内部运行转换器意味着转换操作不需要 Microsoft Office 自动化或独立的在线转换 API。但这并不自动保证整个系统的隐私、合规、删除或加密。

这些属性取决于应用程序如何对用户进行身份验证、获取源文件、配置存储、保护日志、分发输出以及删除临时或保留数据。

运营检查清单

保持 Doconut.NET8 与 Doconut.NET8.Converter 版本一致。
在服务配置期间注册 ConverterPlugin。
通过依赖注入解析 DocumentConverter。
在流源扩展名中包含前导点。
释放源流和结果流。
使用取消机制和应用级文件大小限制。
验证源到目标的支持情况，而不是假设所有组合都可用。
使用具有代表性的文件测试保真度和资源使用情况。
在应用代码中维护存储、授权、审计和保留决策。

请参阅官方 Doconut 转换插件概览和 Doconut 文档以获取当前产品和集成信息。