Řešení problémů

Každá zpráva níže je doslovný text, který Doconut produkuje, uspořádaný podle symptomu. Najděte svou chybu, aplikujte opravu.

Prohlížeč nic nezobrazuje

Prázdná oblast prohlížeče, konzole prohlížeče plná 404 chyb pro /doconut-res/...
UseDoconutResources() chybí, nebo je umístěn po UseDoconut(). Musí být první v pipeline.

HTTP 500 s:

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

Tokenová bezpečnost 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 mezipaměť: v aplikaci minimal-API přidejte builder.Services.AddDistributedMemoryCache(), nebo se aplikace zastaví při spuštění 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 nedorazí k požadavkům stránky (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 Základní koncepty → Relace a bezpečnost.

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 čerstvý 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 nehlásí nic v konzoli prohlížeče.

Zaneprázdněný spinner, který nikdy nezastaví. Vaše zpětné volání prohlížeče jsou deklarována 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ředávejte funkce jako možnosti místo toho:

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

Dokument za spinnerem je v pořádku. Kompletní seznam možností je v KonfiguraceProhlížeče.

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() připojuje:

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

Poškozené 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 interpretuje jako neúspěšný obrázek. Viz Distribuovaná nasazení.

Otevření dokumentu selže

LicenseException s odmítavou zprávou — licenční soubor byl nalezen, ale odmítnut (neplatný podpis, poškozený, na černé listině, nebo sestavení mimo verzi/okno aktualizace licence). Tento stav blokuje otevření (rychlé selhání) místo degradace na vodoznak; přečtěte License.RejectionMessage pro důvod.

LicenseException:

This document type requires the 'Dicom' plugin license.

Rozšíření je zpracováváno pouze pluginem (zde: DICOM) a schopnost již není udělena. Zaregistrujte plugin a ověřte lic.IsCapabilityGranted(LicenseCapability.Dicom). Chybějící nebo nedostatečné nečasové oprávnění obvykle selže dříve během AddDoconut().

FormatNotSupportedException:

Document format '<extension>' is not supported.

Žádný prohlížeč — vestavěný, plugin nebo vlastní — nevyžaduje toto rozšíření. Zkontrolujte seznam podporovaných formátů; pro vlastní formáty může DoconutOptions.RegisterViewer přidat jeden.

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.

Selhání spuštění

InvalidOperationException zmiňující plugin registrovaný přes AddPlugin — aktuální nečasová licence nepřiděluje tuto schopnost pluginu. Odeberte registraci nebo nainstalujte licenci, která ji poskytuje. Chybějící licence a starý soubor TRIAL neposkytují žádné schopnosti pluginu.

ArgumentException od 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.

Validace možností fail-fast — opravte problematickou cestu.

Chyby sestavení / závislostí

Balíček se vůbec nenainstaluje — Doconut.NETStandard 26.8.0 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 připnul System.Text.Json nebo System.Text.Encodings.Web pod verzi 9.0.x závislostí deklarovaných 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 v auditovaném balíčku 26.8.0).

Stěna kompilátorových chyb ihned po zvýšení verze balíčku — to je očekávané. 26.8.0 má odlišnou API plochu než 26.7.0, není to kompatibilní aktualizace. Většina chyb jsou řádky using, které se přesunuly do kořenového jmenného prostoru Doconut; projděte si je pomocí Přechod na .NET Standard 2.1 místo postupného opravování.

TypeInitializationException v prvním prezentačním souboru:

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

Prezentační engine tvrdě 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 v evaluačním stavu: nebyl nalezen licenční soubor, vypršela dočasná nebo předplatitelská licence, nebo neplatná doména. Zkontrolujte IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — odkaz IDoconutLicenseService na stránce Licencování ukazuje připravený endpoint.

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 na Linux/Docker — kontejner postrádá písma dokumentu. Nasmerujte FontFolders (na WordConfig/PptConfig) na připojený adresář s fonty.

Prezentace se otevřou, ale selžou při vykreslování na Linux/macOS — aktuální renderér PPT/PPTX/PPS/POT/ODP vyžaduje nativní libgdiplus plus System.Drawing.EnableUnixSupport=true. Balíček poskytuje System.Drawing.Common 6.0.0, protože to je poslední verze, která tento přepínač podporuje.

Funkce fungovala v evaluačním režimu, v produkci tiše

Klasické překvapení při nasazení: aktivní dočasná licence poskytuje všechny schopnosti; vaše zakoupená licence poskytuje jen to, co jste si koupili. Balíčky pro vyhledávání a anotace mohou zmizet, pokud jejich schopnosti chybí. Registrované pluginy Converter nebo DICOM s nedostatečnou nečasovou licencí selžou během AddDoconut(). Porovnejte IsCapabilityGranted(...) se všemi funkcemi, které povolíte před nasazením.

Vyhledávání nic nenajde (nebo málo)

• Pro přímý PDF nebylo při otevření povoleno AllowSearch. Word, Excel a PowerPoint vystavují stejný přepínač přes své 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 renderovaly pomocí PDF projekce s nativní textovou vrstvou. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB a MHT vyhledávají ve svých výchozích katalogových nastaveních.
• objViewer.CanSearch() je po inicializaci false — rozpoznaný formát nemá standardní vyhledávací cestu. Toto rozhodnutí je oddělené od licence pro Vyhledávání; ověřte obojí.

Stále uvízl?

Izolujte problém vůči minimální aplikaci Quick Start; pokud se tam reprodukuje, kontaktujte podporu s dokumentem, vaším Program.cs a výstupem diagnostiky licence.