Migration

Diese Seite behandelt das Upgrade einer bestehenden ASP.NET-Anwendung von Doconut.NETFramework 26.8.0 oder früher (.NET Framework 4.7) auf 26.9.0 und später (.NET Framework 4.7.2). Das Doconut‑Beispielpaket enthält den vollständigen Migrationsleitfaden und die klassischen Beispiele, die auf die neue API portiert wurden – MVC 5, eine Webfarm und Web Forms. Einen Vergleich Ihrer Anwendung mit dem Ausgangsbeispiel durchzuführen ist der schnellste Weg.

Ein Paket, zwei Versionen

Beide Bibliotheken werden unter derselben Paket-ID veröffentlicht, Doconut.NETFramework. Die Version unterscheidet sie:

Das Aktualisieren des Pakets ist das Upgrade. Es gibt kein separates Paket zur Installation und keine Kompatibilitätsschicht: 26.9.0 hat eine andere API-Oberfläche, erwarten Sie also nach dem Update Compilerfehler – siehe den Rest dieser Seite. Die .NET Framework‑4.7‑Linie ist eingestellt und 26.8.0 ist ihr letzter Release. Sie können dabei bleiben – hier gibt es keinen Sicherheitsfix, den Sie verpassen würden – aber neue Releases, Plugins, der verteilte Modus und die Drop‑In‑Widgets erscheinen nur in 26.9.0 und später.

1. Zielplattform ändern und Paket aktualisieren

Zielen Sie das Webprojekt zuerst auf .NET Framework 4.7.2 aus: Ein Projekt, das noch 4.7 anvisiert, kann 26.9.0 nicht installieren, und NuGet verweigert das Update. Aktualisieren Sie dann Doconut.NETFramework und fügen Sie die von Ihnen verwendeten Plugin‑Pakete hinzu (Doconut.NETFramework.Converter, Doconut.NETFramework.Dicom, …). Jedes Plugin benötigt eine Lizenz, die es gewährt.

Wenn das Projekt packages.config verwendet, führt das Update den Deinstallationsschritt der vorherigen Version aus, der den DocImage‑Handler aus Web.config entfernt, und 26.9.0 fügt ihn nicht wieder hinzu. Registrieren Sie ihn erneut wie in Schritt 3 gezeigt; bis Sie das tun, liefert DocImage.axd 404 und es wird keine Seite gerendert.

2. Namespaces: fast alles in den Root verschoben

Typnamen haben sich nicht geändert: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, FileShareConfig und der Rest ist weiterhin vorhanden. In den meisten Dateien besteht die gesamte Änderung darin, Zeilen mit using zu löschen.

3. Startup: DoconutHost.Initialize und zwei Web.config‑Einträge

Das klassische Paket erstellte seinen Viewer pro Anforderung, wobei Optionen als Eigenschaften dieser Instanz bereitgestellt wurden. Das neue Paket hat einen Composition‑Root, der einmal in Application_Start gebaut wird, und der Viewer ist ein Service, den Sie auflösen:

// Vorher - Doconut.NETFramework 26.8.0 und früher, auf Anfrage
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0+ - Viewer aus DoconutHost aufgelöst, Lizenz einmal in DoconutHost.Initialize() konfiguriert
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize kommt in Application_Start und DoconutHost.Shutdown in Application_End, und Web.config erhält den DocImage.axd‑Handler und das Ressourcenmodul – beide finden Sie in Installation. Die pro‑Seite‑Erscheinungseinstellungen (FitType, FixedZoom, ShowHyperlinks, …) wurden vom Viewer‑Instanz zu den Optionen des Widgets verschoben, oder zu einem ViewerConfig, das an Viewer.RenderViewer übergeben wird (siehe ViewerConfig). new Viewer() kompiliert weiterhin, sobald DoconutHost.Initialize ausgeführt wurde, sodass migrierter Code‑Behind diese Zeile behalten kann, während Sie die Einstellungen verschieben.

Sicherheit funktioniert wie zuvor. Das Öffnen eines Dokuments gewährt der aktuellen ASP.NET‑Sitzung Zugriff auf dessen Seiten, und DocImage.axd verweigert allen anderen. Die DoconutUnSafeMode‑App‑Einstellung, die dies deaktivierte, ist jetzt options.UnsafeMode in DoconutHost.Initialize – lassen Sie sie false. Siehe Sitzungen & Sicherheit.

Der Startfehler, der die gesamte Seite zum Absturz bringt. Ein registriertes Plugin, dessen Fähigkeit keine Lizenz gewährt, wirft in Application_Start, und die Anwendung liefert dann für jede Anforderung ein leeres 500 – keine Fehlerseite, nichts im IIS‑Log, nur ein Eintrag im Windows‑Ereignisprotokoll (Quelle ASP.NET). Lizenzen werden aus wwwroot unter dem Site‑Root gelesen und nirgendwo sonst, und das Basis‑Doconut.Viewer.lic muss vorhanden sein, sonst werden die Plugin‑Lizenzen daneben nicht gelesen. Siehe Lizenz‑Einrichtung.

