Migration von der klassischen .NET 6-Integration

Doconut verfügt über zwei unterschiedliche .NET 6-Integrationen. Sie können denselben Paketnamen Doconut.NET6 verwenden, daher sollten Sie die Generation anhand der APIs in der Anwendung identifizieren, bevor Sie Pakete, Startup, Lizenzen oder Browser‑Ressourcen ändern.

Welche .NET 6-Integration verwenden Sie?

Wenn beide Spalten in derselben Anwendung erscheinen, betrachten Sie die Migration als unvollständig. Senden Sie kein Dokument‑Token über Ressourcen oder Middleware der anderen Generation.

Warum der NuGet‑Paketname Sie möglicherweise nicht informiert

Beide Generationen wurden unter der Paket‑ID Doconut.NET6 ausgeliefert. Ein Paket‑Verweis, Lock‑File oder gecachtes .nupkg identifiziert die hostende API daher nicht von selbst. Notieren Sie die genaue Paketversion und prüfen Sie gemeinsam Program.cs, Viewer‑Konstruktion, Dokument‑Öffnung und Browser‑Skripte.

Die für diesen Leitfaden geprüfte aktuelle Version ist Doconut.NET6 26.7.0. Die optionalen öffentlichen Pakete sind Doconut.NET6.Converter und Doconut.NET6.Dicom, beide auf dieselbe Release‑Version wie das Kernpaket festgelegt.

Bevor Sie migrieren

1. Erstellen Sie einen Branch und ein deploybares Backup der bestehenden Anwendung.
2. Notieren Sie die exakten Kern‑ und Plugin‑Paketversionen.
3. Inventarisieren Sie jedes DocImage.axd‑Mapping, jeden new Viewer(...)‑Aufruf, Lizenz‑Lade‑Aufruf, kopiertes Doconut‑Skript, benutzerdefinierte Toolbar‑Aktion und jeden Dokument‑Öffnen‑Endpunkt.
4. Bewahren Sie die aktuellen .lic‑Dateien und Deployment‑Secrets außerhalb der Versionskontrolle auf.
5. Erfassen Sie ein repräsentatives Set von PDF, Office, Bild, CAD, E‑Mail, DICOM, durchsuchbaren, passwortgeschützten und annotierten Dokumenten.
6. Notieren Sie das aktuelle Session‑Timeout, das Sicherheitsverhalten, die Schriftarten und die Plattform‑Einstellungen.

Migrieren Sie zunächst eine Umgebung, bevor Sie die Produktion umstellen. Die aktuelle Integration ändert Service‑Lebensdauer, Request‑Routing, Session‑Eigentümerschaft und die Auslieferung von Client‑Ressourcen.

Paket‑ und Lizenz‑Kompatibilität

Ersetzen oder aktualisieren Sie das Kernpaket bewusst; verlassen Sie sich nicht auf die identische Paket‑ID, um die neue API auszuwählen. Der Standardbefehl installiert das neueste stabile Release:

dotnet add package Doconut.NET6

Für eine reproduzierbare Migration zur in diesem Leitfaden geprüften Version geben Sie die Version als separates Argument an:

dotnet add package Doconut.NET6 --version 26.7.0

Halten Sie jedes Doconut‑Plugin auf derselben Version wie das Kernpaket. Die aktuelle Integration lädt Lizenzen einmalig während AddDoconut(), nach folgender Priorität:

LicenseStream > LicenseContent > LicensePath > automatische Erkennung

Die automatische Erkennung sucht nach Doconut.Viewer.lic und zugehörigen Doconut.Viewer.<Capability>.lic‑Dateien. Ein klassischer Aufruf von Viewer.DoconutLicense(...) oder Viewer.SetLicensePlugin(...) ist kein aktueller Startup‑Mechanismus. Verschieben Sie die Lizenz in DoconutOptions, bewahren Sie zugehörige Dateien gemeinsam bei automatischer Erkennung, starten Sie nach einer Lizenz‑Änderung neu und prüfen Sie die Fähigkeiten über IDoconutLicenseService.

Gehen Sie nicht davon aus, dass das Vorhandensein einer alten Plugin‑Lizenz das Anrecht auf einen aktuellen Plugin‑Build beweist. Testen Sie Viewer, Suche, Annotation, Converter und DICOM separat mit den freigegebenen Release‑Artefakten.

