Fehlerbehebung

Jede nachfolgende Meldung ist der wörtliche Text, den Doconut erzeugt, geordnet nach Symptomen. Finden Sie Ihren Fehler und wenden Sie die Lösung an.

Der Viewer zeigt nichts

Leerer Viewer‑Bereich, Browser‑Konsole voll mit 404‑Fehlern für /doconut-res/...
UseDoconutResources() fehlt oder wurde nach UseDoconut() platziert. Es muss zuerst in der Pipeline aufgerufen werden.

HTTP 500 mit:

Session middleware not configured. Call UseSession() before UseDoconut().

Die Token‑Sicherheit von Doconut (standardmäßig aktiviert) benötigt ASP.NET‑Session‑State. Fügen Sie builder.Services.AddSession() und app.UseSession() vor dem Doconut‑Middleware‑Zweig hinzu. Der Session‑State benötigt außerdem einen Cache: In einer Minimal‑API‑App fügen Sie builder.Services.AddDistributedMemoryCache() hinzu, oder die Anwendung stoppt beim Start mit Unable to resolve service for type 'IDistributedCache' (MVC‑ und Razor‑Pages‑Apps registrieren bereits einen).

Ein Fehlermeldungs‑Bild im Seitenbereich mit dem Text:

You Are Not Authorized To View This Page.

Das Token wurde von einer anderen Browsersitzung geöffnet. Typische Ursachen: Das Session‑Cookie erreicht die Seiten‑Requests nicht (Cross‑Origin‑Setup, SameSite‑Richtlinie, ein API‑Client ohne Cookie‑Jar) oder die Anwendung wurde neu gestartet (neue Session‑Schlüssel). Dies ist die Sicherheitsschicht, die wie vorgesehen arbeitet — siehe Core Concepts → Sessions & Security.

Ein Fehlermeldungs‑Bild mit dem Text:

Document session not found. Please re-open document.

Das Token ist abgelaufen (gleitendes Fenster, Standard 60 Minuten — DocOptions.TimeOut) oder die Session wurde geschlossen. Öffnen Sie das Dokument erneut, um ein frisches Token zu erhalten.

Der Server ist in Ordnung, aber die Seite verhält sich seltsam — ohne Fehlermeldungen

Dies sind die Fehlermodi, die zuerst zu prüfen sind, wenn eine Anwendung weiterentwickelt wird. Alle drei lassen den Server einwandfrei laufen, rendern das Dokument korrekt und melden nichts in der Browser‑Konsole.

Ein dauernder Lade‑Spinner. Ihre Viewer‑Callbacks sind als globale Funktionen deklariert, die nach der Container‑ID benannt sind — ctlDoc_OnViewerReady() und Freunde. Der vorherige Viewer hat diese Namen nachgeschlagen; dieser nicht. Der Handler, der den Spinner ausblenden würde, wird nie ausgeführt. Übergeben Sie die Funktionen stattdessen als Optionen:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

Das Dokument hinter dem Spinner ist in Ordnung. Die vollständige Optionsliste finden Sie in ViewerConfig.

Fehlende Viewer‑Icons oder Chrome, sonst korrekte Seiten. ResPath ist leer oder zeigt auf das Anwendungs‑Root — im vorherigen Bibliothek korrekt, hier falsch. Es muss das Präfix angeben, das UseDoconutResources() bereitstellt:

ResPath: 'doconut-res/images'   // or '<your ResourcesPath>/images'

Beschädigte Kacheln für spätere Seiten bei Bereitstellung aus gemeinsam genutztem Speicher. Seiten, die noch geschrieben werden, antworten mit 202 Accepted. Ein Client ohne retryOn409: true behandelt das als fehlgeschlagenes Bild. Siehe Distributed Deployments.

Öffnen eines Dokuments schlägt fehl

LicenseException mit Ablehnungsnachricht — die Lizenzdatei wurde gefunden, aber abgelehnt (ungültige Signatur, manipuliert, auf der schwarzen Liste, oder ein Build außerhalb des Lizenz‑Versions‑/Update‑Fensters). Dieser Zustand blockiert das Öffnen (Fail‑Fast) statt zu einer Wasserzeichen‑Darstellung zu degradieren; lesen Sie License.RejectionMessage für den Grund.

LicenseException:

This document type requires the 'Dicom' plugin license.

Die Erweiterung wird nur von einem Plugin (hier: DICOM) unterstützt und die Fähigkeit ist nicht mehr gewährt. Registrieren Sie das Plugin und prüfen Sie lic.IsCapabilityGranted(LicenseCapability.Dicom). Eine fehlende oder unzureichende nicht‑temporäre Berechtigung schlägt normalerweise bereits früher bei AddDoconut() fehl.

FormatNotSupportedException:

Document format '<extension>' is not supported.

Kein Viewer — eingebaut, Plugin oder benutzerdefiniert — unterstützt diese Erweiterung. Prüfen Sie die Liste der unterstützten Formate; für eigene Formate kann DoconutOptions.RegisterViewer einen hinzufügen.

InvalidDataException — der Dateiinhalt ist beschädigt oder stimmt nicht mit seiner Erweiterung überein (z. B. eine umbenannte Datei). Validieren Sie Uploads, bevor Sie sie öffnen.

InvalidOperationException:

No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Sie haben DocumentConverter verwendet, ohne das Converter‑Plugin zu registrieren.

Startfehler

