Jak funguje Viewer
Životní cyklus požadavků na dokument
Doconut renderuje 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é součá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, indexovaný 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ý, neuchovává žádný stav dokumentu na požadavek a úmyslně neimplementuje IDisposable. Relace žijí samostatně ve správci relací a jsou vyčištěny vypršením mezipaměti nebo explicitním CloseDocument(token).
Už jej nebudete konstruovat. AddDoconut() ho registruje jako přechodnou službu; injektujte jej kdekoliv jej potřebujete:
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync($"files/{fileName}");
return Results.Content(token, "text/plain");
});V aplikaci MVC jej vezměte jako parametr konstruktoru; v Razor pohledu použijte @inject Doconut.Viewer Viewer. Cache vlastněné aplikací pro instance Viewer již nejsou potřeba — a také nejsou správné, protože neobsahují nic, co by stálo za cachování.
Co se děje uvnitř OpenDocumentAsync
- License gate. Odmítnutá nebo verze‑expirovaná 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ření se nikdy tiše nevrátí pro neplatnou (na rozdíl od chybějící) licenci. Licence s kalendářním vypršením (Temporary nebo předplatná) je výjimkou: nevyhodí výjimku — degraduje na vodoznak. - Session creation. Továrna vieweru vybere správný viewer formátu podle přípony souboru a načte dokument (viz Rendering Pipeline). Relace je uložena v
IMemoryCachepod čerstvým GUID tokenem s klouzavým vypršením —DocOptions.TimeOutminut, výchozí 60. Každý požadavek na stránku resetuje časovač. - Security registration. S
UnsafeMode = false(výchozí) je token svázán se session ASP.NET volajícího: do session se zapíše 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.
Neexistuje samostatný krok zahřátí. Předchozí knihovna poskytovala InitCache() pro tento účel; již neexistuje a nic ho nenahrazuje.
Tři přetížení se liší pouze 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 | Fulltextové 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 v tomto balíčku |
?token=…&action=rotate/flip/close | Akce stránky a explicitní uzavření |
?token=…&AnnSave=… / &AnnLoad | Ukládání/načítání anotací |
Každá z těchto cest je nejprve ověřena:
- No token → middleware vrací 404 (nebo banner verze, když
ShowDoconutInfo = true). - Unknown or expired token → chybový obrázek s
Document session not found. Please re-open document. - Session middleware missing (s
UnsafeMode = false) → HTTP 500 sSession middleware not configured. Call UseSession() before UseDoconut(). - Token opened by a different browser session → chybový obrázek s
You Are Not Authorized To View This Page.
Kde je middleware nasazen
UseDoconut() odpovídá na požadavky, které nesou token, kdekoliv jej nasadíte. Běžné nastavení zachovává historický tvar požadavku DocImage.axd na větvi MapWhen, takže existující klient nadále volá URL, kterou vždy používal. Ať zvolíte cokoli, BasePath klienta musí s tím souhlasit — viz ViewerConfig.
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é — klouzavé vypršení provádí stejný úklid automaticky — ale pro velké dokumenty je to zdvořilý způsob, jak uvolnit paměť okamžitě po dokončení uživatelem.
Je voláno na injektovaném Viewer. Předchozí vzor — konstruování krátkodobého Viewer v bloku using čistě pro uzavření tokenu — nemá ekvivalent a není potřeba.
Závěry
- Jeden otevřený dokument = jedna relace = jeden token. Tokeny jsou vázány na session prohlížeče, ne na globální URL.
- Token vyprší po klouzavém intervalu; viewer, který zůstane nečinný déle než
DocOptions.TimeOut, vyžaduje opětovné otevření. Viewermůže být injektováno a volně sdíleno; relace nesou celý stav.
Byla tato stránka užitečná?