Startup und Dependency Injection

Klassische Anwendungen konstruieren Viewer mit ASP.NET‑Cache‑ und Request‑Accessor‑Abhängigkeiten:

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

Die aktuelle Integration registriert Doconut einmalig und erhält Viewer über Dependency Injection:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer ist ein transienter Service. Der Dokument‑Session‑Manager und sein Cache besitzen den längerlebigen Dokumentenzustand, nicht die konkret injizierte Viewer‑Instanz.

Middleware und Resource‑Routing

Entfernen Sie den klassischen MapWhen‑Zweig, der DocImage.axd erkennt:

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

Im aktuellen Pipeline‑Verlauf:

1. Rufen Sie UseSession() vor Doconut auf, während Session‑Sicherheit aktiviert ist;
2. Rufen Sie UseDoconutResources() vor UseDoconut() auf;
3. Halten Sie ResourcesPath, die generierten Ressourcen‑URLs und den Client‑ResPath abgestimmt;
4. Wenn Sie UseDoconut() einem Branch zuordnen, halten Sie diesen Branch und den Client‑BasePath abgestimmt.

MiddlewarePath ist eine validierte Konfiguration; sie erzeugt keinen eigenen ASP.NET‑Core‑Branch. Verwenden Sie entweder die einfache Pipeline im obigen Beispiel oder ein explizites app.Map("/doconut", branch => branch.UseDoconut())‑Arrangement, das konsequent vom Client genutzt wird.

Viewer‑Konstruktion und Lebensdauer

Entfernen Sie anwendungs‑eigene Caches von Viewer‑Objekten. Injizieren Sie Viewer in einen Endpunkt, Razor‑Page, Controller oder einen scoped‑Anwendungsservice:

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Das zurückgegebene Token identifiziert eine serverseitige Dokumentensitzung. Behandeln Sie es als Bearer‑Credential: loggen, persistieren oder analysieren Sie es nicht.

Öffnen und Schließen von Dokumenten

Ersetzen Sie das synchrone OpenDocument(...) durch OpenDocumentAsync(...):

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Die aktuellen Überladungen akzeptieren einen Dateipfad oder Stream, eine optionale Format‑Konfiguration, optionale DocOptions und ein Cancellation‑Token. Schließen Sie die Serversitzung explizit, wenn der Browser sie nicht mehr benötigt:

viewer.CloseDocument(token);

Verwenden Sie nach dem Cut‑over kein klassisches Token erneut. Öffnen Sie jedes Dokument erneut über die aktuelle API.

Konfigurationsklassen

Die aktuelle API trennt die Verantwortlichkeiten:

Übertragen Sie nicht DocOptions.ImageResolution als Rendering‑Steuerung. Sie ist veraltet; setzen Sie stattdessen BaseConfig.ImageResolution in der format‑spezifischen Konfiguration. Prüfen Sie alle Defaults, anstatt anzunehmen, dass eine klassische Konfiguration identisches Verhalten zeigt.

Viewer‑Toolbar, Suche und Annotation

Migrieren Sie die alten Skripte nicht einzeln. Die aktuellen Referenz‑Anwendungen setzen ein komplettes Seiten‑Package zusammen:

1. Emitieren Sie Viewer‑CSS und lizenziertes Suche/Annotation‑CSS mit ReferenceCss;
2. Rendern Sie die anwendungs‑eigene Viewer‑Toolbar;
3. Rendern Sie searchBarMount, annBarMount und den erforderlichen Viewer‑Mount;
4. Emitieren Sie Viewer‑ und lizenzierte Modul‑Skripte mit ReferenceScripts;
5. Laden Sie das eigene viewerToolbar.js der Anwendung;
6. Initialisieren Sie ein objViewer;
7. Initialisieren Sie die lizenzierten Suche‑ und Annotation‑Ribbons;
8. Rufen Sie attach(objViewer) für jedes Ribbon auf;
9. Öffnen Sie das Dokument und rufen Sie objViewer.View(token) auf.

Suche und Annotation sind Module, die demselben Viewer angehängt sind, nicht unabhängige Toolbars. Die Haupt‑Toolbar gehört zur Host‑Anwendung; die Suche‑ und Annotation‑Ribbons sind eingebettete, funktions‑gesteuerte Ressourcen.

