Installation

Doconut.NETFramework hosts the Doconut viewer in a classic ASP.NET application on .NET Framework 4.7.2 — IIS or IIS Express, MVC 5 or Web Forms. Setup has three parts: the NuGet package, two registrations in Web.config, and one call in Global.asax. This page covers all three; Quick Start then puts a document on a page.

Requirements

• The web project targets .NET Framework 4.7.2 or later. A 4.7 project cannot consume this package; retarget it first.
• The site runs in the integrated pipeline (the default for IIS and IIS Express application pools).

This page covers Doconut.NETFramework 26.9.0 and later. Versions 26.8.0 and earlier targeted .NET Framework 4.7 with a different API; that line is discontinued. Updating an existing application across that boundary is covered in Migration.

Install the package

From the Package Manager Console:

Install-Package Doconut.NETFramework

Or, in an SDK-style project:

dotnet add package Doconut.NETFramework

The rendering engine is embedded in the package: there is no separate engine assembly to reference, copy, or deploy. Optional capabilities ship as their own packages — for example Doconut.NETFramework.Converter and Doconut.NETFramework.Dicom — and each one needs a license that grants it (see Plugin System).

Configure Web.config

Doconut serves two kinds of request, and IIS routes both through Web.config:

• DocImage.axd — the viewer's page, thumbnail, search, and annotation endpoint, served by Doconut.DocImageHandler.
• /doconut-res/* — the viewer's own scripts, stylesheets, and icons, embedded in the assembly and served by Doconut.DoconutResourceModule.

Add both, plus the settings they depend on:

<configuration>
  <system.web>
    <!-- MVC 5 only: Razor compiles views at run time and needs the netstandard facade. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength is in KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Read .cshtml and .aspx files as UTF-8, not as the server's ANSI code page. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength is in BYTES: the same 200 MB. -->
        <requestLimits maxAllowedContentLength="209715200" />
      </requestFiltering>
    </security>
    <modules runAllManagedModulesForAllRequests="true">
      <add name="DoconutResourceModule" type="Doconut.DoconutResourceModule, Doconut" />
    </modules>
    <handlers>
      <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd"
           type="Doconut.DocImageHandler, Doconut" />
    </handlers>
  </system.webServer>
</configuration>

Each line prevents a failure that raises no exception:

• verb="GET,HEAD,POST" — keep HEAD. The viewer sends a HEAD request for page 1 to detect animated images. Without the verb, IIS answers 404 before the handler runs: documents still display, but animation detection never works and the browser console fills with 404s.
• runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css, and .png look like static files, and IIS would hand them to its static file handler before the resource module sees them. The result is a viewer with no scripts or icons.
• <globalization fileEncoding="utf-8"> — page files saved as UTF-8 without a byte-order mark are otherwise read with the server's ANSI code page, so every non-ASCII character reaches the browser double-encoded (an em dash shows as —). The file is correct on disk, and the page still declares <meta charset="utf-8">.
• The netstandard assembly (MVC 5) — Razor compiles views when they are first requested, with its own reference list that does not include this facade. A view that does anything dynamic beyond a plain member access then fails with CS0012 and answers an empty 500, and only the pages that trip it fail. The compiler error appears only in the Windows event log (source ASP.NET). Web Forms applications do not need this line.
• Upload limits — ASP.NET reads the whole request body before any handler runs, so an upload above these limits is rejected by IIS with its own error page. Keep maxRequestLength (kilobytes) and maxAllowedContentLength (bytes) in step, and above the largest file your users open or upload.

Two more settings matter, and both are usually right already:

• Session state stays on. By default a page is served only to the ASP.NET session that opened the document, so the site must not set <sessionState mode="Off" />. See Sessions & Security.
• Binding redirects. Keep the <runtime> binding redirects that NuGet writes into Web.config. In an SDK-style project, copy them from the generated bin\<YourApp>.dll.config, because classic ASP.NET reads redirects only from Web.config. A redirect that names a version missing from bin\ stops the whole application with an empty 500 at startup.

Register Doconut in Global.asax

There is no builder and no middleware pipeline in System.Web. Doconut is composed once per worker process by DoconutHost.Initialize in Application_Start, and released by DoconutHost.Shutdown in Application_End:

// Global.asax.cs
protected void Application_Start()
{
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    });
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}

DoconutHost.Initialize builds the services the handler, the resource module, and your own code use. Your code reaches them through DoconutHost.Services (see DoconutHost). Only the first call configures anything; a second call is ignored. In an MVC application, also keep the two Doconut paths out of routing — Quick Start shows the complete Application_Start.

All options

DoconutOptions accepts the following settable properties. Every one is optional.

When more than one license source is set, LicenseStream beats LicenseContent, which beats LicensePath, which beats automatic discovery — see License Setup.

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // where the viewer's JS/CSS/images are served from
    options.UnsafeMode      = false;          // keep session security on
    options.ShowDoconutInfo = false;
});
// The page endpoint is not an option here: it is the DocImage.axd handler declared in Web.config.

Next steps

• Quick Start — open a document and render it in the browser, in MVC 5 or Web Forms.
• License Setup — where Doconut looks for your license file.