Řešení problémů
Diagnostika běžných chyb
Každá zpráva níže je doslovný text, který Doconut produkuje, uspořádaný podle symptomu. Najděte svou chybu, aplikujte opravu.
Prohlížeč nezobrazuje nic
Prázdná oblast prohlížeče, konzole prohlížeče plná 404 pro /doconut-res/...
UseDoconutResources() chybí, nebo je umístěn po UseDoconut(). Musí být první v pipeline.
Prohlížeč hlásí The viewer handler could not be reached (no response).
Požadavek nikdy nedostal odpověď. Častou příčinou je BasePath, který začíná /: '/doconut' se stane //doconut/DocImage.axd, požadavek na jiný hostitel. Zapište jej bez úvodní lomítka (BasePath: 'doconut').
Prohlížeč hlásí Please make sure your middleware is configured.
Koncový bod stránky odpověděl 404: UseDoconut() není namontován tam, kam ukazuje BasePath klienta. S app.Map("/doconut", branch => branch.UseDoconut()) klient používá BasePath: 'doconut'.
HTTP 500 s:
Session middleware not configured. Call UseSession() before UseDoconut().Bezpečnost tokenu Doconut (ve výchozím nastavení zapnutá) vyžaduje stav relace ASP.NET. Přidejte builder.Services.AddSession() a app.UseSession() před větví middleware Doconut. Stav relace také potřebuje cache: v aplikaci minimal-API přidejte builder.Services.AddDistributedMemoryCache(), nebo se aplikace zastaví při startu s Unable to resolve service for type 'IDistributedCache' (aplikace MVC a Razor Pages již jednu registrovanou mají).
Obrázek chyby v oblasti stránky s textem:
You Are Not Authorized To View This Page.Token byl otevřen jinou relací prohlížeče. Typické příčiny: cookie relace nedosahuje požadavků na stránku (nastavení cross-origin, politika SameSite, API klient bez úložiště cookie), nebo se aplikace restartovala (nové klíče relace). Toto je bezpečnostní vrstva fungující podle návrhu — viz Core Concepts → Sessions & Security. Odmítnutí je obrázek podávaný se stavem 200, takže monitor, který kontroluje jen stavové kódy, jej počítá jako stránku.
Obrázek chyby s textem:
Document session not found. Please re-open document.Token vypršel (posuvné okno, výchozí 60 minut — DocOptions.TimeOut) nebo byla relace uzavřena. Znovu otevřete dokument pro nový token.
Server je v pořádku, ale stránka se chová špatně — bez jakékoli chyby
Toto jsou režimy selhání, které je třeba podezřívat jako první po nasazení aplikace. Všechny tři nechávají server fungovat perfektně, vykreslují dokument správně a v konzoli prohlížeče nehlásí nic.
Zaneprázdněný spinner, který nikdy neustane. Vaše callbacky prohlížeče jsou deklarovány jako globální funkce pojmenované podle ID kontejneru — ctlDoc_OnViewerReady() a přátelé. Předchozí prohlížeč tyto názvy vyhledával; tento ne. Obsluha, která by spinner skryla, se prostě nikdy nespustí. Předejte funkce jako možnosti místo toho:
function ctlDoc_OnViewerBusy() { /* zobrazte svůj indikátor zaneprázdnění */ }
function ctlDoc_OnViewerReady() { /* skryjte to */ }
function ctlDoc_Copy(text) { /* použijte zkopírovaný text */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* oznamovat průběh */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... vaše existující možnosti ...
onViewerBusy: ctlDoc_OnViewerBusy,
onViewerReady: ctlDoc_OnViewerReady,
onCopy: ctlDoc_Copy,
onAutoLoadStatus: ctlDoc_AutoLoadStatus
});Dokument za spinnerem je v pořádku. Úplný seznam možností je v ViewerConfig.
Chybějící ikony prohlížeče nebo chrome, stránky jinak správné. ResPath je prázdný nebo ukazuje na kořen aplikace — v předchozí knihovně správně, zde špatně. Musí pojmenovat prefix, který UseDoconutResources() namontuje:
ResPath: 'doconut-res/images' // nebo '<your ResourcesPath>/images'Rozbité dlaždice pro pozdější stránky při servírování ze sdíleného úložiště. Stránky, které jsou stále zapisovány, odpovídají 202 Accepted. Klient bez retryOn409: true to považuje za selhaný obrázek. Viz Distributed Deployments.
Otevření dokumentu selže
LicenseException s odmítavou zprávou — soubor licence byl nalezen, ale odmítnut (neplatný podpis, poškozený, na černé listině nebo sestavení mimo verzi/okno aktualizace licence). Tento stav blokuje otevření (okamžité selhání) místo degradace na vodoznak; přečtěte si License.RejectionMessage pro důvod.
LicenseException:
This document type requires the 'Dicom' plugin license.Rozšíření je zpracováváno pouze pluginem (zde: DICOM). Plugin je zaregistrován, ale žádná licence již neuděluje jeho schopnost — typicky dočasná licence, která vypršela po spuštění aplikace. Nainstalujte licenci, která to povolí, a ověřte IsCapabilityGranted(LicenseCapability.Dicom) na IDoconutLicenseService. Chybějící nebo nedostatečné ne‑dočasné oprávnění obvykle selže dříve, během AddDoconut().
FormatNotSupportedException:
Document format '<extension>' is not supported.Žádný prohlížeč — vestavěný, plugin ani vlastní — nevyžaduje toto rozšíření. Zkontrolujte seznam podporovaných formátů; pro vlastní formáty jej může přidat DoconutOptions.RegisterViewer.
InvalidDataException — obsah souboru je poškozený nebo neodpovídá jeho rozšíření (např. přejmenovaný soubor). Ověřte nahrané soubory před otevřením.
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().Vyřešili jste DocumentConverter bez registrace pluginu Converter.
Spuštění selže
InvalidOperationException zmiňující plugin registrovaný přes AddPlugin — aktuální ne‑dočasná licence neuděluje tomuto pluginu oprávnění. Odeberte registraci nebo nainstalujte licenci, která to povolí. Chybějící licence a starý soubor TRIAL neposkytují žádná pluginová oprávnění.
ArgumentException from 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.Okamžitá validace možností — opravte problematickou cestu.
Chyby sestavení / závislostí
Balíček se vůbec nenainstaluje — Doconut.NETStandard cílí na netstandard2.1, takže NuGet odmítá projekt .NET Framework. Toto není řešitelná chyba obnovení: .NET Framework nemůže konzumovat netstandard2.1. Použijte místo toho balíček Doconut.NETFramework.
Chyba kompilátoru CS1705, nebo za běhu při otevírání dokumentu:
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'Váš projekt upíná System.Text.Json nebo System.Text.Encodings.Web pod verzi 9.0.x závislostí deklarovaných v Doconut.NETStandard. Odstraňte downgrade a nechte NuGet obnovit graf balíčků (System.Text.Json 9.0.0 a System.Text.Encodings.Web 9.0.0 podle deklarace balíčku).
Hromada chyb kompilace ihned po zvýšení verze balíčku — to je očekávané. 26.8.0 má odlišné API oproti 26.7.0, nejde o kompatibilní aktualizaci. Většina chyb jsou řádky using, které se přesunuly do kořenového jmenného prostoru Doconut; projděte je pomocí Přechod na .NET Standard 2.1 místo jejich postupného opravování.
TypeInitializationException v prvním prezentačním souboru:
Could not load ... System.Drawing.Common, Version=6.0.0.0Prezentační engine pevně vyžaduje System.Drawing.Common 6.0.0 (deklarováno balíčkem). Neodstraňujte ani nepřepisujte tuto závislost — každé otevření PPT/PPTX/PPS/POT/ODP selže bez ní.
Výstup vypadá špatně
Stránky nesou vodoznak — aplikace je ve stavu hodnocení: nebyl nalezen soubor licence, vypršela dočasná licence nebo neplatná doména. Při aktivní dočasné licenci je vodoznak pouze u výstupu pluginu. Sestavení vydané po datu předplatného placené licence není opatřeno vodoznakem: při otevření vyvolá LicenseException. Prozkoumejte IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — odkaz na IDoconutLicenseService na stránce Licensing ukazuje připravený koncový bod.
Starší dokumenty vykreslují poškozený text — kódové stránky nejsou načteny ve výchozím nastavení. Přidejte jednou při spuštění:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Špatná nebo nahrazená písma — server postrádá písma dokumentu. Nainstalujte je nebo nasměrujte FontFolders (na WordConfig/PptConfig) na složku, která je obsahuje.
Obrázková anotace se zobrazuje v prohlížeči, ale export má políčko „Image blocked“ — hostitel obrázku má soukromou nebo smyčkovou adresu, kterou server odmítá načíst. Viz Anotace.
Funkce fungovala v hodnocení, v produkci je tichá
Klasické překvapení při spuštění: aktivní dočasná licence poskytuje všechny funkce; vaše zakoupená licence poskytuje jen to, co jste si zakoupili. Balíčky pro vyhledávání a anotace mohou zmizet, když jejich funkce chybí. Registrovaný převodník nebo DICOM pluginy s nedostatečnou ne‑dočasnou licencí selžou během AddDoconut(). Porovnejte IsCapabilityGranted(...) s každou funkcí, kterou povolíte před nasazením.
Vyhledávání nic nenajde (nebo příliš málo)
- Pro přímý PDF nebylo při otevření povoleno
AllowSearch. Word, Excel a PowerPoint vystavují stejný přepínač přes jejich vnořenýPdfConfig. - Obsah je skenovaný / pouze obrázek, takže běžné vyhledávání nemá textovou vrstvu k porovnání. Použijte zdroj s textem nebo PDF projekci, která zachovává text.
- HTML a MS Project (MPP) nejsou ve výchozím nastavení prohledávatelné — nastavte
DefaultRender = false, aby se vykreslovaly pomocí PDF projekce s nativní textovou vrstvou. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB a MHT vyhledávají ve výchozím nastavení katalogu. objViewer.CanSearch()je po inicializacifalse— rozpoznaný formát nemá standardní cestu pro vyhledávání. Toto hodnocení je oddělené od licence pro vyhledávání; ověřte obojí.- Stránka čte návratovou hodnotu
objViewer.Search(...)— počet přichází ve třetím argumentu, jako zpětné volání.
Stále uvízli?
Izolujte problém pomocí minimální aplikace Quick Start; pokud se tam reprodukuje, kontaktujte podporu s dokumentem, vaším Program.cs a výstupem diagnostiky licence.
Byla tato stránka užitečná?