Zwei Migrationen werden auf dieser Seite behandelt: Aktualisierung der Paketversion innerhalb von .NET 8 und Verschieben einer Integration von einem älteren Doconut‑Framework (.NET 6, .NET Standard 2.0, .NET Framework 4.7) auf die .NET 8‑API.

Aktualisieren der Paketversion

Aktualisieren Sie das Paket (und alle Plugin‑Pakete — halten Sie die Versionen abgestimmt):

bash

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

Überprüfen Sie das Lizenzfenster. Eine Lizenz deckt einen Versionsbereich ab. Wenn die neue Version außerhalb liegt, wird das Öffnen blockiert — OpenDocumentAsync wirft LicenseException (Fail‑Fast); es fällt nicht auf ein Wasserzeichen zurück, und IsVersionValid wird zu false. Erneuern Sie die Lizenz, ersetzen Sie die .lic und starten Sie die Anwendung neu, damit AddDoconut() die neue Lizenz lädt.
Erstellen Sie neu und lassen Sie NuGet die deklarierten Abhängigkeitsversionen wiederherstellen — pinnen Sie System.Text.Json oder System.Drawing.Common nicht erneut (siehe Fehlersuche für die genauen Fehler, die ein Downgrade verursacht).
Führen Sie einen Smoke‑Test mit einem Dokument pro von Ihnen genutzter Formatfamilie durch.

Migration von .NET 6 / .NET Standard 2.0

Die .NET 8‑API ist ein Redesign rund um DI und Async. Die Zuordnung:

Thema	.NET 6 / Standard 2.0	.NET 8
Setup	Erstelle `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + injiziere `Viewer`
License	Statisch `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` pro Plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — eine Lizenz, automatische Erkennung für Plugin‑Dateien
Open	`viewer.OpenDocument(...)` (synchron)	`await viewer.OpenDocumentAsync(...)`
Close	`viewer.CloseDocument()` oder `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` ist nicht `IDisposable`
Lifetime	`Viewer` implementiert `IDisposable`, hält das geöffnete Dokument	`Viewer` ist zustandslos; Sitzungen leben im Cache unter Tokens
Converter	`viewer.Converter` Eigenschaft	Das Converter‑Plugin (`AddPlugin<ConverterPlugin>()`) + der `DocumentConverter` Service
Config classes	`Doconut.Configs.View.*` Namespaces	Alle im `Doconut` Namespace
Middleware	Manuelle Handler‑Verkabelung	`app.UseDoconutResources()` + `app.UseDoconut()`

Ein typisches Vorher/Nachher:

text

// .NET 6 (alte API, zum Vergleich gezeigt — nicht gültig unter .NET 8)
using var viewer = new Viewer(cache, httpContextAccessor, "wwwroot/Doconut.Viewer.lic");
var token = viewer.OpenDocument(path, new PdfConfig { AllowSearch = true }, new DocOptions());

csharp

// .NET 8 — Viewer injiziert, Lizenz einmalig in AddDoconut() konfiguriert
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Migration von .NET Framework 4.7 (Web Forms)

Der 4.7 Viewer ist ein WebControl; .NET 8 ersetzt das Steuerungsmodell durch Middleware + einen DI‑Service:

Das <doconut:DocViewer runat=server>‑Steuerelement verschwindet — die Seite hostet das Widget‑div‑Paar und Ihr Endpunkt gibt das Token zurück (Quick Start zeigt das Muster).
Statische Lizenzmethoden → DoconutOptions Lizenzquellen.
Synchrones OpenDocument → await OpenDocumentAsync.
Viewer.ReferenceScripts() / ReferenceCss() existieren in beiden Welten — die .NET 8‑Versionen akzeptieren ScriptConfig/CssConfig‑Objekte und sind lizenzgesteuert.
Steuerelementeigenschaften (ShowThumbs, PageZoom, FixedZoom, …) → dieselben Namen in ViewerConfig / den docViewer‑JS‑Optionen.
Export‑Methoden, die byte[] zurückgeben → die asynchronen Annotation‑Export‑APIs im Viewer.

Planen Sie dies als Neuschreibung der Hosting‑Schicht um ein unverändertes Konzept: öffnen → Token → Widget.

Hinweis zur Benennung

In allen Frameworks ist die Klasse Viewer — wenn Sie DocumentViewer in alten Code‑Snippets oder Drittanbieter‑Artikeln finden, dieser Typ hat im SDK nie existiert.

Migrations‑Checkliste

Pakete austauschen; Plugin‑Paketversionen angleichen.
Lizenz‑Setup in AddDoconut() verschieben; statische Lizenzaufrufe löschen.
Öffnungsaufrufe asynchron machen; Dispose/parameterloses CloseDocument durch CloseDocument(token) ersetzen.
viewer.Converter‑Verwendungen durch die Registrierung des Converter‑Plugins + DocumentConverter ersetzen.
Den Sicherheitsweg erneut testen: AddSession()/UseSession() sind jetzt mit Standard‑Sicherheit erforderlich (plus AddDistributedMemoryCache() in einer Minimal‑API‑App).