Migration von der klassischen .NET 6-Integration
Verschieben einer bestehenden Doconut.NET6-Anwendung zur aktuellen DI- und Async-API
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 identifizieren, bevor Sie Pakete, Start‑Up, Lizenzen oder Browser‑Ressourcen ändern.
Welche .NET 6-Integration verwenden Sie?
| Wenn das Projekt enthält… | Generation |
|---|---|
app.MapWhen(... "DocImage.axd" ...) | Legacy / klassisch |
new Viewer(_cache, _accessor, ...) | Legacy / klassisch |
Viewer.DoconutLicense(...) oder Viewer.SetLicensePlugin(...) | Legacy / klassisch |
Manuell kopierte docViewer.js, documentLinks.js oder docViewer.UI.js | Legacy / klassisch |
builder.Services.AddDoconut(...) | Aktuelle Integration |
app.UseDoconutResources() plus app.UseDoconut() | Aktuelle Integration |
Viewer bereitgestellt durch Dependency Injection | Aktuelle Integration |
await viewer.OpenDocumentAsync(...) | Aktuelle Integration |
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 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, die Viewer‑Konstruktion, das Öffnen von Dokumenten und die Browserskripte gemeinsam.
Die aktuelle, für diesen Leitfaden geprüfte 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
- Erstellen Sie einen Branch und ein bereitstellbares Backup der bestehenden Anwendung.
- Notieren Sie die genauen Kern‑ und Plugin‑Paketversionen.
- Erfassen Sie jede
DocImage.axdZuordnung, jedennew Viewer(...)Aufruf, Lizenz‑Lade‑Aufruf, kopiertes Doconut‑Skript, benutzerdefinierte Toolbar‑Aktion und Dokument‑Öffnen‑Endpunkt. - Bewahren Sie die aktuellen
.licDateien und Bereitstellungsgeheimnisse außerhalb der Versionskontrolle auf. - Erfassen Sie einen repräsentativen Satz von PDF-, Office-, Bild-, CAD-, E‑Mail-, DICOM-, durchsuchbaren, passwortgeschützten und annotierten Dokumenten.
- Notieren Sie das aktuelle Sitzungs‑Timeout, das Sicherheitsverhalten, die Schriftarten und die Plattform‑Einstellungen.
Migrieren Sie zunächst eine Umgebung, bevor Sie die Produktion ändern. Die aktuelle Integration ändert die Service‑Lebensdauer, das Anforderungs‑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 die neueste stabile Version:
dotnet add package Doconut.NET6Fü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.9.0Behalten Sie jedes Doconut‑Plugin in derselben Version wie das Kernpaket. Die aktuelle Integration lädt Lizenzen einmal während AddDoconut(), wobei diese Priorität verwendet wird:
LicenseStream > LicenseContent > LicensePath > automatic discoveryDie 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 zu DoconutOptions, behalten 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 Dependency Injection
Klassische Anwendungen erstellen Viewer mit ASP.NET-Cache- und Request-Accessor-Abhängigkeiten:
// Klassische Integration — nur zum Vergleich; kompilieren Sie dies nicht gegen das aktuelle 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.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 Dokumentenzustand, nicht die speziell injizierte Viewer‑Instanz.
Middleware und Ressourcenrouting
Entfernen Sie den klassischen MapWhen‑Zweig, der DocImage.axd erkennt:
// Klassische Integration — während der Umstellung entfernen.
app.MapWhen(
context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
branch => branch.UseDoconut(new DoconutOptions()));Im aktuellen Pipeline:
- Rufen Sie
UseSession()vor Doconut auf, während die Sitzungssicherheit aktiviert ist; - Rufen Sie
UseDoconutResources()vorUseDoconut()auf; - Behalten Sie
ResourcesPath, die generierten Ressourcen‑URLs und den Client‑ResPathausgerichtet bei; - Beim Zuordnen von
UseDoconut()zu einem Zweig, behalten Sie diesen Zweig und den Client‑BasePathausgerichtet bei.
MiddlewarePath ist eine validierte Konfiguration; sie erstellt nicht von selbst einen ASP.NET‑Core‑Zweig. Verwenden Sie entweder die einfache Pipeline im oben kompilierten 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‑Credential: Protokollieren, persistieren oder in Analysen einbinden Sie es nicht.
Öffnen und Schließen von Dokumenten
Ersetzen Sie das synchrone 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 Verantwortlichkeiten:
| Verantwortlichkeit | Aktueller Typ |
|---|---|
| Middleware‑Pfade, Lizenzierung, Plugin‑Registrierung | DoconutOptions |
| Passwort, Timeout, Sicherheit, Wasserzeichen | DocOptions |
| Format‑Rendering und DPI | PdfConfig, WordConfig, ExcelConfig, und andere BaseConfig‑Typen |
| Browser‑Widget‑Standardwerte | ViewerConfig oder die entsprechenden JavaScript‑Optionen |
| Generiertes CSS und Skripte | CssConfig und ScriptConfig |
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 Standardwerte, 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:
- Geben Sie Viewer‑CSS und lizenziertes Suche/Annotation‑CSS mit
ReferenceCssaus; - Rendern Sie die von der Anwendung verwaltete Viewer‑Toolbar;
- Rendern Sie
searchBarMount,annBarMountund die erforderliche Viewer‑Einbindung; - Geben Sie Viewer‑ und lizenzierte Modul‑Skripte mit
ReferenceScriptsaus; - Laden Sie das eigene
viewerToolbar.jsder Anwendung; - Initialisieren Sie ein
objViewer; - Initialisieren Sie die lizenzierten Suche‑ und Annotation‑Ribbons;
- Rufen Sie
attach(objViewer)für jedes Ribbon auf; - Öffnen Sie das Dokument und rufen Sie
objViewer.View(token)auf.
Suche und Annotation sind Module, die an denselben Viewer angehängt sind, nicht unabhängige Toolbars. Die Haupt‑Toolbar gehört zur Host‑Anwendung; die Suche‑ 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. Normale Suche 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 state benötigt einen Cache (MVC/Razor Pages fügt bereits einen hinzu)
builder.Services.AddSession();
app.UseSession();Behalten Sie DocOptions.IsSecured = true bei, es sei denn, ein geprü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, 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 Schriften, nicht‑lateinischer Text und konfigurierte Zeitüberschreitungen;
- Ablehnung von Tokens über Sitzungen hinweg und Verhalten bei abgelaufenen Sitzungen;
- Mobile, Dark‑Mode und den 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 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‑Setup. Das neue Classic‑Integrationsgateway 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.
War diese Seite hilfreich?