Two migrations land on this page: upgrading the package version within .NET 8, and moving an integration from an older Doconut framework (.NET 6, .NET Standard 2.0, .NET Framework 4.7) onto the .NET 8 API.

Upgrading the package version

Update the package (and any plugin packages — keep versions aligned):

bash

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Dicom

Check the license window. A license covers a version range. If the new version falls outside it, opening is blocked — OpenDocumentAsync throws LicenseException (fail-fast); it does not fall back to a watermark, and IsVersionValid turns false. Renew, replace the .lic, and restart the application so AddDoconut() loads the new license.
Rebuild and let NuGet restore the declared dependency versions — don't re-pin System.Text.Json or System.Drawing.Common (see Troubleshooting for the exact errors a downgrade causes).
Smoke-test one document per format family you use.

Migrating from .NET 6 / .NET Standard 2.0

The .NET 8 API is a redesign around DI and async. The mapping:

Concern	.NET 6 / Standard 2.0	.NET 8
Setup	Construct `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + inject `Viewer`
License	Static `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` per plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — one license, auto-discovery for plugin files
Open	`viewer.OpenDocument(...)` (synchronous)	`await viewer.OpenDocumentAsync(...)`
Close	`viewer.CloseDocument()` or `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` is not `IDisposable`
Lifetime	`Viewer` implements `IDisposable`, holds the open document	`Viewer` is stateless; sessions live in the cache under tokens
Converter	`viewer.Converter` property	The Converter plugin (`AddPlugin<ConverterPlugin>()`) + the `DocumentConverter` service
Config classes	`Doconut.Configs.View.*` namespaces	All in the `Doconut` namespace
Middleware	Manual handler wiring	`app.UseDoconutResources()` + `app.UseDoconut()`

A typical before/after:

text

// .NET 6 (old API, shown for contrast — not valid on .NET 8)
using var viewer = new Viewer(cache, httpContextAccessor, "wwwroot/Doconut.lic");
var token = viewer.OpenDocument(path, new PdfConfig { AllowSearch = true }, new DocOptions());

csharp

// .NET 8 — Viewer injected, license configured once in AddDoconut()
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Migrating from .NET Framework 4.7 (Web Forms)

The 4.7 Viewer is a WebControl; .NET 8 replaces the control model with middleware + a DI service:

The <doconut:DocViewer runat=server> control disappears — the page hosts the widget div pair and your endpoint returns the token (Quick Start shows the pattern).
Static license methods → DoconutOptions license sources.
Synchronous OpenDocument → await OpenDocumentAsync.
Viewer.ReferenceScripts() / ReferenceCss() exist in both worlds — the .NET 8 versions take ScriptConfig/CssConfig objects and are license-gated.
Control properties (ShowThumbs, PageZoom, FixedZoom, …) → the same names on ViewerConfig / the docViewer JS options.
Export methods returning byte[] → the async annotation-export APIs on Viewer.

Plan this one as a rewrite of the hosting layer around an unchanged concept: open → token → widget.

Naming note

In all frameworks the class is Viewer — if you find DocumentViewer in old snippets or third-party articles, that type never existed in the SDK.

Migration checklist

Swap packages; align plugin package versions.
Move license setup into AddDoconut(); delete static license calls.
Make open calls async; replace Dispose/parameterless CloseDocument with CloseDocument(token).
Replace viewer.Converter usages with the Converter plugin registration + DocumentConverter.
Re-test the security path: AddSession()/UseSession() are now required with default security.