Migration

Upgrade auf Doconut unter .NET 8

Zwei Migrationen werden auf dieser Seite behandelt: Upgrade 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.

Upgrade 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 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.
  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 genutzter 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
SetupErzeugen Sie Viewer(cache, httpContextAccessor, licensePath)builder.Services.AddDoconut(options => …) + Inject Viewer
LicenseStatische 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 und hält das geöffnete DokumentViewer ist zustandslos; Sitzungen leben im Cache unter Tokens
Converterviewer.Converter‑EigenschaftDas Converter‑Plugin (AddPlugin<ConverterPlugin>()) + der DocumentConverter‑Service
Config‑KlassenDoconut.Configs.View.*‑NamensräumeAlles im Doconut‑Namensraum
MiddlewareManuelle Handler‑Verkettungapp.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 Version 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. Öffnungs‑Aufrufe asynchron machen; Dispose/parameterloses CloseDocument durch CloseDocument(token) ersetzen.
  4. viewer.Converter‑Verwendungen durch die Registrierung des Converter‑Plugins + DocumentConverter ersetzen.
  5. Den Sicherheits‑Pfad erneut testen: AddSession() / UseSession() sind jetzt mit Standard‑Sicherheit erforderlich.

War diese Seite hilfreich?