Migration von der klassischen .NET 6-Integration

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

Welche .NET 6-Integration verwenden Sie?

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

Warum der NuGet-Paketname Sie nicht informieren kann

Beide Generationen wurden unter der Paket‑ID Doconut.NET6 veröffentlicht. Ein Paket‑Verweis, Lock‑File oder gecachtes .nupkg identifiziert die zugrundeliegende API daher nicht automatisch. Notieren Sie die exakte Paketversion und prüfen Sie gemeinsam Program.cs, die Viewer‑Konstruktion, das Dokument‑Öffnen und die Browser‑Skripte.

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

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 Aufruf von new Viewer(...), Lizenz‑Ladeaufruf, kopiertes Doconut‑Skript, benutzerdefinierte Toolbar‑Aktion und Endpunkt zum Dokument‑Öffnen.
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 bestehende 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 die Service‑Lebensdauer, das Request‑Routing, den Sitzungs‑Besitz und die Bereitstellung von Client‑Ressourcen.

Paket- und Lizenzkompatibilitä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 zu dem von diesem Leitfaden geprüften Release geben Sie die Version als separate Option 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 einmal während AddDoconut(), wobei folgende Priorität gilt:

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 Start‑Mechanismus. Verschieben Sie die Lizenz in DoconutOptions, bewahren Sie zugehörige Dateien gemeinsam auf, wenn Sie die automatische Erkennung nutzen, 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, Search, Annotation, Converter und DICOM separat mit den freigegebenen Release‑Artefakten.

Start und Abhängigkeitsinjektion

Klassische Anwendungen erstellen 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 einmal 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 transientes Service. Der Dokumentensitzungsmanager und sein Cache besitzen den längerlebigen Dokumentenzustand, nicht die speziell injizierte Viewer‑Instanz.

Middleware und Ressourcenrouting

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()));

In der aktuellen Pipeline:

1. Rufen Sie UseSession() vor Doconut auf, während die Sitzungs­sicherheit aktiviert ist;
2. Rufen Sie UseDoconutResources() vor UseDoconut() auf;
3. Behalten Sie ResourcesPath, die generierten Ressourcen‑URLs und den Client‑ResPath abgestimmt bei;
4. Wenn Sie UseDoconut() einem Zweig zuordnen, halten Sie diesen Zweig und den Client‑BasePath abgestimmt.

MiddlewarePath ist eine validierte Konfiguration; sie erstellt keinen ASP.NET Core‑Zweig von selbst. Verwenden Sie entweder die einfache Pipeline im obigen Beispiel oder eine explizite app.Map("/doconut", branch => branch.UseDoconut())‑Anordnung, die vom Client konsequent verwendet wird.

Viewer‑Konstruktion und Lebensdauer

Entfernen Sie von der Anwendung verwaltete Caches von Viewer‑Objekten. Injizieren Sie Viewer in einen Endpunkt, Razor‑Seite, Controller oder einen scoped Anwendung‑Service:

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‑Anmeldeinformation: Loggen Sie es nicht, speichern Sie es nicht und verwenden Sie es nicht in Analysen.

Ö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 });

Aktuelle Überladungen akzeptieren einen Dateipfad oder Stream, eine optionale Formatkonfiguration, 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 ein klassisches Token nach der Umstellung nicht erneut. Öffnen Sie jedes Dokument erneut über die aktuelle API.

Konfigurationsklassen

Die aktuelle API trennt Verantwortlichkeiten:

Übertragen Sie DocOptions.ImageResolution nicht als Rendering‑Steuerung weiter. Es ist veraltet; setzen Sie BaseConfig.ImageResolution in der format‑spezifischen Konfiguration. Überprüfen Sie alle Standardwerte, anstatt anzunehmen, dass eine klassische Konfiguration das gleiche Verhalten hat.

Viewer‑Werkzeugleiste, Suche und Annotation

Migrieren Sie die alten Skripte nicht einzeln. Die aktuellen Referenzanwendungen stellen ein komplettes Seitenpaket zusammen:

