DoconutOptions

配置 Doconut 服务

DoconutOptions（命名空间 Doconut）是整个 SDK 的唯一配置对象。您只需在传递给 DoconutHost.Initialize 的回调中（位于 Application_Start）进行一次配置。

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

属性

类型属性默认描述
boolUnsafeModefalse当 false，DocImage.axd 仅向打开文档的 ASP.NET 会话（或在集群中，向拥有签名票据的浏览器）提供页面。当 true，任何携带令牌的请求都会被提供。保持 false — 请参阅 会话与安全。
boolShowDoconutInfofalse当 true，未携带令牌的 DocImage.axd 请求会返回 Doconut <version> is running on <host> 而不是 404。可用作快速检查；在生产环境中保持 false。
stringResourcesPath"/doconut-res"资源模块提供嵌入式脚本、样式和图像的 URL 前缀。
stringLicensePath""许可证文件的完整路径。为空 → 使用下一个许可证来源，然后自动发现；若未找到 → 以水印评估模式运行，且无任何功能。
stringLicenseContent""原始许可证内容（数据库、环境变量、密钥存储）。优先于 LicensePath。
Stream?LicenseStreamnull许可证作为流，在启动时读取一次。优先于其他两种来源。
stringMiddlewarePath"/doconut"System.Web 不使用。页面端点始终是 Web.config 中声明的 DocImage.axd 处理程序。该值仍在启动时进行验证（见下文）。
boolResetLicensefalse不使用。许可证在 DoconutHost.Initialize 中读取一次；更换许可证后请回收应用程序池。
DoconutPluginRegistryPluginRegistry—插件贡献的只读注册表，由 AddPlugin<T>() 填充。

许可证优先级：LicenseStream → LicenseContent → LicensePath → 自动发现（参见 许可证设置）。

方法

AddPlugin<TPlugin>()

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

注册一个插件（Converter、DICOM）。采用流式调用——返回 选项 实例。Annotation 和 Search 是内置的授权功能，不使用此方法。

如果没有有效许可证授予插件的功能，DoconutHost.Initialize 会从 Application_Start 抛出 InvalidOperationException，并且站点会对所有请求返回空的 500，直至问题解决；相关信息记录在 Windows 事件日志中（参见 插件系统）。

Add…Widget()

text
DoconutOptions AddConverterWidget(Action<ConverterWidgetOptions>? configure = null)

这些即插即用的小部件默认 关闭。每次调用 Add…Widget() 会在 DocImage.axd 上打开该小部件的端点，并且需要已注册相应的插件。资源模块始终提供小部件的脚本，无论是否已启用，因此如果小部件能够加载并渲染，但在首次操作时返回 404，则说明缺少此调用。Converter 小部件的文档位于 Converter 插件。

RegisterViewer(extension, factory, defaultConfig?)

text
DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — 前导点可选
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

为文件扩展名注册一个 自定义查看器。自定义查看器优先于内置和插件查看器，并且不受许可证限制。当省略 defaultConfig 且文档在没有显式配置的情况下打开时，将使用 ImageConfig。

对于空扩展名会抛出 ArgumentException（Extension must be a non-empty file extension.），对于空工厂会抛出 ArgumentNullException。

启动验证

DoconutHost.Initialize 在构建任何内容之前验证选项：

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.

MiddlewarePath 会被检查，尽管 System.Web 从不使用它，因此请保持默认。与从 Application_Start 抛出的所有异常一样，验证失败会在每个请求上显示为空的 500，并在 Windows 事件日志中记录相应信息。

常见配置

csharp
// Production: 明确的许可证，其他所有均使用安全默认设置。
public static void ProductionLicense() =>
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
    });

// Custom resource path (例如，为避免路由冲突)。保留 viewer 的 ResPath 和任何 MVC
// IgnoreRoute 与其同步："/docs-assets" 表示 ResPath：'docs-assets/images'。
public static void CustomResourcePath() =>
    Doconut.DoconutHost.Initialize(options =>
    {
        options.ResourcesPath = "/docs-assets";
    });

当您更改 ResourcesPath 时，请同时更改三项内容：该选项、小部件的 ResPath（针对 "/docs-assets" 的 'docs-assets/images'），以及在 MVC 中用于资源路径的 IgnoreRoute（routes.IgnoreRoute("docs-assets/{*pathInfo}")）。DocImage.axd 端点位置不变：其路径由 Web.config 中处理程序的 path 属性设置。

此页面对您有帮助吗？