Реализация управления документами с Doconut

Рабочий процесс управления документами в .NET портале обычно требует три вещи:

1. Способ загрузки PDF, файлов Office, чертежей CAD или изображений без необходимости писать просмотрщик с нуля.
2. Безопасный токен, связывающий загруженный документ с текущим сеансом браузера.
3. Шаг очистки, освобождающий память сразу после завершения работы пользователя.

Doconut предоставляет всё это через единственный сервис Viewer, легковесный сеанс IMemoryCache и явные вызовы CloseDocument.

---

1. Зарегистрировать просмотрщик в контейнере DI

Во время запуска приложения добавьте сервисы Doconut в контейнер DI, вызвав метод регистрации Doconut, описанный в официальной документации. Этот шаг регистрирует просмотрщик, обработку лицензий и кэш в памяти, который будет хранить сеансы документов.

Регистрация проверяет лицензию при запуске, поэтому любая отсутствующая или недействительная лицензия приводит к быстрой ошибке, и вы узнаёте о проблеме до того, как первый запрос достигнет сервера.

---

2. Вставьте middleware, обслуживающий изображения страниц, миниатюры и данные аннотаций

Настройте middleware Doconut в конвейере запросов так, чтобы любой запрос, содержащий строку запроса ?token=, обрабатывался Doconut. Middleware применяет маркер безопасности по умолчанию (secure-{token}), когда UnsafeMode равно false (по умолчанию), и обслуживает изображения страниц, миниатюры и данные аннотаций.

Размещение middleware на отдельной ветке оставляет остальную часть вашего конвейера нетронутой и позволяет горизонтальное масштабирование без привязанных сеансов.

---

3. Откройте документ и получите непрозрачный токен сеанса

Создайте единый endpoint, который принимает путь к файлу (или поток) и возвращает токен. Токен — единственное удостоверение, которое видит клиентский виджет.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Токен является непрозрачным — передайте его виджету, никогда не записывайте в журнал и не сохраняйте его.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Contract.pdf");
    return Results.Ok(new { token });
});

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

1. Проверка лицензии – недействительная лицензия сразу генерирует LicenseException.
2. Создание сеанса – Doconut выбирает подходящий просмотрщик формата (PDF, Word, DWG, …) и сохраняет движок в IMemoryCache под GUID‑токеном.
3. Регистрация безопасности – с помощью UnsafeMode = false токен привязывается к ASP.NET‑сеансу вызывающего через маркер secure-{token}. Только этот сеанс браузера может запрашивать страницы.
4. Возврат токена – клиент получает токен и использует его для каждого последующего запроса (/DocImage.axd?token=…).

Скользящее время истечения по умолчанию — 60 минут (настраивается через DocOptions.TimeOut). Каждый запрос страницы сбрасывает таймер, поэтому неактивные сеансы исчезают автоматически.

---

4. Отобразите документ на клиентской стороне

Из браузера вы вызываете endpoint, получаете токен и передаёте его виджету Doconut:

fetch('/api/open', { method: 'POST' })
    .then(r => r.json())
    .then(d => {
        const token = d.token;
        objViewer.View(token);   // JavaScript виджет, поставляемый Doconut
    });

Виджет внутренне отправляет запросы страниц, миниатюр, поиска и аннотаций, которые все включают один и тот же token. Поскольку токен привязан к сеансу на стороне сервера, злоумышленник не может захватить документ другого пользователя.

---

5. Закройте документ, как только пользователь покинет просмотрщик

Для больших PDF или CAD файлов следует сразу освободить движок рендеринга. Вызовите CloseDocument из серверного endpoint или из события «unload» виджета.

// Server‑side конечная точка
app.MapPost("/api/close", (Viewer viewer, string token) =>
{
    viewer.CloseDocument(token);
    return Results.Ok();
});

// Прямой вызов из виджета (если вы раскрываете токен backend)
viewer.CloseDocument(token);

CloseDocument удаляет сеанс из кэша, освобождает underlying document engine, удаляет маркер secure-{token} и отзывает доступ. Скользящее истечение времени в конечном итоге сделает то же самое, но явное закрытие гарантирует, что память будет освобождена сразу после завершения работы пользователя.

---

6. Необязательно: Конвертировать документ на сервере

Если ваш процесс требует экспорта PDF из загруженного Word‑файла, включите плагин Converter в конфигурации Doconut (см. документацию). После регистрации плагина вы можете внедрить DocumentConverter и вызвать его метод ConvertAsync. Конверсия выполняется на сервере, поэтому вам никогда не понадобится Office, установленный на веб‑сервере.

---

7. Соображения масштабирования для корпоративного управления документами

• Фронтенды без состояния – Виджет просмотрщика никогда не хранит данные документа; вся тяжёлая работа остаётся на сервере.
• Распределённый кэш – Замените кэш в памяти по умолчанию на распределённый провайдер (Redis, NCache), если у вас несколько узлов веб‑фермы. Соответствие токен‑сеанс работает без изменений, потому что middleware читает из сконфигурированного IMemoryCache.
• Фоновые задачи – Вы можете предварительно открывать документы в фоновом воркере, кэшировать токен и передавать его UI позже. Помните, что каждый токен одноразовый за сеанс; повторное использование требует нового вызова OpenDocumentAsync.

Эти шаблоны позволяют построить платформу управления документами, масштабируемую от односерверного интранет‑портала до многорегионального облачного сервиса без переписывания логики просмотрщика.

---

8. Быстрый чек‑лист для готовой к продакшену реализации

Шаг	Действие
1	Зарегистрировать сервисы Doconut в Program.cs (проверка лицензии).
2	Добавить middleware Doconut на отдельной ветке.
3	Открыть endpoint /api/open, который вызывает OpenDocumentAsync.
4	Передать возвращённый токен в objViewer.View(token) на клиенте.
5	Вызвать CloseDocument(token), когда просмотрщик скрыт или страница выгружается.
6	(Опционально) Включить ConverterPlugin, если нужна серверная конверсия.
7	(Опционально) Заменить IMemoryCache на распределённый кэш для горизонтального масштабирования.

Следуйте списку, и у вас будет полный, безопасный, высокопроизводительный поток управления документами, построенный на нативном .NET просмотрщике Doconut.

---