DoconutOptions

配置 Doconut 服务

DoconutOptions（命名空间 Doconut）是整个 SDK 唯一的配置对象。您只需在 AddDoconut() 中配置一次，它会以单例方式注册。

这既是位置的改变，也是形态的改变。在之前的 .NET Standard 库中，DoconutOptions 实例在管道阶段构造，并传递给 UseDoconut(new DoconutOptions { … })。而这里的 middleware 完全不接受任何选项——所有设置都在服务注册时完成。

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

属性

TypePropertyDefaultDescription
boolShowDoconutInfofalse当为 true 时，未携带令牌的 middleware 请求会返回版本横幅而不是 404。可用于快速检查；在生产环境中保持 false。
boolUnsafeModefalse当为 true 时，跳过页面请求的 ASP.NET 会话安全检查。在单节点生产环境中保持 false（参见 核心概念 → 会话与安全）。之前写作 UnSafeMode。
stringMiddlewarePath"/doconut"页面‑图片端点的协调值。会进行验证，但不会挂载管道分支；请保持其与实际的 UseDoconut() 映射以及客户端 BasePath 对齐。
stringResourcesPath"/doconut-res"嵌入式 JS/CSS/图片/字体资源的 URL 路径前缀。
stringLicensePath""许可证文件的路径。为空 → 使用下一个许可证来源，然后自动发现；若仍未找到 → 进入带水印的评估状态，且无任何功能。
stringLicenseContent""原始 XML 许可证内容（数据库、环境变量、密钥管理器）。优先于 LicensePath。
Stream?LicenseStreamnull以流形式提供的许可证，在启动时读取一次。优先于上述两种来源。
boolResetLicensefalse保留的兼容性标志。当前实现不使用它；更换许可证后请重启应用程序。
DoconutPluginRegistryPluginRegistry—只读注册表，用于收集插件贡献，由查看器工厂使用。通过 AddPlugin<T>() 填充。

许可证优先级（在服务注册时强制执行）：LicenseStream → LicenseContent → LicensePath → 自动发现（参见 入门指南 → 许可证设置）。

方法

AddPlugin()

text
DoconutOptions AddPlugin<TPlugin>() where TPlugin : IDoconutPlugin, new()

此方法用于已发布的可选 Converter 和 DICOM 包。标注和普通搜索是内置的授权功能，不需要使用 AddPlugin<TPlugin>()。

注册一个第一方插件（Converter、DICOM）。采用流式调用——返回 options 实例。AddDoconut() 会在缺少许可证、使用旧版 TRIAL 文件，或付费许可证未授予插件功能时抛出 InvalidOperationException。临时/演示注册在过期后仍会保留，并受运行时门控约束（参见 核心概念 → 插件系统）。

可选的 Converter 小部件通过 AddConverterWidget() 启用，并通过只读的 ConverterWidget 属性暴露；其选项在 Converter Plugin 页面（插件 → Converter 插件）中有文档说明。

RegisterViewer(extension, factory, defaultConfig?)

text
DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — leading dot optional
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

为文件扩展名注册一个 自定义查看器。自定义查看器优先于内置和插件查看器，且不受许可证限制。当省略 defaultConfig 且文档在未提供显式配置时，将使用 ImageConfig。

若扩展名为空则抛出 ArgumentException（Extension must be a non-empty file extension.），若工厂为 null 则抛出 ArgumentNullException。

启动验证

AddDoconut() 对选项进行 快速失败 验证，因此配置错误会在启动时以明确的异常出现，而不是在请求时产生令人困惑的 404。

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

常见配置

csharp
// Production: explicit license, everything locked down (all security defaults)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Custom paths (e.g. to avoid a route conflict)
builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});

更改 ResourcesPath 时，请保持客户端小部件的 ResPath 同步（参见 ViewerConfig）。这是两个在客户端会导致失败且不报错的设置之一。

MiddlewarePath 并不是自动的 ASP.NET Core 路由映射器。如果 Doconut 只应在自定义前缀下响应，请在该分支上挂载 UseDoconut()（例如使用 app.Map("/docs-engine", branch => branch.UseDoconut())），并将客户端的 BasePath 设置为相同的 URL。参考应用程序则在 MapWhen 分支上保持历史的 DocImage.axd 请求形式，BasePath 为 '/'。

此页面对您有帮助吗？