Jak funguje prohlížeč

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.
• Doconut middleware — 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í nezávisle ve správci relací a jsou čištěny vypršením mezipaměti nebo explicitním CloseDocument(token).

Už jej nebudete konstruovat. AddDoconut() jej registruje jako přechodnou službu; injektujte jej, kdekoli 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 přijmě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 už nejsou správné, protože neobsahují nic, co by stálo za cachování.

Co se děje uvnitř OpenDocumentAsync

1. Licenční brána. Odmítnutá nebo verze‑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ření se nikdy tiše nepřepne na nižší úroveň 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: nevyhodí výjimku — přejde na vodoznak.
2. Vytvoření relace. Továrna prohlížeče vybere správný prohlížeč formátu podle přípony souboru a načte dokument (viz Rendering Pipeline). Relace je uložena v IMemoryCache pod čerstvým GUID tokenem s posuvný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: do relace se zapíše marker secure-{token}, 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.

Neexistuje samostatný krok zahřátí. Předchozí knihovna poskytovala InitCache() pro tento účel; již neexistuje a nic jej 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 řídí detekci formátu.

Jak widget získává stránky

Klientský widget volá Doconut middleware s tokenem v řetězci dotazu. Co middleware udělá, závisí na požadavku:

Každá z těchto cest se nejprve ověří:

• No token → middleware vrátí 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 s Session 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 nesoucí token, kdekoliv jej nasadíte. Referenční aplikace 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é — posuvné vypršení provádí stejný úklid automaticky — ale pro velké dokumenty je to slušný způsob, jak uvolnit paměť, jakmile uživatel skončí.

Je voláno na injektovaném Viewer. Předchozí vzor — konstrukce krátkodobého Viewer v bloku using výhradně pro uzavření tokenu — nemá ekvivalent a není potřeba.

Závěry

• Jeden otevřený dokument = jedna relace = jeden token. Tokeny jsou na relaci prohlížeče, ne globální URL.
• Token vyprší v posuvném okně; prohlížeč ponechaný nečinný po dobu DocOptions.TimeOut potřebuje opětovné otevření.
• Viewer může být injektováno a volně sdíleno; relace nesou celý stav.