Jak funguje Viewer

Doconut vykresluje dokumenty jako stránkované obrázky poskytované prostřednictvím middleware ASP.NET Core. Porozumění životnímu cyklu — otevření, token, požadavky na stránky, uzavření — vysvětluje téměř veškeré chování, které můžete pozorovat, včetně chybových zpráv.

Tři pohyblivé části

• Viewer — veřejná služba, kterou injektujete. Otevírá dokumenty a vrací tokeny relace.
• Relace dokumentu — objekt na straně serveru, který drží načtený dokument, klíčovaný tokenem v IMemoryCache.
• Middleware Doconut — přidáno pomocí UseDoconut(); odpovídá na každý požadavek, který widget prohlížeče provádí (pages, thumbnails, search, annotations, …), vždy autentizováno tokenem.

Viewer je bezstavový — záměrně

Viewer je uzavřený (sealed), neuchovává žádný stav dokumentu na požadavek a úmyslně neimplementuje IDisposable. Relace žijí nezávisle v správci relací a jsou čištěny vypršením mezipaměti nebo explicitním voláním CloseDocument(token).

Injektujte jej kdekoliv potřebujete:

app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

Co se děje uvnitř OpenDocumentAsync

1. Licenční brána. Odmítnutá nebo vypršená licence (na černé listině, pozměněná nebo sestavení mimo aktualizační okno licence) okamžitě vyhodí LicenseException s důvodem odmítnutí jako zprávou — otevírání se nikdy tiše nepropadá pro neplatnou (na rozdíl od chybějící) licenci. Výjimkou je licence Temporary nebo předplatná, která vypršela kalendářně: nevyhodí výjimku — degraduje se na vodoznak.
2. Vytvoření relace. Továrna viewerů vybere správný viewer formátu podle přípony souboru a načte dokument (viz Rendering Pipeline). Relace je uložena v IMemoryCache pod novým GUID tokenem s klouzavým vypršením — DocOptions.TimeOut minut, výchozí 60. Každý požadavek na stránku resetuje časovač.
3. Registrace zabezpečení. S UnsafeMode = false (výchozí) je token svázán s ASP.NET relací volajícího: marker secure-{token} je zapsán do relace, takže pouze relace prohlížeče, která dokument otevřela, může požadovat jeho stránky.
4. Token je vrácen. Je to jediné pověření pro vše, co následuje.

Tyto tři přetížení se liší pouze vstupem: cesta k souboru, cesta k souboru plus konfigurace pro konkrétní formát (PdfConfig, WordConfig, …) nebo Stream plus FileInfo, jehož přípona určuje detekci formátu.

Jak widget získává stránky

Klientský widget volá middleware Doconut s tokenem v řetězci dotazu. To, co middleware provádí, závisí na požadavku:

Každá z těchto cest je nejprve validována:

• Žádný token → middleware vrátí 404 (nebo banner verze, když je ShowDoconutInfo = true).
• Neznámý nebo vypršený token → chybový obrázek s textem Relace dokumentu nebyla nalezena. Prosím znovu otevřete dokument.
• Middleware relace chybí (s UnsafeMode = false) → HTTP 500 s textem Middleware relace není nakonfigurován. Zavolejte UseSession() před UseDoconut().
• Token otevřený jinou relací prohlížeče → chybový obrázek s textem Nemáte oprávnění zobrazit tuto stránku.

Uzavření dokumentu

viewer.CloseDocument(token);

CloseDocument odstraní relaci z mezipaměti (což uvolní podkladový dokumentový engine a okamžitě uvolní jeho paměť), smaže marker secure-{token} a odvolá přístupové oprávnění. Volání je volitelné — klouzavé vypršení provede stejný úklid automaticky — ale pro velké dokumenty je to zdvořilý způsob, jak uvolnit paměť okamžitě po dokončení uživatelem.

Závěry

• Jeden otevřený dokument = jedna relace = jeden token. Tokeny jsou na relaci prohlížeče, ne globální URL.
• Token vyprší po uplynutí klouzavého okna; viewer ponechaný nečinný přes DocOptions.TimeOut vyžaduje opětovné otevření.
• Viewer může být injektován a volně sdílen; relace nesou veškerý stav.