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

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

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

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

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

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

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

Вы больше не создаёте его вручную. AddDoconut() регистрирует его как временный сервис; внедряйте его там, где он нужен:

csharp
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

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

Отдельного шага прогрева нет. Предыдущая библиотека предоставляла InitCache() для этой цели; он больше не существует, и ничто его не заменяет.

Три перегрузки различаются только входными данными: путь к файлу, путь к файлу плюс конфигурация для формата (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‑сеанса в этом пакете
?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 клиента должен соответствовать ему — см. КонфигурацияПросмотрщика.

Обслуживание страниц из общего хранилища вместо узла открытия — это полностью другая схема; см. Распределённые развертывания.

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

csharp
viewer.CloseDocument(token);

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

Он вызывается у внедрённого Viewer. Предыдущий шаблон — создание кратковременного Viewer в блоке using исключительно для закрытия токена — не имеет эквивалента и не нужен.

Ключевые выводы

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

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