Migration von der klassischen .NET 6-Integration

Doconut hat 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, betrachten Sie die Migration als unvollständig. Senden Sie kein Dokument‑Token über Ressourcen oder Middleware der anderen Generation.

Warum der NuGet-Paketname Ihnen möglicherweise nichts sagt

Beide Generationen wurden unter der Doconut.NET6 Paket-ID veröffentlicht. Ein Paketverweis, Sperrdatei oder zwischengespeichertes .nupkg identifiziert die hostende API daher nicht allein. Notieren Sie die genaue Paketversion und prüfen Sie Program.cs, Viewer‑Konstruktion, Dokumentenöffnung und Browserskripte gemeinsam.

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, festgelegt auf dieselbe Release‑Version wie das Kernpaket.

Bevor Sie migrieren

1. Erstellen Sie einen Branch und ein bereitstellbares Backup der bestehenden Anwendung.
2. Notieren Sie die genauen Kern‑ und Plugin‑Paketversionen.
3. Erfassen Sie jede DocImage.axd Zuordnung, jeden new Viewer(...) Aufruf, Lizenz‑Ladeaufruf, kopiertes Doconut‑Skript, benutzerdefinierte Symbolleistenaktion und Dokument‑Öffnen‑Endpunkt.
4. Bewahren Sie die aktuellen .lic Dateien und Bereitstellungsgeheimnisse außerhalb der Versionskontrolle auf.
5. Erfassen Sie einen repräsentativen Satz von PDF-, Office-, Bild-, CAD-, E‑Mail-, DICOM-, durchsuchbaren, passwortgeschützten und annotierten Dokumenten.
6. Notieren Sie das bestehende Sitzungs‑Timeout, Sicherheitsverhalten, Schriftarten und Plattform‑Einstellungen.

Migrieren Sie zunächst eine Umgebung, bevor Sie die Produktion ändern. Die aktuelle Integration ändert die Service‑Lebensdauer, Anforderungsrouting, Sitzungsbesitz 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 die neueste stabile Version:

dotnet add package Doconut.NET6

Für eine reproduzierbare Migration zur von diesem Leitfaden geprüften Version übergeben Sie die Version als separate Option:

dotnet add package Doconut.NET6 --version 26.7.0

Behalten Sie jedes Doconut‑Plugin in derselben Version wie das Kernpaket bei. Die aktuelle Integration lädt Lizenzen einmal während AddDoconut(), unter Verwendung dieser Priorität:

LicenseStream > LicenseContent > LicensePath > automatic discovery

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 Startmechanismus. Verschieben Sie die Lizenz zu DoconutOptions, bewahren Sie zugehörige Dateien zusammen, wenn Sie die automatische Erkennung verwenden, starten Sie nach einer Lizenzänderung neu und überprüfen Sie die Fähigkeiten über IDoconutLicenseService.

Gehen Sie nicht davon aus, dass das Vorhandensein einer alten Plugin‑Lizenz das Anrecht für einen aktuellen Plugin‑Build beweist. Testen Sie Viewer, Suche, Annotation, Konverter 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:

// Klassische Integration — nur zum Vergleich; nicht gegen das aktuelle SDK kompilieren.
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.AddDistributedMemoryCache();
builder.Services.AddSession();

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

Viewer ist ein transientes Service. Der Dokument‑Sitzungs‑Manager und sein Cache besitzen den längerlebigen Dokumentzustand, nicht die speziell injizierte Viewer‑Instanz.

Middleware und Ressourcenrouting

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

// Klassische Integration — während des Cutovers entfernen.
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 ausgerichtet bei;
4. Beim Zuordnen von UseDoconut() zu einem Zweig behalten Sie diesen Zweig und den Client‑BasePath ausgerichtet.

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

Viewer-Erstellung und Lebensdauer

Entfernen Sie von der Anwendung besessene Caches von Viewer‑Objekten. Injizieren Sie Viewer in einen Endpunkt, Razor‑Seite, Controller oder einen scoped Anwendungs‑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‑Credential: Protokollieren, persistieren oder in Analysen verwenden Sie es nicht.

Öffnen und Schließen von Dokumenten

Ersetzen Sie synchrones OpenDocument(...) durch OpenDocumentAsync(...):

// Aktuelle .NET 6-Integration: Viewer kommt aus DI und das Öffnen des Dokuments ist asynchron.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Aktuelle Überladungen akzeptieren einen Dateipfad oder Stream, eine optionale Format‑Konfiguration, optionales 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 die Verantwortungsbereiche:

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

Viewer-Toolbar, Suche und Annotation

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

1. Erzeugen Sie Viewer‑CSS und lizenziertes Search/Annotation‑CSS mit ReferenceCss;
2. Rendern Sie die von der Anwendung besessene Viewer‑Toolbar;
3. Rendern Sie searchBarMount, annBarMount und die erforderliche Viewer‑Einbindung;
4. Erzeugen 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 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 Toolbars. Die Haupt‑Toolbar 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 registration

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() prüft 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.

Sitzung und Dokumentensicherheit

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

builder.Services.AddDistributedMemoryCache(); // Session-Status benötigt einen Cache (MVC/Razor Pages fügt bereits einen hinzu)
builder.Services.AddSession();
app.UseSession();

Behalten Sie DocOptions.IsSecured = true, es sei denn, ein geprüftes Design erfordert etwas anderes. Verwenden Sie niemals
UnsafeMode = true als Migrations‑Shortcut. 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

Mindestens prüfen Sie:

• Anwendungsstart mit der Produktionslizenz und jedem registrierten Plugin;
• Viewer‑CSS/Skripte und alle Seiten‑Bild‑Anfragen unter den gewählten Pfaden;
• Dokument öffnen, Navigation, Zoom, Miniaturansichten, 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

Behalten Sie das klassische Bereitstellungsartefakt, passende Pakete, Lizenzdateien und kopierte Browser
Ressourcen zusammen. Ein sicherer Rollback wechselt die gesamte Anwendungsgeneration; er mischt nicht einen 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 für einen Rollback verwendet wird;
• wer das vorherige Paketset und die Konfiguration wiederherstellen kann.

Legacy‑Dokumentation

Das übersetzte klassische Handbuch bleibt verfügbar unter
Legacy .NET 6 Einrichtung. Der neue
Klassisches Integrationsgateway erklärt dieselben Identifikationssignale und verweist zurück auf diesen Migrationsleitfaden.

Behalten 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.