DoconutOptions

DoconutOptions (namespace Doconut) is the single configuration object for the whole SDK. You configure it once, in the callback you pass to DoconutHost.Initialize in Application_Start.

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

Properties

License precedence: LicenseStream → LicenseContent → LicensePath → automatic discovery (see License Setup).

Methods

AddPlugin<TPlugin>()

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

Registers a plugin (Converter, DICOM). Fluent — returns the options instance. Annotation and Search are built-in licensed features and do not use it.

If no active license grants the plugin's capability, DoconutHost.Initialize throws InvalidOperationException from Application_Start, and the site answers every request with an empty 500 until that is fixed; the message is in the Windows event log (see Plugin System).

Add…Widget()

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

The drop-in widgets are off by default. Each Add…Widget() call switches on that widget's endpoints on DocImage.axd, and requires the matching plugin to be registered. The resource module serves the widget's script whether or not you enabled it, so a widget that loads and paints but answers 404 on its first action is missing this call. The Converter widget is documented in Converter Plugin.

RegisterViewer(extension, factory, defaultConfig?)

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

DoconutHost.Initialize validates the options before building anything:

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 is checked even though System.Web never uses it, so leave it at its default. Like every exception thrown from Application_Start, a validation failure shows up as an empty 500 on every request, with the message in the Windows event log.

Common configurations

// Production: explicit license, everything else at its secure default.
public static void ProductionLicense() =>
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
    });

// Custom resource path (e.g. to avoid a route conflict). Keep the viewer's ResPath and any MVC
// IgnoreRoute in step with it: "/docs-assets" means ResPath: 'docs-assets/images'.
public static void CustomResourcePath() =>
    Doconut.DoconutHost.Initialize(options =>
    {
        options.ResourcesPath = "/docs-assets";
    });

When you change ResourcesPath, change three things together: the option, the widget's ResPath ('docs-assets/images' for "/docs-assets"), and, in MVC, the IgnoreRoute for the resource path (routes.IgnoreRoute("docs-assets/{*pathInfo}")). The DocImage.axd endpoint does not move: its path is set by the handler's path attribute in Web.config.