Як працює переглядач
Життєвий цикл запиту документа
Doconut рендерить документи у вигляді розбитих на сторінки зображень, що подаються через middleware ASP.NET Core. Розуміння життєвого циклу — відкриття, токен, запити сторінок, закриття — пояснює майже всю поведінку, яку ви спостерігатимете, включно з повідомленнями про помилки.
Три рухомі частини
Viewer— публічний сервіс, який ви інжектуєте. Він відкриває документи та повертає токени сесії.- Сесія документа — об’єкт на боці сервера, що зберігає завантажений документ, індексований токеном у
IMemoryCache. - middleware Doconut — додається
UseDoconut(); відповідає на кожен запит, який робить віджет браузера (pages,thumbnails,search,annotations, …), завжди автентифікований токеном.
Viewer є безстанним — за задумом
Viewer є запечатаний, не містить стану документа на запит і навмисно не реалізує IDisposable. Сесії живуть незалежно в менеджері сесій і очищуються внаслідок закінчення терміну кешу або явного CloseDocument(token).
Ви більше не створюєте його. AddDoconut() реєструє його як транзієнтний сервіс; інжектуйте його там, де потрібно:
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync($"files/{fileName}");
return Results.Content(token, "text/plain");
});У MVC‑застосунку беріть його як параметр конструктора; у Razor‑виді використовуйте @inject Doconut.Viewer Viewer. Кеші, що належать застосунку, з екземплярів Viewer більше не потрібні — і більше не правильні, бо вони не містять нічого, що варто кешувати.
Що відбувається всередині OpenDocumentAsync
- Ліцензійний контроль. Відхилена або прострочена за версією ліцензія (чорний список, підроблена або збірка поза вікном оновлення ліцензії) миттєво викидає
LicenseException, з причиною відхилення у повідомленні — відкриття ніколи не деградує мовчки для недійсної (на відміну від відсутньої) ліцензії. Ліцензія Temporary або підписки, прострочена за календаром, є винятком: вона не викидає — деградує до водяного знаку. - Створення сесії. Фабрика переглядача вибирає відповідний переглядач формату за розширенням файлу та завантажує документ (див. Rendering Pipeline). Сесія зберігається у
IMemoryCacheпід новим GUID‑токеном з ковзним терміном дії —DocOptions.TimeOutхвилин, за замовчуванням 60. Кожен запит сторінки скидає таймер. - Реєстрація безпеки. За допомогою
UnsafeMode = false(за замовчуванням) токен прив'язується до ASP.NET‑сесії виклику: у сесію записується маркерsecure-{token}, тому лише браузерна сесія, яка відкрила документ, може запитувати його сторінки. - Токен повертається. Це єдині облікові дані для всього, що слідує.
Окремого кроку прогрівання немає. Попередня бібліотека надавала InitCache() для цієї мети; вона більше не існує, і нічого її не замінює.
Три перевантаження відрізняються лише вхідними даними: шлях до файлу, шлях до файлу плюс конфігурація per-format (PdfConfig, WordConfig, …), або Stream плюс FileInfo, розширення якого визначає формат.
Як віджет отримує сторінки
Віджет клієнта викликає Doconut middleware з токеном у рядку запиту. Те, що робить middleware, залежить від запиту:
| Запит | Призначення |
|---|---|
?token=…&page=N | Зображення відрендереної сторінки (PNG) |
?token=…&page=N&thumb=1 | Мініатюра |
?token=…&zoom=… | Збільшене рендеринг сторінки |
?token=…&search=term | Повнотекстовий пошук (з захистом ліцензії) |
?token=…&bookmarks | Структура документа/закладки |
?token=…© / &showlinks / &fileFormat | Копіювання тексту, гіперпосилання та інформація про формат |
?token=…&meta | Технічні метадані DICOM; повертає 501 для DICOM‑сесії в цьому пакеті |
?token=…&action=rotate/flip/close | Дії зі сторінками та явне закриття |
?token=…&AnnSave=… / &AnnLoad | Збереження/завантаження анотацій |
Кожен з цих шляхів спочатку проходить валідацію:
- Відсутній токен → middleware повертає 404 (або банер версії, коли
ShowDoconutInfo = true). - Невідомий або прострочений токен → зображення помилки з
Document session not found. Please re-open document. - Відсутній middleware сесії (з
UnsafeMode = false) → HTTP 500 зSession middleware not configured. Call UseSession() before UseDoconut(). - Токен відкрито іншим браузерним сеансом → зображення помилки з
You Are Not Authorized To View This Page.
Де змонтовано middleware
UseDoconut() відповідає на запити, що містять токен, де б ви його не змонтували. Типове налаштування зберігає історичну форму запиту DocImage.axd на гілці MapWhen, тому існуючий клієнт продовжує викликати URL, який завжди використовував. Яке б рішення ви не обрали, BasePath клієнта має відповідати йому — див. КонфігураціяПереглядача.
Обслуговування сторінок з спільного сховища замість вузла відкриття — це зовсім інша організація; див. Розподілені розгортання.
Закриття документа
viewer.CloseDocument(token);CloseDocument видаляє сесію з кешу (що звільняє підлеглий движок документа і одразу звільняє його пам'ять), видаляє маркер secure-{token} і відкликає наданий доступ. Викликати його необов'язково — ковзний термін дії робить те ж саме автоматично — проте для великих документів це ввічливий спосіб звільнити пам'ять одразу після завершення користувачем.
Він викликається на інжектованому Viewer. Попередній шаблон — створення короткоживущого Viewer у блоці using лише для закриття токену — не має еквіваленту і не потрібен.
Висновки
- Один відкритий документ = одна сесія = один токен. Токени прив'язані до браузерної сесії, а не до глобальних URL.
- Токен закінчує термін дії у ковзному вікні; переглядач, що залишився без дії понад
DocOptions.TimeOut, потребує повторного відкриття. Viewerможна інжектувати та вільно ділитися; сесії містять весь стан.
Чи була ця сторінка корисною?