Ř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 a 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í nasazen tam, kde ukazuje BasePath klienta. S app.Map("/doconut", branch => branch.UseDoconut()) klient používá BasePath: 'doconut'.

HTTP 500 s:

text
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 cache: 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 registrují).

Obrázek chyby v oblasti stránky s textem:

text
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 pracují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:

text
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.

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í (fail-fast) místo degradace na vodoznak; přečtěte License.RejectionMessage pro důvod.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

Rozšíření je zpracováváno pouze pluginem (zde: DICOM). Plugin je registrová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é nedočasové oprávnění obvykle selže během AddDoconut().

FormatNotSupportedException:

text
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 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:

text
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. Odstraňte registraci nebo nainstalujte licenci, která ji poskytuje. Chybějící licence a starý soubor TRIAL neposkytují žádné schopnosti pluginu.

ArgumentException od AddDoconut():

text
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í

Chyba kompilátoru CS1705, nebo za běhu při otevírání dokumentu:

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

Váš projekt připnul System.Text.Json nebo System.Text.Encodings.Web pod verzi 8.0.x závislostí deklarovaných v Doconut.NET8. Odstraňte downgrad a nechte NuGet obnovit graf balíčků (System.Text.Json 8.0.5 a System.Text.Encodings.Web 8.0.0).

Výstup vypadá špatně

Stránky nesou vodoznak — aplikace je v evaluačním stavu: nebyl nalezen licenční soubor, vypršela dočasná licence nebo neplatná doména. Při aktivní dočasné licenci je vodoznak pouze na výstupu pluginu. Sestavení vydané po datu předplatného placené licence není vodoznakováno: při otevírání vyvolá LicenseException. Prozkoumejte IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — odkaz na IDoconutLicenseService na stránce Licencování ukazuje připravený koncový bod.

Legacy dokumenty vykreslují poškozený text — kódové stránky nejsou ve výchozím nastavení načteny v .NET 8. Přidejte jednou při spuštění:

csharp
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. Na Linuxu viz níže.

Obrázková anotace se zobrazuje v prohlížeči, ale export má pole „Image blocked“ — hostitel obrázku má soukromou nebo loopback adresu, kterou server odmítá načíst. Viz Anotace.

Linux

Otevření libovolného dokumentu selže s:

text
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Nainstalujte knihovnu pro konfiguraci fontů: apt-get install -y libfontconfig1 (fontconfig na RHEL/Fedora). Viz Instalace.

Otevření libovolného dokumentu selže s:

text
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.

Aplikace odkazuje na novější SkiaSharp, přímo nebo přes jinou knihovnu. Přidejte SkiaSharp.NativeAssets.Linux ve stejné verzi jako ten SkiaSharp.

Otevření libovolného dokumentu selže s:

text
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.

Hostitel není podporovaná platforma. Alpine a další distribuce založené na musl nejsou podporovány: použijte obraz založený na Debianu nebo Ubuntu.

Text je na Windows širší nebo užší, nebo se řádky lámají jinak — písma dokumentu nejsou nainstalována, takže Doconut použije nejbližší nainstalované písmo. Nainstalujte metricky kompatibilní písma (fonts-liberation pro Arial, Times New Roman a Courier New; fonts-crosextra-carlito a fonts-crosextra-caladea pro Calibri a Cambria), nebo zkopírujte vlastní licencovaná písma do /usr/share/fonts/ a spusťte fc-cache -f. Asijský text zobrazený jako prázdné políčka vyžaduje fonts-noto-cjk.

Funkce fungovala v hodnocení, v produkci tiše

Klasické překvapení při nasazení: aktivní dočasná licence poskytuje všechny funkce; vaše zakoupená licence poskytuje jen to, co jste si koupili. 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í nenajde nic (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 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 tak, aby se vykreslovaly pomocí PDF projekce s nativní textovou vrstvou. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB a MHT jsou ve výchozím nastavení katalogu prohledávatelné.
  • objViewer.CanSearch() je po inicializaci false — 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á?