Fehlerbehebung

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

Der Viewer zeigt nichts

Leerer Viewer‑Bereich, Browser‑Konsole voller 404‑Fehler für /doconut-res/...
UseDoconutResources() fehlt oder steht nach UseDoconut(). Es muss zuerst in der Pipeline stehen.

HTTP 500 mit:

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

Die Token‑Sicherheit von Doconut (standardmäßig aktiviert) benötigt ASP.NET‑Sitzungszustand. Fügen Sie builder.Services.AddSession() und app.UseSession() vor dem Doconut‑Middleware‑Zweig hinzu. Sitzungszustand benötigt ebenfalls 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 Fehlersymbol 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 Sitzungs‑Cookie erreicht die Seitenanfragen nicht (Cross‑Origin‑Setup, SameSite‑Richtlinie, ein API‑Client ohne Cookie‑Speicher), oder die Anwendung wurde neu gestartet (neue Sitzungs‑Schlüssel). Dies ist die Sicherheits­schicht, die wie vorgesehen funktioniert — siehe Core Concepts → Sessions & Security.

Ein Fehlersymbol mit dem Text:

Document session not found. Please re-open document.

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

Öffnen eines Dokuments schlägt fehl

LicenseException mit einer Ablehnungsnachricht — die Lizenzdatei wurde gefunden, aber abgelehnt (ungültige Signatur, manipuliert, gesperrt oder ein Build außerhalb des Versions‑/Update‑Fensters der Lizenz). Dieser Zustand blockiert das Öffnen (Fail‑Fast) anstatt zu einem Wasserzeichen 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) verarbeitet und die Fähigkeit wird nicht mehr gewährt. Registrieren Sie das Plugin und prüfen Sie lic.IsCapabilityGranted(LicenseCapability.Dicom). Ein fehlendes oder unzureichendes nicht‑temporäres Anrecht schlägt normalerweise bereits während AddDoconut() fehl.

FormatNotSupportedException:

Document format '<extension>' is not supported.

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

InvalidDataException — der Dateiinhalt ist beschädigt oder stimmt nicht mit der Erweiterung überein (z. B. eine umbenannte Datei). Validieren Sie Uploads vor dem Öffnen.

InvalidOperationException:

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

Sie haben DocumentConverter gelöst, ohne das Converter‑Plugin zu registrieren.

Startvorgang schlägt fehl

InvalidOperationException mit Hinweis auf ein über AddPlugin registriertes Plugin — 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.

Fail‑Fast‑Optionen‑Validierung — korrigieren Sie den fehlerhaften Pfad.

Build‑/Abhängigkeitsfehler

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

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

Ihr Projekt hat System.Text.Json oder System.Text.Encodings.Web unter die 8.0.x‑Abhängigkeiten festgelegt, die von Doconut.NET6 deklariert wurden. Entfernen Sie das Downgrade und lassen Sie NuGet den Paket‑Graphen wiederherstellen (System.Text.Json 8.0.6 und System.Text.Encodings.Web 8.0.0 im geprüften 26.7.0‑Paket).

TypeInitializationException in 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 (vom Paket deklariert). Entfernen oder überschreiben Sie diese Abhängigkeit nicht — jedes Öffnen von PPT/PPTX/PPS/POT/ODP schlägt ohne sie fehl.

Ausgabe sieht falsch aus

Seiten enthalten ein Wasserzeichen — die Anwendung befindet sich im Evaluations‑Modus: 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 Lizenz‑Seite zeigt in der Referenz IDoconutLicenseService einen fertigen Endpunkt.

Legacy‑Dokumente rendern unleserlichen Text — Code‑Seiten‑Kodierungen werden in .NET 6 nicht standardmäßig geladen. Fügen Sie einmal beim Start hinzu:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Falsche oder ersetzte Schriftarten unter Linux/Docker — der Container fehlt die Schriftarten des Dokuments. Zeigen Sie FontFolders (auf WordConfig/PptConfig) auf ein gemountetes Schriftarten‑Verzeichnis.

Präsentationen öffnen, aber die Darstellung schlägt unter Linux/macOS fehl — der aktuelle PPT/PPTX/PPS/POT/ODP‑Renderer erfordert native libgdiplus plus System.Drawing.EnableUnixSupport=true. Das Paket liefert System.Drawing.Common 6.0.0, weil das die letzte Version ist, die diesen Schalter unterstützt.

Funktion funktionierte in der Evaluation, ist in der Produktion still

Die klassische Überraschung 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‑Pakete können verschwinden, wenn ihre Fähigkeiten fehlen. Registrierte Converter‑ oder DICOM‑Plugins mit einer unzureichenden nicht‑temporären Lizenz schlagen während AddDoconut() fehl. Vergleichen Sie IsCapabilityGranted(...) mit jeder Funktion, die Sie vor der Bereitstellung 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/nur Bild, sodass die normale Suche keinen Textlayer zum Abgleichen hat. Verwenden Sie eine texthaltige Quelle oder eine PDF‑Projektion, die Text bewahrt.
• HTML und MS Project (MPP) sind in ihren Standardeinstellungen nicht durchsuchbar — setzen Sie DefaultRender = false, damit sie über eine PDF‑Projektion mit nativen Textlayer rendern. Word, Excel, PowerPoint, TXT, Visio, E‑Mail, EPUB und MHT durchsuchen in ihren Katalog‑Standardwerten.
• objViewer.CanSearch() ist nach der Initialisierung false — das aufgelöste Format hat keinen standardmäßigen Suchpfad. Dieses Urteil ist getrennt von der Such‑Lizenz; prüfen Sie beide.

Noch festgefahren?

Isolieren Sie das Problem anhand der minimalen Quick‑Start‑App; wenn es dort reproduziert wird, kontaktieren Sie den Support mit dem Dokument, Ihrem Program.cs und der Lizenz‑Diagnoseausgabe.