Впровадження управління документами з Doconut

Робочий процес управління документами у .NET порталі зазвичай потребує трьох речей:

1. Способу завантажувати PDF, файли Office, креслення CAD або зображення без написання власного переглядача.
2. Безпечного токену, який прив’язує завантажений документ до поточної браузерної сесії.
3. Кроку очищення, який звільняє пам’ять, щойно користувач закінчив роботу.

Doconut забезпечує всі три через один Viewer сервіс, легковаговий IMemoryCache сеанс і явні виклики CloseDocument.

---

1. Зареєструйте переглядач у DI‑контейнері

Під час запуску застосунку додайте сервіси Doconut у DI‑контейнер, викликавши метод реєстрації Doconut, описаний в офіційній документації. Цей крок реєструє переглядач, обробку ліцензії та кеш у пам’яті, який буде зберігати сеанси документів.

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

---

2. Додайте проміжне ПЗ, що обслуговує зображення сторінок, мініатюри та дані анотацій

Налаштуйте проміжне ПЗ Doconut у конвеєрі запитів так, щоб будь‑який запит, що містить рядок запиту ?token=, оброблявся Doconut. Проміжне ПЗ застосовує маркер безпеки за замовчуванням (secure-{token}), коли UnsafeMode має значення false (за замовчуванням), і повертає зображення сторінок, мініатюри та дані анотацій.

Розміщення проміжного ПЗ у окремій гілці залишає решту вашого конвеєра недоторканою і дозволяє горизонтальне масштабування без «липких» сесій.

---

3. Відкрийте документ і отримайте непрозорий токен сеансу

Створіть єдиний кінцевий пункт, який приймає шлях до файлу (або потік) і повертає токен. Токен – єдина облікова дані, яку бачить клієнтський віджет.

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. Відобразіть документ на боці клієнта

З браузера викликайте кінцеву точку, отримуйте токен і передайте його віджету 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 з серверного кінцевого пункту або з події «unload» віджету.

// Серверний кінцевий пункт
app.MapPost("/api/close", (Viewer viewer, string token) =>
{
    viewer.CloseDocument(token);
    return Results.Ok();
});

// Прямий виклик від віджету (якщо ви відкриваєте токен бекенду)
viewer.CloseDocument(token);

CloseDocument видаляє сеанс з кешу, звільняє базовий движок документа, стирає маркер secure-{token} і анулює доступ. Термін дії за замовчуванням зрештою робив би те саме, але явне закриття гарантує, що пам’ять звільняється миттєво після завершення роботи користувача.

---

6. Додатково: Конвертація документа на сервері

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

---

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

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

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

---

8. Швидкий чек‑лист для готової до продакшн реалізації

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

Дотримуйтесь цього списку, і у вас буде повний, безпечний, високопродуктивний потік управління документами, побудований на нативному .NET переглядачі Doconut.