Installation
Add Doconut to your .NET 8 project
The base Doconut viewer for .NET 8 ships as one NuGet package that plugs into any ASP.NET Core application. Optional plugins use separate packages. This page installs the base package and registers the middleware — the minimum needed before your first render.
Requirements
The package runs on these platforms:
| Platform | Supported |
|---|---|
| Windows x64 / x86 | Yes |
Linux x64, glibc-based (Debian, Ubuntu, the official mcr.microsoft.com/dotnet/aspnet:8.0 image) | Yes |
| Alpine and other musl-based distributions | No |
| macOS | No |
On Linux, install the font configuration library before the first document opens:
apt-get update && apt-get install -y libfontconfig1On RHEL, Fedora and similar distributions the package is fontconfig (dnf install -y fontconfig). That is the only system package Doconut needs: the native libraries it uses ship inside the NuGet package, and libgdiplus is not required. Pages are drawn with the fonts installed on the server, so see Troubleshooting for fonts and the Linux error messages.
Install the package
dotnet add package Doconut.NET8The unversioned command installs the latest stable release. To pin the release this documentation describes, pass the version as a separate option:
dotnet add package Doconut.NET8 --version 26.10.0Doconut.NET8 is the package ID. The version suffix belongs to the downloaded
Doconut.NET8.<version>.nupkg filename and is not part of the ID.
Register Doconut
AddDoconut() is the only registration entry point — there is a single overload, and it wires the Viewer service, the license service, and the rendering infrastructure into the DI container.
Two middleware calls complete the setup, and their order matters: UseDoconutResources() must run before UseDoconut(). UseDoconut() is terminal middleware, so calling it first means every request to a /doconut-res asset never reaches the resources handler and 404s. UseDoconut() answers every request that reaches it, so mount it on its own branch with app.Map. The session wiring is required too — Doconut's default document security validates every page request against ASP.NET session state.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state needs a cache (MVC/Razor Pages already add one)
builder.Services.AddSession(); // Doconut document security rides on ASP.NET session state
app.UseSession(); // call UseSession() before UseDoconut()
app.UseDoconutResources(); // must be registered before UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());All options
DoconutOptions accepts the following settable properties. Every one is optional — the defaults below apply when a property is left unset.
| Property | Default | Description |
|---|---|---|
ShowDoconutInfo | false | When true, a request with no token returns a version banner instead of a 404. Useful as a smoke check; leave off in production. |
UnsafeMode | false | When true, skips the ASP.NET-session security check on page requests. Leave off in production. |
MiddlewarePath | "/doconut" | Coordination value for the page-image endpoint. It is validated, but it does not mount a branch by itself; keep it aligned with the actual UseDoconut() mapping and the client BasePath. |
ResourcesPath | "/doconut-res" | Where the embedded JS/CSS/image resources are served from. |
LicensePath | "" (empty string) | Path to the license file. Empty means fall through to the next source, then auto-search. |
LicenseContent | "" (empty string) | Raw license content — from an environment variable, a secret manager, or a database. |
LicenseStream | null | License as a stream, read once at startup. |
ResetLicense | false | Reserved compatibility flag. The current .NET 8 services read the license during AddDoconut(); restart the app after replacing a license. |
MaxConcurrentEditorSessions | 200 | Maximum number of live editor sessions (documents opened with DocOptions.EditMode). Above it, the least-recently-used idle editor session is closed. Normal viewer sessions are never counted. 0 or a negative value means no cap. |
EditorSnapshotEveryOps | 50 | With editor persistence enabled (AddDoconutEditorPersistence), snapshot the live document every N recorded changes. 0 or a negative value never snapshots mid-session. No effect when persistence is disabled. |
License precedence when more than one source is set: LicenseStream beats LicenseContent beats LicensePath beats auto-search — see License Setup.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.MiddlewarePath = "/doconut"; // coordinate with app mapping and client BasePath
options.ResourcesPath = "/doconut-res"; // where the viewer's JS/CSS/images are served from
options.UnsafeMode = false; // keep session security on
options.ShowDoconutInfo = false;
});Next steps
- Quick Start — open your first document and render it in the browser.
- License Setup — where Doconut looks for your license file.
Was this page helpful?