使用 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.Viewer.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 文档以获取最新的产品和集成信息。