Как работает Viewer
Жизненный цикл запросов документа
Doconut отображает документы в виде постраничных изображений, обслуживаемых через middleware ASP.NET Core. Понимание жизненного цикла — открытие, токен, запросы страниц, закрытие — объясняет почти все наблюдаемые поведения, включая сообщения об ошибках.
Три движущих компонента
Viewer— публичный сервис, который вы внедряете. Он открывает документы и возвращает токены сеанса.- Сессия документа — объект на стороне сервера, хранящий загруженный документ, ключевой по токену в
IMemoryCache. - Промежуточное ПО Doconut — добавлен
UseDoconut(); отвечает на каждый запрос, который делает виджет браузера (pages,thumbnails,search,annotations, …), всегда аутентифицированный токеном.
Viewer без состояния — по замыслу
Viewer закрыт, не хранит состояние документа для каждого запроса и намеренно не реализует 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можно внедрять и свободно делиться; сессии несут всё состояние.
Была ли эта страница полезной?