4. Webfarm: von einem Flag zum verteilten Modus

Das klassische Modell war viewer.IsWebfarm = true plus ExportToPng(path). Das neue Modell wird einmal registriert: Jeder Knoten teilt sich einen Speicher und einen Signaturschlüssel, und ein signiertes Ticket, das an den Browser gebunden ist, ersetzt „welcher Knoten auch immer antwortet“:

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath ist ein Alias
        d.SigningKey        = farmKey;                           // >= 32 bytes, auf jedem Knoten gleich
    }));

Öffnen Sie dann Dokumente wie gewohnt, binden den Browser (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) und übergeben viewer.AccessToken an das Widget mit dem Token. Sitzungen & Sicherheit hat die Schritte; das Webfarm-Beispiel ist ein vollständiger Knoten. IsWebfarm und WebfarmPath kompilieren weiterhin, aber sie schalten nichts mehr um.

Zwei Dinge, die wie Erfolg aussehen, es aber nicht tun: DistributedDocumentPublisher.PublishAsync schreibt die gerenderten Dateien eines Dokuments, öffnet jedoch keine Sitzung, sodass ein Betrachter, der auf ein veröffentlichtes Token zeigt, das ~2 KB‑Fehlerbild mit Status 200 erhält; und ein Testclient ohne das doconut-client‑Cookie erhält dasselbe Bild, nicht ein 401. Unterscheiden Sie eine echte Seite vom Fehlerbild anhand der Größe.

5. Konvertierung ist ein Plugin und viel kleiner

Das SourceFormatConverter‑Enum, die zwölf *ConfigConverter‑Klassen und deren verschachtelten Ziel‑Enums werden durch ein Enum, ConversionTarget, und einen Aufruf ersetzt:

using System.IO;
using System.Threading;
using Doconut;
using Doconut.Configs.Conversion;

// Angenommen DoconutHost ist bereits initialisiert und ein CancellationToken mit dem Namen ct ist verfügbar.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* Ihr Eingabestream */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

Das Quellformat stammt aus der übergebenen Erweiterung. Es gibt keinen Kompatibilitäts‑Shim: Jede SourceFormatConverter‑Referenz ist ein Kompilierfehler, den Sie durch Löschen beheben. Die pro‑Format‑Option‑Objekte haben es nicht überlebt — WordConfigConverter.HtmlOptions und CadConfigConverter.CadOptions.ShowColor haben keine Entsprechung über ConvertAsync. In Web Forms sollten Sie niemals auf ConvertAsync blockieren — siehe Konverter‑Plugin.

6. Cloud‑Speicher: Zugriff als gemeinsamen Ordner

Die Cloud‑Konfigurationstypen wurden unverändert nach Doconut.Clouds verschoben. Die Cloud‑Request‑Handler hingegen sind ASP.NET‑Core‑Komponenten, und eine klassische Anwendung hat keine Pipeline, um sie auszuführen. Von einer System.Web‑Seite aus greifen Sie auf Cloud‑Speicher als gemeinsamen Ordner zu – auf Azure ein Azure‑Files‑Share, das auf jedem Knoten gemountet ist – adressiert über FileShareConfig.

7. Die clientseitigen Änderungen, die stillschweigend fehlschlagen

Jeder untenstehende Punkt kompiliert, läuft, protokolliert nichts und macht das Falsche:

Drei weitere: Der Viewer zeichnet seine eigene Symbolleiste nicht (Ihre Seite verbindet Zoom, Next, GotoPage und den Rest mit ihren eigenen Schaltflächen); ein Viewer, der in einem versteckten Bootstrap‑Modal erstellt wird, misst 0×0 und zeichnet nichts, bis Sie seinem Container eine explizite Höhe geben und ihn bei shown.bs.modal neu anpassen; und AllowSearch verwendet standardmäßig false für PDF, sodass ein Dokument perfekt gerendert wird, während jede Suche nichts zurückliefert.

8. Was verschwindet

Vorgeschlagene Arbeitsreihenfolge

1. Ziel neu ausrichten, das Paket austauschen und Global.asax mit DoconutHost.Initialize und den beiden Web.config Registrierungen kompilieren lassen. Die Seite sollte starten.
2. Eine Viewer‑Seite: ein Dokument zum Rendern erhalten, dann Abschnitt 7 durcharbeiten, bis die Symbolleiste, Suche und Anmerkungen funktionieren. In einem echten Browser überprüfen — in diesem Abschnitt wird kein Fehler ausgelöst.
3. Konvertierung (Abschnitt 5): mechanisch und die meisten Kompilierungsfehler.
4. Die restlichen Seiten, wobei die portierten Beispiele als Diff‑Ziel verwendet werden.
5. Der Web‑Farm (Abschnitt 4), falls vorhanden. Mit zwei Knoten und einem Browser testen oder mit einem Client, der Cookies speichert.