InvalidOperationException mentioning a plugin registered via AddPlugin — die aktuelle nicht‑temporäre Lizenz gewährt diese Plugin‑Fähigkeit nicht. Entfernen Sie die Registrierung oder installieren Sie eine Lizenz, die sie gewährt. Eine fehlende Lizenz und eine veraltete TRIAL‑Datei gewähren keine Plugin‑Fähigkeiten.

ArgumentException von AddDoconut():

DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

Fehlerhafte Optionenvalidierung — korrigieren Sie den fehlerhaften Pfad.

Build‑/Abhängigkeitsfehler

Das Paket lässt sich überhaupt nicht installieren — Doconut.NETStandard 26.8.0 zielt auf netstandard2.1 ab, sodass NuGet ein .NET‑Framework‑Projekt ablehnt. Dies ist kein auflösbarer Wiederherstellungsfehler: .NET Framework kann netstandard2.1 nicht konsumieren. Verwenden Sie stattdessen das Paket Doconut.NETFramework.

Compiler‑Fehler CS1705 oder zur Laufzeit beim Öffnen eines Dokuments:

Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

Ihr Projekt hat System.Text.Json oder System.Text.Encodings.Web unter die 9.0.x‑Abhängigkeiten von Doconut.NETStandard festgelegt. Entfernen Sie das Downgrade und lassen Sie NuGet den Paketgraphen wiederherstellen (System.Text.Json 9.0.0 und System.Text.Encodings.Web 9.0.0 im geprüften 26.8.0‑Paket).

Eine Flut von Compiler‑Fehlern unmittelbar nach dem Aktualisieren des Pakets — das ist zu erwarten. 26.8.0 hat eine andere API‑Oberfläche als 26.7.0 und ist kein kompatibles Update. Die meisten Fehler betreffen die using‑Zeilen, die in den Root‑Namespace Doconut verschoben wurden; arbeiten Sie die Änderungen durch Migrieren zu .NET Standard 2.1, anstatt sie einzeln zu patchen.

TypeInitializationException bei der ersten Präsentationsdatei:

Could not load ... System.Drawing.Common, Version=6.0.0.0

Die Präsentations‑Engine erfordert zwingend System.Drawing.Common 6.0.0 (im Paket deklariert). Entfernen oder überschreiben Sie diese Abhängigkeit nicht — jeder Versuch, PPT/PPTX/PPS/POT/ODP zu öffnen, schlägt ohne sie fehl.

Ausgabe sieht falsch aus

Seiten enthalten ein Wasserzeichen — die Anwendung befindet sich im Evaluierungsmodus: keine Lizenzdatei gefunden, ein abgelaufenes temporäres oder Abonnement‑Fenster oder eine ungültige Domain. Prüfen Sie IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — die Referenz auf IDoconutLicenseService der Lizenz‑Seite zeigt ein fertiges Endpunkt‑Objekt.

Altdokumente zeigen verzerrten Text — Code‑Page‑Kodierungen werden standardmäßig nicht geladen. Fügen Sie einmal beim Starten hinzu:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Falsche oder ersetzte Schriftarten unter Linux/Docker — der Container enthält nicht die Schriften des Dokuments. Zeigen Sie FontFolders (auf WordConfig/PptConfig) auf ein gemountetes Schriftverzeichnis.

Präsentationen öffnen, können jedoch unter Linux/macOS nicht gerendert werden — der aktuelle PPT/PPTX/PPS/POT/ODP‑Renderer benötigt das native libgdiplus plus System.Drawing.EnableUnixSupport=true. Das Paket liefert System.Drawing.Common 6.0.0, weil dies die letzte Version ist, die diesen Schalter honoriert.

Feature funktionierte in der Evaluation, ist in der Produktion still

Der klassische Überraschungsmoment beim Go‑Live: Eine aktive temporäre Lizenz gewährt jede Fähigkeit; Ihre gekaufte Lizenz gewährt nur das, was Sie erworben haben. Such‑ und Anmerkungs‑Bundles können verschwinden, wenn deren Fähigkeiten fehlen. Registrierte Converter‑ oder DICOM‑Plugins mit einer unzureichenden nicht‑temporären Lizenz schlagen beim Aufruf von AddDoconut() fehl. Vergleichen Sie IsCapabilityGranted(...) mit jeder Funktion, die Sie vor dem Deployment aktivieren.

Suche findet nichts (oder zu wenig)

• Für ein direktes PDF war AllowSearch zum Öffnungszeitpunkt nicht aktiviert. Word, Excel und PowerPoint stellen denselben Schalter über ihr verschachteltes PdfConfig bereit.
• Der Inhalt ist gescannt bzw. nur Bild, sodass die normale Suche keinen Textlayer zum Abgleichen hat. Verwenden Sie eine textbasierte Quelle oder eine PDF‑Projektion, die den Text erhält.
• HTML und MS Project (MPP) sind in ihren Standard‑Einstellungen nicht durchsuchbar — setzen Sie DefaultRender = false, damit sie über eine PDF‑Projektion mit nativen Textlayer gerendert werden. Word, Excel, PowerPoint, TXT, Visio, E‑Mail, EPUB und MHT durchsuchen Sie mit ihren Katalog‑Standardwerten.
• objViewer.CanSearch() ist nach der Initialisierung false — das aufgelöste Format hat keinen Standard‑Suchpfad. Dieses Ergebnis ist unabhängig von der Such‑Lizenz; prüfen Sie beide.

Noch feststeckend?

Isolieren Sie das Problem anhand der minimalen Quick Start app; wenn es dort reproduziert wird, kontaktieren Sie den Support mit dem Dokument, Ihrer Program.cs und der Lizenzdiagnoseausgabe.