Как работает Viewer

Жизненный цикл запросов документа

Doconut рендерит документы в виде постраничных изображений, обслуживаемых через middleware ASP.NET Core. Понимание жизненного цикла — открытие, токен, запросы страниц, закрытие — объясняет почти все наблюдаемые поведения, включая сообщения об ошибках.

Три движущих компонента

  • Viewer — публичный сервис, который вы внедряете. Он открывает документы и возвращает токены сессий.
  • The document session — объект на стороне сервера, хранящий загруженный документ, идентифицируемый токеном в IMemoryCache.
  • The Doconut middleware — добавлен UseDoconut(); отвечает на каждый запрос, который делает виджет браузера (pages, thumbnails, search, annotations, …), всегда аутентифицированный токеном.

Viewer без состояния — по замыслу

Viewer закрыт, не хранит состояние документа per-request и намеренно не реализует IDisposable. Сессии живут независимо в менеджере сессий и очищаются по истечении кэша или явным вызовом CloseDocument(token).

Внедрите его там, где он нужен:

csharp
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

Что происходит внутри OpenDocumentAsync

  1. License gate. Отклонённая или просроченная версия лицензии (в чёрном списке, подделана, или сборка вне окна обновления лицензии) сразу бросает LicenseException, с причиной отклонения в сообщении — открытие никогда не деградирует тихо для недействительной (в отличие от отсутствующей) лицензии. Исключение составляет лицензия Temporary или подписка, истёкшая по календарю: она не бросает исключение — переходит в режим водяного знака.
  2. Session creation. Фабрика просмотрщика выбирает подходящий просмотрщик формата по расширению файла и загружает документ (см. Rendering Pipeline). Сессия сохраняется в IMemoryCache под новым GUID‑токеном с скользящим истечением — DocOptions.TimeOut минут, по умолчанию 60. Каждый запрос страницы сбрасывает таймер.
  3. Security registration. С UnsafeMode = false (по умолчанию) токен привязывается к ASP.NET‑сессии вызывающего: в сессию записывается маркер secure-{token}, поэтому только браузерная сессия, открывшая документ, может запрашивать его страницы.
  4. Токен возвращается. Это единственное удостоверение для всего последующего.

Три перегрузки различаются только входными данными: путь к файлу, путь к файлу плюс конфигурация per-format (PdfConfig, WordConfig, …), или Stream плюс FileInfo, расширение которого определяет формат.

Как виджет получает страницы

Виджет клиента вызывает middleware Doconut с токеном в строке запроса. Что делает middleware, зависит от запроса:

ЗапросНазначение
?token=…&page=NИзображение отрисованной страницы (PNG)
?token=…&page=N&thumb=1Эскиз
?token=…&zoom=…Отрисовка увеличенной страницы
?token=…&search=termПолнотекстовый поиск (по лицензии)
?token=…&bookmarksСтруктура документа/закладки
?token=…&copy / &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.

Обслуживание страниц из общего хранилища вместо узла открытия — это совершенно другая схема; см. Distributed Deployments.

Закрытие документа

csharp
viewer.CloseDocument(token);

CloseDocument удаляет сессию из кэша (что освобождает движок документа и сразу освобождает его память), удаляет маркер secure-{token} и отзывает право доступа. Вызывать её необязательно — скользящее истечение делает ту же очистку автоматически — но для больших документов это вежливый способ освободить память, как только пользователь закончил.

Выводы

  • Один открытый документ = одна сессия = один токен. Токены привязаны к браузерной сессии, а не к глобальным URL.
  • Токен истекает по скользящему окну; просмотрщик, оставшийся бездействующим более DocOptions.TimeOut, требует повторного открытия.
  • Viewer можно внедрять и свободно делиться; сессии несут всё состояние.

Была ли эта страница полезной?