Как работает Viewer
Жизненный цикл запросов документа
Doconut рендерит документы в виде постраничных изображений, обслуживаемых через middleware ASP.NET Core. Понимание жизненного цикла — открытие, токен, запросы страниц, закрытие — объясняет почти все наблюдаемые поведения, включая сообщения об ошибках.
Три движущих компонента
Viewer— публичный сервис, который вы внедряете. Он открывает документы и возвращает токены сеанса.- Сеанс документа — объект на стороне сервера, хранящий загруженный документ, индексируемый токеном в
IMemoryCache. - Middleware Doconut — добавлен
UseDoconut(); отвечает на каждый запрос, который делает виджет браузера (pages,thumbnails,search,annotations, …), всегда аутентифицированный токеном.
Viewer без состояния — по замыслу
Viewer закрыт, не хранит состояние документа для каждого запроса и преднамеренно не реализует IDisposable. Сеансы живут независимо в менеджере сеансов и очищаются по истечении кэша или явным CloseDocument(token).
Вы больше не создаёте его вручную. AddDoconut() регистрирует его как временный сервис; внедряйте его там, где он нужен:
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
- Лицензионный шлюз. Отклонённая или просроченная версия лицензии (в чёрном списке, подделана, или сборка вне окна обновления лицензии) сразу бросает
LicenseException, с причиной отклонения в сообщении — открытие никогда не деградирует тихо при недействительной (в отличие от отсутствующей) лицензии. Календарно‑просроченная временная или подписочная лицензия — исключение: она не бросает исключение, а переходит в режим водяного знака. - Создание сеанса. Фабрика просмотрщика выбирает подходящий просмотрщик формата по расширению файла и загружает документ (см. Rendering Pipeline). Сеанс сохраняется в
IMemoryCacheпод новым GUID‑токеном с скользящим истечением —DocOptions.TimeOutминут, по умолчанию 60. Каждый запрос страницы сбрасывает таймер. - Регистрация безопасности. С
UnsafeMode = false(по умолчанию) токен привязывается к ASP.NET‑сеансу вызывающего: в сеанс записывается маркерsecure-{token}, поэтому только браузерный сеанс, открывший документ, может запрашивать его страницы. - Токен возвращается. Это единственное удостоверение для всех последующих операций.
Отдельного шага прогрева нет. Предыдущая библиотека предоставляла 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=…© / &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 клиента должен соответствовать ему — см. КонфигурацияПросмотрщика.
Обслуживание страниц из общего хранилища вместо узла открытия — это полностью другая схема; см. Распределённые развертывания.
Закрытие документа
viewer.CloseDocument(token);CloseDocument удаляет сеанс из кэша (что освобождает движок документа и сразу освобождает его память), удаляет маркер secure-{token} и отзывает право доступа. Вызывать его необязательно — скользящее истечение делает ту же очистку автоматически — но для больших документов это вежливый способ освободить память сразу после завершения работы пользователя.
Он вызывается у внедрённого Viewer. Предыдущий шаблон — создание кратковременного Viewer в блоке using исключительно для закрытия токена — не имеет эквивалента и не нужен.
Ключевые выводы
- Один открытый документ = один сеанс = один токен. Токены привязаны к браузерному сеансу, а не к глобальным URL.
- Токен истекает по скользящему окну; просмотрщик, оставленный бездействующим более
DocOptions.TimeOut, требует повторного открытия. Viewerможно внедрять и свободно делиться; сеансы несут всё состояние.
Была ли эта страница полезной?