Fehlerbehebung
Diagnose gängiger Fehler
Jede nachfolgende Meldung ist der wörtliche Text, den Doconut erzeugt, 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.
Der Viewer meldet The viewer handler could not be reached (no response).
Die Anfrage erhielt nie eine Antwort. Eine häufige Ursache ist ein BasePath, das mit / beginnt: '/doconut' wird zu //doconut/DocImage.axd, eine Anfrage an einen anderen Host. Schreiben Sie es ohne den führenden Schrägstrich (BasePath: 'doconut').
Der Viewer meldet Please make sure your middleware is configured.
Der Seiten‑Endpunkt antwortete mit 404: UseDoconut() ist nicht dort eingebunden, wo der BasePath des Clients hinzeigt. Mit app.Map("/doconut", branch => branch.UseDoconut()) verwendet der Client BasePath: 'doconut'.
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. Session‑State 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 Fehlermotiv 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‑Anfragen 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 funktioniert — siehe Core Concepts → Sessions & Security. Die Ablehnung ist ein Bild, das mit dem Status 200 ausgeliefert wird, sodass ein Monitor, der nur Statuscodes prüft, es als Seite zählt.
Ein Fehlermotiv 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 falsch — ohne Fehlermeldungen
Dies sind die Fehlermodi, die Sie zuerst vermuten sollten, wenn Sie eine Anwendung weiterführen. Alle drei lassen den Server einwandfrei laufen, rendern das Dokument korrekt und melden nichts in der Browser‑Konsole.
Ein ständig drehender 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 ausgeblendet hätte, wird einfach nie ausgeführt. Übergeben Sie die Funktionen stattdessen als Optionen:
function ctlDoc_OnViewerBusy() { /* zeige deinen Busy-Indikator */ }
function ctlDoc_OnViewerReady() { /* verstecke ihn */ }
function ctlDoc_Copy(text) { /* verwende den kopierten Text */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* Fortschritt melden */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... deine bestehenden Optionen ...
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, Seiten sonst korrekt. ResPath ist leer oder verweist auf die Anwendungswurzel — in der vorherigen Bibliothek korrekt, hier falsch. Es muss das Präfix benennen, das UseDoconutResources() einbindet:
ResPath: 'doconut-res/images' // oder '<your ResourcesPath>/images'Defekte Kacheln für spätere Seiten beim Servieren aus gemeinsamem Speicher. Seiten, die noch geschrieben werden, antworten mit 202 Accepted. Ein Client ohne retryOn409: true behandelt das als fehlgeschlagenes Bild. Siehe Verteilte Deployments.
Ö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 verhindert 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 verarbeitet (hier: DICOM). Das Plugin ist registriert, aber keine Lizenz gewährt ihm mehr die Fähigkeit — typischerweise eine temporäre Lizenz, die nach dem Start der Anwendung abgelaufen ist. Installieren Sie eine Lizenz, die es gewährt, und überprüfen Sie IsCapabilityGranted(LicenseCapability.Dicom) auf IDoconutLicenseService. Ein fehlendes oder unzureichendes nicht‑temporäres Anrecht schlägt normalerweise früher fehl, während AddDoconut().
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 Ihre eigenen 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 ö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 erwähnt ein Plugin, das über AddPlugin registriert wurde — die aktuelle nicht‑temporäre Lizenz gewährt diesem Plugin keine Berechtigung. 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
Das Paket lässt sich überhaupt nicht installieren — Doconut.NETStandard 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 Doconut.NETFramework‑Paket.
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 festgelegt, die von Doconut.NETStandard deklariert wurden. 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 wie vom Paket deklariert).
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, kein kompatibles Update. Die meisten Fehler sind die using‑Zeilen, die in den Root‑Doconut‑Namespace verschoben wurden; arbeiten Sie sie durch Migrieren zu .NET Standard 2.1 statt sie einzeln zu patchen.
TypeInitializationException in der ersten Präsentationsdatei:
Could not load ... System.Drawing.Common, Version=6.0.0.0Die 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 tragen ein Wasserzeichen — die App befindet sich im Evaluierungsmodus: keine Lizenzdatei gefunden, eine abgelaufene temporäre Lizenz oder eine ungültige Domain. Unter einer aktiven temporären Lizenz wird nur die Plugin‑Ausgabe mit Wasserzeichen versehen. Ein Build, der nach dem Abonnementdatum einer bezahlten Lizenz veröffentlicht wurde, ist nicht mit Wasserzeichen versehen: Beim Öffnen wird LicenseException ausgelöst. Prüfen Sie IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — die Lizenzierungs‑Seite zeigt einen fertigen Endpunkt in IDoconutLicenseService.
Legacy‑Dokumente rendern verzerrten Text — Code‑Page‑Kodierungen werden standardmäßig nicht geladen. Fügen Sie sie einmal beim Start hinzu:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Falsche oder ersetzte Schriftarten — dem Server fehlen die Schriftarten des Dokuments. Installieren Sie sie oder verweisen Sie FontFolders (auf WordConfig/PptConfig) auf einen Ordner, der sie enthält.
Eine Bildanmerkung wird im Viewer angezeigt, aber der Export enthält ein „Image blocked“-Feld — der Host des Bildes hat eine private oder Loopback‑Adresse, die der Server nicht abrufen darf. Siehe Anmerkungen.
Feature funktionierte in der Evaluation, still in der Produktion
Die klassische Go-Live-Überraschung: 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 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
AllowSearchbeim Öffnen nicht aktiviert. Word, Excel und PowerPoint stellen denselben Schalter über ihr verschachteltesPdfConfigbereit. - 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 den Text bewahrt. - HTML und MS Project (MPP) sind in ihren Standardeinstellungen nicht durchsuchbar — setzen Sie
DefaultRender = false, damit sie über eine PDF‑Projektion mit nativer Textebene gerendert werden. Word, Excel, PowerPoint, TXT, Visio, E‑Mail, EPUB und MHT durchsuchen in ihren Katalog‑Standardeinstellungen. objViewer.CanSearch()ist nach der Initialisierungfalse— das aufgelöste Format hat keinen Standard‑Suchpfad. Dieses Urteil ist getrennt von der Such‑Lizenz; prüfen Sie beide.- Die Seite liest den Rückgabewert von
objViewer.Search(...)— die Anzahl kommt im dritten Argument, einem Callback, an.
Noch feststeckend?
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.
War diese Seite hilfreich?