DoconutOptions – Doconut Documentation

DoconutOptions (namespace Doconut) is the single configuration object for the whole SDK. You configure it once, inside AddDoconut(), and it is registered as a singleton.

csharp

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

Properties

Type	Property	Default	Description
`bool`	`ShowDoconutInfo`	`false`	When `true`, a middleware request without a token returns a version banner (`Doconut <version> is running on <host>`) instead of 404. Useful as a smoke check; leave `false` in production.
`bool`	`UnsafeMode`	`false`	When `true`, skips the ASP.NET-session security check on page requests. Leave `false` in production (see Core Concepts → Sessions & Security).
`string`	`MiddlewarePath`	`"/doconut"`	Coordination value for the page-image endpoint. It is validated, but does not mount a pipeline branch; keep it aligned with the actual `UseDoconut()` mapping and client `BasePath`.
`string`	`ResourcesPath`	`"/doconut-res"`	URL path prefix for the embedded JS/CSS/image/font resources.
`string`	`LicensePath`	`""`	Path to the license file. Empty → next license source, then auto-discovery; nothing found → watermarked evaluation state with no capabilities.
`string`	`LicenseContent`	`""`	Raw XML license content (database, env var, secret manager). Takes precedence over `LicensePath`.
`Stream?`	`LicenseStream`	`null`	License as a stream, read once at startup. Takes precedence over both other sources.
`bool`	`ResetLicense`	`false`	Reserved compatibility flag. The current .NET 8 implementation does not consume it; restart the application after replacing a license.
`DoconutPluginRegistry`	`PluginRegistry`	—	Read-only registry collecting plugin contributions; consumed by the viewer factory. Populate via `AddPlugin<T>()`.

License precedence (enforced at service registration): LicenseStream → LicenseContent → LicensePath → automatic discovery (see Getting Started → License Setup).

Methods

AddPlugin<TPlugin>()

text

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

Use this method for the released opt-in Converter and DICOM packages. Annotation and normal Search are built-in licensed features and do not use AddPlugin<TPlugin>().

Registers a first-party plugin (Converter, DICOM). Fluent — returns the options instance. AddDoconut() throws InvalidOperationException for a missing license, legacy TRIAL file, or paid license that does not grant the plugin's capability. Temporary/Demo registrations are retained across expiry and become subject to the runtime gate (see Core Concepts → Plugin System).

The opt-in Converter widget is enabled with AddConverterWidget() and surfaced through the read-only ConverterWidget property; its options are documented on the Converter Plugin page (Plugins → Converter Plugin).

RegisterViewer(extension, factory, defaultConfig?)

text

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

Registers a custom viewer for a file extension. Custom viewers take precedence over built-in and plugin viewers and are not license-gated. When defaultConfig is omitted and a document opens without an explicit config, an ImageConfig is used.

Throws ArgumentException (Extension must be a non-empty file extension.) for a blank extension and ArgumentNullException for a null factory.

Startup validation

AddDoconut() validates the options fail-fast, so a misconfiguration surfaces as a clear exception at startup instead of confusing 404s at request time:

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.

Common configurations

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";
});

When you change ResourcesPath, keep the client widget's ResPath in sync (see ViewerConfig).

MiddlewarePath is not an automatic ASP.NET Core route mapper. If Doconut should answer only below a custom prefix, mount UseDoconut() on that branch (for example with app.Map("/docs-engine", branch => branch.UseDoconut())) and set the client BasePath to the same URL.