Entfernen Sie manuell kopierte klassische Dateien wie documentLinks.js und docViewer.UI.js erst, nachdem die aktuelle Seite mit Ressourcen funktioniert, die von ReferenceCss und ReferenceScripts bereitgestellt werden.

Plugin‑Registrierung

Klassische statische Plugin‑Lizenz‑Methoden registrieren keine aktuellen Plugins. Installieren und registrieren Sie jedes veröffentlichte Paket explizit:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() prüft die registrierten Plugin‑Fähigkeiten beim Startup. Converter und DICOM sind veröffentlichte .NET 6‑Plugins. Normale Suche‑ und Annotation‑Funktionen sind integrierte lizenzierte Features, nicht AddPlugin<TPlugin>()‑Pakete.

Session‑ und Dokumentensicherheit

Die aktuelle Integration bindet Dokumente an undurchsichtige Tokens und gecachte Sessions. Bei UnsafeMode = false fügt UseDoconut() Dokument‑Zugriffssicherheit hinzu und der Host muss ASP.NET‑Session konfigurieren:

builder.Services.AddSession();
app.UseSession();

Setzen Sie DocOptions.IsSecured = true, es sei denn, ein geprüftes Design erfordert etwas anderes. Verwenden Sie niemals UnsafeMode = true als Migrations‑Abkürzung. Testen Sie Anfragen ohne Token, mit einem fehlerhaften Token, einem abgelaufenen Token und einem Token aus einer anderen Browser‑Session.

Die Distributed‑Referenz‑Anwendung fügt Zugriffstickets und Transportdetails hinzu. Diese APIs sind für eine normale Single‑Node‑Migration nicht erforderlich.

Testen der Migration

Stellen Sie mindestens sicher, dass:

• die Anwendung mit der Produktions‑Lizenz und allen registrierten Plugins startet;
• Viewer‑CSS/Skripte und alle Seiten‑Bild‑Anfragen unter den gewählten Pfaden funktionieren;
• Dokument öffnen, navigieren, zoomen, Thumbnails, drucken und explizit schließen funktioniert;
• Suche in einem texthaltigen Dokument und der nicht‑durchsuchbare Zustand einer Bild‑Only‑Datei;
• Annotation laden, speichern, exportieren und Funktions‑Gating;
• Converter‑Zielerkennung, Ausgabe, Download und Wasserzeichen‑Zustand;
• DICOM‑Seiten, Frames und Animation; .NET 6‑technische Metadaten sind nicht verfügbar;
• passwortgeschützte Dokumente, benutzerdefinierte Schriftarten, nicht‑lateinischer Text und konfigurierte Timeouts;
• Ablehnung von Tokens über Session‑Grenzen und Verhalten bei abgelaufenen Sessions;
• mobile Darstellung, Dark‑Mode und der Produktions‑Reverse‑Proxy‑Pfad.

Rollback‑Plan

Bewahren Sie das klassische Deploy‑Artifact, passende Pakete, Lizenzdateien und kopierte Browser‑Ressourcen gemeinsam auf. Ein sicherer Rollback wechselt die gesamte Anwendungs‑Generation; er mischt keinen klassischen Server mit aktuellen Skripten oder einen aktuellen Server mit klassischen DocImage.axd‑Aufrufen.

Vor dem Cut‑over dokumentieren Sie:

• den Deployment‑Slot oder das Artifact, das für den Rollback verwendet wird;
• die Auswirkungen auf Datenbank/Cache, falls vorhanden;
• wie aktive Dokument‑Sessions invalidiert werden;
• den Health‑Check und das Smoke‑Document, das über den Rollback entscheidet;
• wer das vorherige Paket‑Set und die Konfiguration wiederherstellen kann.

Legacy‑Dokumentation

Das übersetzte klassische Handbuch bleibt verfügbar unter Legacy .NET 6‑Einrichtung. Das neue Gateway für klassische Integration erklärt dieselben Identifikations‑Signale und verweist zurück auf diesen Migrations‑Leitfaden.

Bewahren Sie die historische URL in Lesezeichen und Support‑Tickets, solange klassische Installationen noch existieren. Sie dokumentiert eine andere Generation und wird nicht zur aktuellen API weitergeleitet.