1. Geben Sie Viewer‑CSS und lizenziertes Search/Annotation‑CSS mit ReferenceCss aus;
2. Rendern Sie die von der Anwendung verwaltete Viewer‑Werkzeugleiste;
3. Rendern Sie searchBarMount, annBarMount und den erforderlichen Viewer‑Mount;
4. Geben Sie Viewer‑ und lizenzierte Modul‑Skripte mit ReferenceScripts aus;
5. Laden Sie das eigene viewerToolbar.js der Anwendung;
6. Initialisieren Sie ein objViewer;
7. Initialisieren Sie die lizenzierten Search‑ 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.

Search und Annotation sind Module, die an denselben Viewer angehängt sind, nicht unabhängige Werkzeugleisten. Die Haupt‑Werkzeugleiste gehört zur Host‑Anwendung; die Search‑ und Annotation‑Ribbons sind eingebettete, funktionsabhängige Ressourcen.

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

Plugin-Registrierung

Klassische statische Plugin‑Lizenzmethoden registrieren aktuelle Plugins nicht. 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() validiert registrierte Plugin‑Fähigkeiten beim Start. Converter und DICOM sind veröffentlichte .NET 6 Plugins. Normal Search und Annotation sind integrierte lizenzierte Funktionen, keine AddPlugin<TPlugin>() Pakete.

Sitzungs- und Dokumentensicherheit

Die aktuelle Integration bindet Dokumente an undurchsichtige Tokens und zwischengespeicherte Sitzungen. Mit dem Standardwert UnsafeMode = false fügt UseDoconut() Dokumentenzugriffssicherheit hinzu und der Host muss die ASP.NET‑Sitzung konfigurieren:

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

Behalten Sie DocOptions.IsSecured = true bei, es sei denn, ein überprüftes Design erfordert etwas anderes. Verwenden Sie UnsafeMode = true niemals als Migrationsabkürzung. Testen Sie Anfragen ohne Token, mit einem fehlerhaften Token, einem abgelaufenen Token und einem Token aus einer anderen Browsersitzung.

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

Testen der Migration

Überprüfen Sie mindestens:

• Anwendungsstart mit der Produktionslizenz und allen registrierten Plugins;
• Viewer‑CSS/Skripte und alle Seiten‑Bild‑Anfragen unter den gewählten Pfaden;
• Dokument öffnen, Navigation, Zoom, Thumbnails, Drucken und explizites Schließen;
• Suche in einem texthaltigen Dokument und der nicht durchsuchbare Zustand einer rein bildbasierten Datei;
• Annotation laden, speichern, exportieren und Funktionsgating;
• Converter‑Zielerkennung, Ausgabe, Download und Wasserzeichen‑Status;
• DICOM‑Seiten, Frames und Animation; .NET 6‑technische Metadaten sind nicht verfügbar;
• Passwortgeschützte Dokumente, benutzerdefinierte Schriftarten, nicht‑lateinischer Text und konfigurierte Zeitüberschreitungen;
• Ablehnung von Tokens über Sitzungen hinweg und Verhalten bei abgelaufenen Sitzungen;
• Mobile, Dark‑Mode und der Produktions‑Reverse‑Proxy‑Pfad.

Rollback‑Plan

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

Vor dem Umschalten dokumentieren Sie:

• den Bereitstellungs‑Slot oder das Artefakt, das für den Rollback verwendet wird;
• die Auswirkungen auf Datenbank/Cache, falls vorhanden;
• wie aktive Dokumentensitzungen ungültig gemacht werden;
• den Health‑Check und das Smoke‑Dokument, das zur Entscheidung über den Rollback verwendet wird;
• wer das vorherige Paketsatz und die Konfiguration wiederherstellen kann.

Legacy‑Dokumentation

Das übersetzte klassische Handbuch ist weiterhin verfügbar unter Legacy .NET 6 setup. Das neue Classic integration gateway erklärt dieselben Identifikationssignale und verweist zurück auf diesen Migrationsleitfaden.

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.