License Setup

Without a license, Doconut still renders documents — every page just carries an evaluation watermark. This page covers the four ways to supply a license in Global.asax, where Doconut looks when you supply none, and what happens when a plugin's license is missing.

Four ways to supply a license

There are three explicit sources on DoconutOptions — a file path, a stream, or raw content — plus automatic discovery when none of them is set. All of them are read once, in DoconutHost.Initialize. When more than one is set, the precedence is exact:

LicenseStream beats LicenseContent beats LicensePath beats automatic discovery.

By path

Give LicensePath a full path. A relative path is resolved against the process's current directory, and under IIS that is the worker process's own folder, not your site. HostingEnvironment.MapPath turns a site-relative path into a full one:

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
});

If the file does not exist, Doconut does not throw and does not fall back to automatic discovery: it loads no license, and the viewer watermarks. The per-plugin license files in the same folder (Doconut.Viewer.<Capability>.lic) are read with it, so LicensePath and AddPlugin<...>() work together when the plugin licenses sit beside the base license.

By stream

LicenseStream is read once, at startup — useful when the license comes from an embedded resource or a secret store rather than a file on disk.

// Precedence: LicenseStream > LicenseContent > LicensePath > auto-search.
Doconut.DoconutHost.Initialize(options =>
{
    options.LicenseStream = licenseStream;
});

By content

LicenseContent takes the license text itself — from an environment variable, a database, or a secret store — so no license file has to be deployed with the site.

// License XML from a database, an environment variable or a secret store -
// no file on disk. Beaten only by LicenseStream.
Doconut.DoconutHost.Initialize(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

Automatic discovery

Set none of the three, and Doconut searches for the license itself:

// Configure nothing, and Doconut searches for the license itself, in this order:
//   1. {CurrentDirectory}\wwwroot
//   2. {AppContext.BaseDirectory}\wwwroot   (under IIS: the site's root folder)
// It looks for Doconut.lic first, then Doconut.Viewer.lic, plus any per-plugin
// Doconut.Viewer.<Capability>.lic files alongside it.
Doconut.DoconutHost.Initialize();

The two folders, in order, and the files looked for:

1. {CurrentDirectory}\wwwroot
2. {AppContext.BaseDirectory}\wwwroot

In each folder:
  Doconut.lic                        — if found, this is the only file read
  Doconut.Viewer.lic                 — base viewer license
  Doconut.Viewer.<Capability>.lic    — per-plugin licenses, read only next to Doconut.Viewer.lic

Under IIS and IIS Express, AppContext.BaseDirectory is the site's root folder — the one that holds Web.config — not its bin folder. So the license belongs in wwwroot under the site root:

MySite\
  Web.config
  Global.asax
  bin\
  wwwroot\
    Doconut.Viewer.lic
    Doconut.Viewer.Converter.lic

In the project, keep wwwroot\*.lic beside Web.config and deploy the folder with the site. No build step has to copy it anywhere. A .lic anywhere else — in bin\, next to Web.config, or in a subfolder of wwwroot — is never read.

Keep .lic files out of source control. Deploy them alongside the site, or supply the license through LicenseContent or LicenseStream from your secret store.

What happens without a license

A missing license does not throw. DoconutHost.Initialize succeeds, the site starts, and the viewer runs, but every page carries an evaluation watermark and no optional capability is granted.

A license file that is found but rejected is different. An invalid signature, tampering, or a build outside the license's version window makes OpenDocumentAsync throw LicenseException with the reason.

Plugins need their license at startup

Registering a plugin whose capability no license grants stops the application at startup. DoconutHost.Initialize throws in Application_Start:

InvalidOperationException: The Converter plugin is registered via AddPlugin but no active
license grants Converter. Remove the AddPlugin<...>() call or install a license (or
trial/demo) that includes Converter.

Under System.Web, you do not see that message in the browser. Every request to the site answers an empty 500 — no error page, no stack trace, nothing in the IIS log. The exception is recorded only in the Windows event log (Application log, source ASP.NET). If the whole site stops responding right after you add an AddPlugin line, check the license files in wwwroot before the code: the plugin's Doconut.Viewer.<Capability>.lic has to sit next to Doconut.Viewer.lic, and without the base license the plugin files are not read at all.

Verify the loaded license

IDoconutLicenseService is the same source of truth the SDK uses. Resolve it from DoconutHost.Services to expose an authenticated diagnostic endpoint or drive feature flags — never return license contents:

// GET /License/Status
public ActionResult Status()
{
    var license = Doconut.DoconutHost.Services.GetRequiredService<IDoconutLicenseService>();

    return Json(new
    {
        viewer     = license.IsViewerLicensed || license.IsTemporary,
        temporary  = license.IsTemporary,
        search     = license.IsCapabilityGranted(LicenseCapability.Search),
        annotation = license.IsCapabilityGranted(LicenseCapability.Annotation),
        converter  = license.HasConverter,
        dicom      = license.HasDicom
    }, JsonRequestBehavior.AllowGet);
}

The license is read once, in DoconutHost.Initialize. After replacing a license file, recycle the application pool (or touch Web.config) so Application_Start runs again.

Troubleshooting

Next steps

• Licensing — capabilities, and how to check them at run time.
• Troubleshooting — watermarks, startup failures, and other symptoms.