Як працює переглядач
Життєвий цикл запиту документа
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
- Ліцензійний шлюз. Відхилена або прострочена за версією ліцензія (чорний список, підроблена або збірка поза вікном оновлення ліцензії) миттєво генерує
LicenseException, з причиною відхилення у повідомленні — відкриття ніколи не деградує безшумно для недійсної (на відміну від відсутньої) ліцензії. Ліцензія, що закінчилася за календарем (тимчасова або підписка), є винятком: вона не генерує виключення — переходить у водяний знак. - Створення сесії. Фабрика переглядача вибирає відповідний переглядач формату за розширенням файлу та завантажує документ (див. Rendering Pipeline). Сесія зберігається у
IMemoryCacheпід новим GUID токеном з ковзним терміном дії —DocOptions.TimeOutхвилин, за замовчуванням 60. Кожен запит сторінки скидає таймер. - Реєстрація безпеки. За допомогою
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 / &meta | Копіювання тексту, гіперпосилання, інформація про формат, технічні метадані 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.
Обслуговування сторінок з спільного сховища замість вузла відкриття — це зовсім інша схема; дивіться Розподілені розгортання.
Закриття документа
viewer.CloseDocument(token);CloseDocument видаляє сесію з кешу (що звільняє підлеглий движок документа та одразу звільняє його пам'ять), видаляє маркер secure-{token} і відкликає надання доступу. Викликати це необов'язково — ковзний термін дії виконує те ж саме автоматично — але для великих документів це ввічливий спосіб звільнити пам'ять, щойно користувач закінчив.
Висновки
- Один відкритий документ = одна сесія = один токен. Токени прив'язані до браузерної сесії, а не до глобальних URL.
- Токен закінчує термін дії у ковзному вікні; переглядач, який залишився без активності понад
DocOptions.TimeOut, потребує повторного відкриття. Viewerможна інжектувати та вільно ділитися; сесії несуть весь стан.
Чи була ця сторінка корисною?