Viewer

Viewer (namespace Doconut) is the public entry point for opening documents from Razor pages, MVC controllers, Blazor components, or minimal APIs. It is sealed, registered as a transient service by AddDoconut(), and resolved via constructor injection — never construct it directly.

The previous .NET Standard library exposed a public constructor taking the memory cache, the HTTP context accessor, and one or more license paths. That constructor is gone; the service graph supplies those dependencies.

Viewer holds no per-request state and intentionally does not implement IDisposable: document sessions live independently in the session cache, so disposing the service could never tear down an open document (see Core Concepts → How the Viewer Works).

OpenDocumentAsync

Opens a document and returns the session token the client widget uses for all subsequent requests. Every open is asynchronous — there is no synchronous OpenDocument.

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Exceptions to handle:

• LicenseException — a found license is rejected (the message carries the rejection reason), or the format needs a plugin capability that is no longer granted. Calendar expiry without a rejection message degrades to watermarked rendering instead of throwing.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — the file content is corrupt or doesn't match its extension.

CloseDocument

void CloseDocument(string token)

Removes the session from the cache (disposing the document engine immediately), deletes the security marker, and revokes the access grant. Optional — sliding expiration performs the same cleanup — but recommended for large documents.

GetPageCount

int GetPageCount(string token)

Total pages of the open session. Throws if the token is unknown or expired.

Capability flags

Use these in a Razor view to render a licensed Ribbon only when the server will actually serve it — see Quick Start.

DocOptions

Per-open, format-independent options (namespace Doconut):

The class also exposes specialized properties that are intentionally outside the normal single-host viewing flow:

Custom watermark

DocOptions.Watermark uses six tilde-separated fields. An optional leading ^ requests the all-corners layout:

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

The parser expects exactly six fields after the optional ^. An invalid definition is replaced by the SDK's visible Invalid Watermark fallback instead of silently disappearing.

License decision

The same decision is applied to served page images and annotation exports. Animated GIF output is stamped frame by frame. A custom watermark is therefore a licensed application feature, not a way to replace or suppress the evaluation watermark.

Annotations API

Server-side annotation loading and export. The full walkthrough lives in Guides → Annotations; the surface is:

Every one of these takes the session token. The previous library's session-free GetAnnotationManager(pageWidth, pageHeight) shape survives for building annotations outside a session, but loading them still requires a token.

DICOM metadata

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

The method is present for API alignment, but this package cannot supply technical DICOM tags: the metadata reader ships only a .NET 8 build. It returns null for DICOM and non-DICOM sessions; on a DICOM session it also writes a one-time warning explaining the platform limitation. Page, frame, and animation rendering remain supported.

Resource helpers — ReferenceCss / ReferenceScripts

Emit the <link>/<script> tags for the embedded resources served by UseDoconutResources(), in correct dependency order. Bundles for license-gated features such as search and annotation are emitted only when the license enables them, keeping the client UI consistent with server behavior.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

ScriptConfig flags: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts and IncludeSearchBar (search-gated), IncludeAnnotationScripts and IncludeAnnotationBar (annotation-gated).

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

These helpers are the supported way to deliver the browser resources. Applications that copied docViewer.js, documentLinks.js, and docViewer.UI.js into wwwroot should remove those copies once the page renders from the emitted tags.