在 .NET 8 中注册并启用 Doconut 即插即用转换器小部件

即插即用小部件是 Doconut 提供的即用型界面，用于上传文件、执行转换并下载结果。
默认情况下，小部件的三个 ?convert= 端点返回 404；只有在注册 Converter 插件 并且 在 DoconutOptions 上调用 AddConverterWidget() 时，它们才会生效。
下面提供一个完整的、可直接复制的启动配置，满足上述两个要求。

---

1. 前置条件 – 许可证和会话支持

• 许可证 – Converter 插件需要一个授予 Converter 功能的许可证。将文件（例如 Doconut.Viewer.lic）放置在应用可访问的位置，并将 DoconutOptions.LicensePath 指向该文件。
• 会话状态 – Doconut 的安全模型将文档会话令牌存储在 ASP.NET Core 会话中。添加分布式缓存并在中间件配置之前调用 AddSession()。

builder.Services.AddDistributedMemoryCache();   // 会话所需
builder.Services.AddSession();                  // 启用 IDistributedCache 支持的会话

---

2. 注册核心 Doconut 服务

AddDoconut() 是唯一的入口点，用于注入查看器、许可证服务以及插件注册表。

builder.Services.AddDoconut(options =>
{
    // 告诉 Doconut 在哪里可以找到许可证文件。
    options.LicensePath = "Doconut.Viewer.lic";

    // 注册 Converter 插件 – 这也会验证许可证功能。
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

如果许可证 不 包含 Converter 功能，上述调用会抛出 InvalidOperationException，导致应用无法启动。这种快速失败的行为可防止您部署未授权的构建。

---

3. 使用 AddConverterWidget 启用小部件

小部件为可选启用。调用 AddConverterWidget() 会注册三个转换端点（?convert=open、?convert=run、?convert=download），并配置少量客户端设置（最大上传大小、基础路径等）。

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

    // 启用 drop‑in UI 并设置客户端上传限制。
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // 客户端预检查；服务器强制执行其自身限制
    });
});

只有 AddConverterWidget 调用会创建这些端点；静态 JavaScript 文件（doconutConverter.js）始终作为嵌入资源提供，但如果端点缺失，它将无法与服务器通信。

---

4. 按正确顺序配置中间件

提供静态资源的中间件（UseDoconutResources）必须 在 终端查看器中间件（UseDoconut）之前运行。会话中间件也需要提前放置，因为 Doconut 会在每个请求上验证会话。

app.UseSession();           // 必须在 UseDoconut() 之前
app.UseDoconutResources();  // 提供 JS、CSS、图像
app.UseDoconut();           // 处理 ?convert= 和文档页面请求

配置好此管道后，对 /doconut-res/doconutConverter.js 的请求将成功，小部件即可调用 /doconut?convert=open、/doconut?convert=run 和 /doconut?convert=download。

---

5. 小部件的实际工作流程

阶段	服务器端点	典型响应
打开	?convert=open	返回一个 JSON 负载，包含 token、页数、源文件扩展名以及允许的目标格式列表。
运行	?convert=run	启动转换并返回一个 downloadToken、结果页数、建议的文件名，以及指示输出是否带水印的标志。
下载	?convert=download	当客户端访问提供的下载 URL 时，流式传输转换后的文件。

在客户端，小部件会对 widget.MaxUploadMb 进行预上传大小检查。如果文件超过该限制，小部件会中止上传并触发 onError 回调，传递 phase = "open" 和友好的提示信息。服务器会自行强制限制，如果请求绕过客户端检查，将返回 413 Payload Too Large。

---

6. 绑定小部件事件（无需 C# 代码）

所有回调（onReady、onSourceLoaded、onConverted、onError 等）都是由承载小部件的页面提供的 JavaScript 函数。由于问题聚焦于 注册 方面，您无需编写额外的 C# 代码来处理这些回调——端点上线后，小部件会自动调用它们。

---

7. 常见陷阱及规避方法

症状	可能原因	解决方案
404 在 /doconut?convert=open 上出现	缺少 AddConverterWidget()。	按第 3 节所示添加该调用。
应用启动失败，出现 InvalidOperationException（缺少功能）	许可证文件未授予 Converter。	获取包含 Converter 功能的许可证。
会话相关的 500 错误	UseSession() 放在 UseDoconut() 之后或缺少缓存注册。	确保 app.UseSession() 在 app.UseDoconut() 之前运行，并已注册缓存服务。

---

8. 运行应用并观察小部件效果

1. 构建并运行 ASP.NET Core 项目。
2. 打开包含 <div id="doconut-convert"></div> 元素并引入 Doconut 转换器脚本的页面（脚本会自动从 /doconut-res/doconutConverter.js 提供）。
3. 将支持的文件（PDF、DOCX、DWG 等）拖拽到投放区域。
4. 小部件将依次调用 ?convert=open、?convert=run，最后显示指向 ?convert=download 的 下载 链接。

如果三个端点返回 JSON 而非 404，则说明小部件已正确注册，可投入生产使用。

---

下一步： 将上述代码片段添加到您的 Program.cs（或 Startup.cs），确认许可证文件已存在，然后启动应用。即插即用转换器小部件将无需进一步的服务器端修改即可上线。