Jak funguje Viewer
Životní cyklus požadavků na dokument
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é pozorujete, 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ý provádí widget prohlížeče (pages,thumbnails,search,annotations, …), vždy autentizováno tokenem.
Viewer je bezstavový — záměrně
Viewer je uzavřený, neuchovává žádný stav dokumentu na požadavek a úmyslně neimplementuje IDisposable. Relace žijí nezávisle ve správci relací a jsou čištěny vypršením platnosti cache nebo explicitním CloseDocument(token).
Injektujte to 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
- Licenční brána. Odmítnutá nebo verze‑expirovaná licence (na černé listině, poškozená, nebo sestavení mimo aktualizační okno licence) okamžitě vyhodí
LicenseException, s důvodem odmítnutí jako zprávou — otevření se nikdy tiše nepropadá pro neplatnou (na rozdíl od chybějící) licenci. Licence s kalendářním vypršením – dočasná nebo předplatitelská – je výjimkou: nevyhazuje výjimku — přechází na vodoznak. - Vytvoření relace. Továrna prohlížeče vybere správný formátový prohlížeč pro příponu souboru a načte dokument (viz renderovací pipeline). Relace je uložena v
IMemoryCachepod čerstvým GUID tokenem s posuvnou expirací —DocOptions.TimeOutminut, výchozí 60. Každý požadavek na stránku resetuje časovač. - Registrace zabezpečení. S
UnsafeMode = false(výchozí) je token svázán se session ASP.NET volajícího: do session je zapsán markersecure-{token}, takže pouze session prohlížeče, která dokument otevřela, může požadovat jeho stránky. - Token je vrácen. Je to jediné pověření pro vše, co následuje.
Tři přetížení se liší jen vstupem: cesta k souboru, cesta k souboru plus konfigurace pro každý 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 udělá, závisí na požadavku:
| Dotaz | Účel |
|---|---|
?token=…&page=N | Vykreslený obrázek stránky (PNG) |
?token=…&page=N&thumb=1 | Náhled |
?token=…&zoom=… | Zvětšené vykreslení stránky |
?token=…&search=term | Full‑textové vyhledávání (licencí řízené) |
?token=…&bookmarks | Osnova dokumentu/záložky |
?token=…© / &showlinks / &fileFormat | Kopírování textu, hypertextové odkazy a informace o formátu |
?token=…&meta | Technická metadata DICOM; vrací 501 pro DICOM relaci na .NET 6 |
?token=…&action=rotate/flip/close | Akce stránky a explicitní uzavření |
?token=…&AnnSave=… / &AnnLoad | Uložit/načíst anotace |
Každá z těchto cest je nejprve validována:
- Žádný token → middleware vrátí 404 (nebo banner verze, když
ShowDoconutInfo = true). - Neznámý nebo vypršený token → chybový obrázek s
Document session not found. Please re-open document. - Chybí middleware relace (s
UnsafeMode = false) → HTTP 500 sSession middleware not configured. Call UseSession() before UseDoconut(). - Token otevřený jinou relací prohlížeče → chybový obrázek s
You Are Not Authorized To View This Page.
Poskytování stránek ze sdíleného úložiště místo otevíracího uzlu je zcela odlišné uspořádání; viz Distributed Deployments.
Uzavření dokumentu
viewer.CloseDocument(token);CloseDocument odstraňuje relaci z cache (což uvolní podkladový dokumentový engine a okamžitě uvolní jeho paměť), maže marker secure-{token} a odvolává přístupové oprávnění. Volání je volitelné — posuvná expirace provádí stejný úklid automaticky — ale pro velké dokumenty je to zdvořilý způsob, jak uvolnit paměť, jakmile uživatel skončí.
Závěry
- Jeden otevřený dokument = jedna relace = jeden token. Tokeny jsou na úrovni session prohlížeče, ne globální URL.
- Token vyprší po posuvném časovém okně; prohlížeč ponechaný nečinný po
DocOptions.TimeOutpotřebuje znovu otevření. Viewermůže být injektován a volně sdílen; relace nesou celý stav.
Byla tato stránka užitečná?