Migration

Upgrade auf Doconut unter .NET 8

Auf dieser Seite werden zwei Migrationen 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.

Aktualisierung der Paketversion

  1. 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
  1. Ü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 wird nicht zu einem Wasserzeichen zurückgekehrt, 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.
  2. 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).
  3. Führen Sie einen Smoke‑Test mit einem Dokument pro von Ihnen verwendeter Formatfamilie durch.

Migration von .NET 6 / .NET Standard 2.0

Die .NET 8‑API ist ein Neugestaltung rund um DI und asynchronen Betrieb. Die Zuordnung:

Aspekt.NET 6 / Standard 2.0.NET 8
SetupKonstruktor Viewer(cache, httpContextAccessor, licensePath)builder.Services.AddDoconut(options => …) + Viewer injizieren
LicenseStatischer Aufruf Viewer.DoconutLicense(path) + SetLicensePlugin(...) pro Pluginoptions.LicensePath / LicenseContent / LicenseStream – eine Lizenz, automatische Erkennung von Plugin‑Dateien
Openviewer.OpenDocument(...) (synchron)await viewer.OpenDocumentAsync(...)
Closeviewer.CloseDocument() oder viewer.Dispose()viewer.CloseDocument(token) – Viewer ist nicht IDisposable
LifetimeViewer implementiert IDisposable, hält das geöffnete DokumentViewer ist zustandslos; Sitzungen leben im Cache unter Tokens
Converterviewer.Converter‑EigenschaftDas Converter‑Plugin (AddPlugin<ConverterPlugin>()) + der DocumentConverter‑Dienst
Config classesDoconut.Configs.View.*‑NamensräumeAlle im Doconut‑Namespace
MiddlewareManuelle Handler‑Verdrahtungapp.UseDoconutResources() + app.UseDoconut()

Ein typisches Vorher/Nachher:

text
// .NET 6 (old API, shown for contrast — not valid on .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 injected, license configured once in AddDoconut()
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Migration von .NET Framework 4.7 (Web Forms)

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

  • 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 → Lizenzquellen in DoconutOptions.
  • 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 eine Neuschreibung der Hosting‑Schicht um ein unverändertes Konzept: öffnen → Token → Widget.

Hinweis zur Namensgebung

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

Migrations‑Checkliste

  1. Pakete austauschen; Plugin‑Paketversionen angleichen.
  2. Lizenz‑Setup in AddDoconut() verschieben; statische Lizenzaufrufe entfernen.
  3. Öffnungsaufrufe asynchron machen; Dispose/parameterloses CloseDocument durch CloseDocument(token) ersetzen.
  4. viewer.Converter‑Verwendungen durch die Registrierung des Converter‑Plugins + DocumentConverter ersetzen.
  5. Den Sicherheitsweg erneut testen: AddSession()/UseSession() sind jetzt mit der Standardsicherheit erforderlich.

War diese Seite hilfreich?