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.jsLegacy / klassisch
builder.Services.AddDoconut(...)Aktuelle Integration
app.UseDoconutResources() plus app.UseDoconut()Aktuelle Integration
Viewer bereitgestellt durch Dependency InjectionAktuelle 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

  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‑Lade‑Aufruf, kopiertes Doconut‑Skript, benutzerdefinierte Toolbar‑Aktion 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 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:

bash
dotnet add package Doconut.NET6

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

bash
dotnet add package Doconut.NET6 --version 26.9.0

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

text
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 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:

csharp
// 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:

csharp
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:

csharp
// 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:

  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 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:

csharp
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(...):

csharp
// 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:

csharp
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:

VerantwortlichkeitAktueller Typ
Middleware‑Pfade, Lizenzierung, Plugin‑RegistrierungDoconutOptions
Passwort, Timeout, Sicherheit, WasserzeichenDocOptions
Format‑Rendering und DPIPdfConfig, WordConfig, ExcelConfig, und andere BaseConfig‑Typen
Browser‑Widget‑StandardwerteViewerConfig oder die entsprechenden JavaScript‑Optionen
Generiertes CSS und SkripteCssConfig 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:

  1. Geben Sie Viewer‑CSS und lizenziertes Suche/Annotation‑CSS mit ReferenceCss aus;
  2. Rendern Sie die von der Anwendung verwaltete Viewer‑Toolbar;
  3. Rendern Sie searchBarMount, annBarMount und die erforderliche Viewer‑Einbindung;
  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 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 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:

csharp
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:

csharp
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?