Як працює переглядач
Життєвий цикл запиту документа
Doconut відображає документи у вигляді розбитих на сторінки зображень, які подаються через middleware ASP.NET Core. Розуміння життєвого циклу — відкриття, токен, запити сторінок, закриття — пояснює майже всю поведінку, яку ви спостерігатимете, включаючи повідомлення про помилки.
Три взаємодіючі частини
Viewer— публічний сервіс, який ви інжектуєте. Він відкриває документи та повертає токени сесії.- Сесія документа — об’єкт на боці сервера, що зберігає завантажений документ, індексований токеном у
IMemoryCache. - Middleware Doconut — додається
UseDoconut(); відповідає на кожен запит, який робить віджет браузера (pages,thumbnails,search,annotations, …), завжди автентифікований токеном.
Viewer є безстанним — за задумом
Viewer є sealed, не містить стану документа для кожного запиту і навмисно не реалізує IDisposable. Сесії існують незалежно в менеджері сесій і очищуються вичерпанням кешу або явним CloseDocument(token).
Інжектуйте його там, де потрібно:
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync($"files/{fileName}");
return Results.Content(token, "text/plain");
});Що відбувається всередині OpenDocumentAsync
- License gate. Відхилена або застаріла ліцензія (чорний список, підроблена або збірка поза вікном оновлення ліцензії) одразу викидає
LicenseException, причину відхилення у повідомленні — відкриття ніколи не деградує без повідомлення для недійсної (на відміну від відсутньої) ліцензії. Ліцензія Temporary або підписки, термін якої закінчився за календарем, є винятком: вона не викидає помилку — переходить у водяний знак. - Session creation. Фабрика переглядача вибирає відповідний переглядач формату за розширенням файлу і завантажує документ (див. Rendering Pipeline). Сесія зберігається у
IMemoryCacheпід новим GUID токеном з ковзним терміном дії —DocOptions.TimeOutхвилин, за замовчуванням 60. Кожен запит сторінки скидає таймер. - Security registration. За допомогою
UnsafeMode = false(за замовчуванням) токен прив’язується до ASP.NET сесії виклику: в сесію записується маркерsecure-{token}, тому лише браузерна сесія, яка відкрила документ, може запитувати його сторінки. - Токен повертається. Це єдині облікові дані для всього подальшого.
Три перевантаження відрізняються лише вхідними даними: шлях до файлу, шлях до файлу плюс конфігурація для формату (PdfConfig, WordConfig, …) або Stream плюс FileInfo, розширення якого визначає формат.
Як віджет отримує сторінки
Віджет клієнта викликає middleware Doconut з токеном у рядку запиту. Що робить 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 сесії на .NET 6 |
?token=…&action=rotate/flip/close | Дії зі сторінками та явне закриття |
?token=…&AnnSave=… / &AnnLoad | Збереження/завантаження анотацій |
Кожен з цих шляхів спочатку проходить валідацію:
- No token → middleware повертає 404 (або банер версії, коли
ShowDoconutInfo = true). - Unknown or expired token → зображення помилки з
Document session not found. Please re-open document. - Session middleware missing (з
UnsafeMode = false) → HTTP 500 зSession middleware not configured. Call UseSession() before UseDoconut(). - Token opened by a different browser session → зображення помилки з
You Are Not Authorized To View This Page.
Обслуговування сторінок з спільного сховища замість вузла відкриття — це зовсім інша схема; див. Розподілені розгортання.
Закриття документа
viewer.CloseDocument(token);CloseDocument видаляє сесію з кешу (що звільняє підлеглий движок документа і одразу звільняє пам'ять), видаляє маркер secure-{token} і відкликає доступ. Викликати це необов'язково — ковзний термін дії виконує те ж саме автоматично — але для великих документів це ввічливий спосіб звільнити пам'ять одразу після завершення користувачем.
Висновки
- Один відкритий документ = одна сесія = один токен. Токени прив'язані до браузерної сесії, а не до глобальних URL.
- Токен закінчує термін дії у ковзному вікні; переглядач, який залишився без дії після
DocOptions.TimeOut, потребує повторного відкриття. Viewerможна інжектити та вільно ділитися; сесії містять весь стан.
Чи була ця сторінка корисною?