Зареєструйте та увімкніть віджет конвертера Doconut drop‑in у .NET 8

Віджет drop‑in — це готовий інтерфейс Doconut для завантаження файлу, запуску конвертації та завантаження результату.
За замовчуванням три кінцеві точки віджету ?convert= повертають 404; вони стануть активними лише після реєстрації плагіна Converter і виклику AddConverterWidget() на DoconutOptions.

Нижче наведено повну конфігурацію запуску, готову до копіювання, яка задовольняє обидві вимоги.

---

1. Передумови – ліцензія та підтримка сесій

• Ліцензія – Плагін Converter потребує ліцензії, яка надає можливість Converter. Розмістіть файл (наприклад, Doconut.Viewer.lic) у доступному для програми місці та вкажіть на нього DoconutOptions.LicensePath.
• Стан сесії – Модель безпеки Doconut зберігає токени документ‑сесії в сесії ASP.NET Core. Додайте розподілений кеш і AddSession() перед підключенням проміжного програмного забезпечення.

builder.Services.AddDistributedMemoryCache();   // необхідно для сеансу
builder.Services.AddSession();                  // вмикає IDistributedCache‑backed сеанс

---

2. Зареєструйте основні служби Doconut

AddDoconut() — це єдина точка входу, яка впроваджує переглядач, службу ліцензій та реєстр плагінів.

builder.Services.AddDoconut(options =>
{
    // Повідомте Doconut, де знайти файл ліцензії.
    options.LicensePath = "Doconut.Viewer.lic";

    // Зареєструйте плагін Converter – це також перевіряє ліцензійну можливість.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Якщо ліцензія не включає можливість Converter, виклик вище генерує помилку InvalidOperationException і застосунок не запуститься. Така поведінка «fail‑fast» запобігає розгортанню неправильно ліцензованої збірки.

---

3. Увімкніть віджет за допомогою AddConverterWidget

Віджет є опційним. Виклик AddConverterWidget() реєструє три кінцеві точки конвертації (?convert=open, ?convert=run, ?convert=download) та підключає невелику кількість клієнтської конфігурації (максимальний розмір завантаження, базові шляхи тощо).

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();

    // Увімкніть UI drop‑in і встановіть обмеження завантаження на боці клієнта.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // перевірка клієнта; сервер застосовує власне обмеження
    });
});

Лише виклик AddConverterWidget створює кінцеві точки; статичний файл JavaScript (doconutConverter.js) завжди подається як вбудований ресурс, проте він не зможе зв’язатися з сервером, якщо кінцеві точки відсутні.

---

4. Підключіть проміжне ПЗ у правильному порядку

Проміжне ПЗ, що обслуговує статичні ресурси (UseDoconutResources), має виконуватись перед кінцевим переглядачем (UseDoconut). Проміжне ПЗ сесії також повинно бути розташоване раніше, оскільки Doconut перевіряє сесію в кожному запиті.

app.UseSession();           // повинно передувати UseDoconut()
app.UseDoconutResources();  // обслуговує JS, CSS, зображення
app.UseDoconut();           // обробляє запити ?convert= та запити сторінок документу

З такою конвеєрною лінією запит до /doconut-res/doconutConverter.js успішний, і віджет може викликати /doconut?convert=open, /doconut?convert=run та /doconut?convert=download.

---

5. Що фактично робить віджет

Етап	Кінцева точка сервера	Типова відповідь
Відкриття	?convert=open	Повертає JSON‑payload, що містить token, кількість сторінок, розширення джерела та список дозволених форматів призначення.
Запуск	?convert=run	Запускає конвертацію та повертає downloadToken, кількість сторінок результату, запропоновану назву файлу та прапорець, що вказує, чи має вихідний файл водяний знак.
Завантаження	?convert=download	Транслює конвертований файл, коли клієнт переходить за наданим URL‑адресою завантаження.

На клієнтській стороні віджет виконує перевірку розміру перед завантаженням проти widget.MaxUploadMb. Якщо файл перевищує цей ліміт, віджет перериває завантаження та викликає зворотний виклик onError з phase = "open" та дружнім повідомленням. Сервер застосовує власний ліміт і відповість 413 Payload Too Large, якщо запит пройде повз клієнтську перевірку.

---

6. Підключення до подій віджету (C#‑сторона не потрібна)

Усі зворотні виклики (onReady, onSourceLoaded, onConverted, onError тощо) — це JavaScript‑функції, які надає сторінка, що розміщує віджет. Оскільки питання стосується реєстрації, вам не потрібно писати додатковий код C# для обробки цих зворотних викликів — віджет викликає їх автоматично, коли кінцеві точки активні.

---

7. Поширені підводні камені та як їх уникнути

Симптом	Ймовірна причина	Виправлення
404 on /doconut?convert=open	AddConverterWidget() було пропущено.	Додайте виклик, як показано у розділі 3.
Застосунок не запускається з InvalidOperationException про відсутню можливість	Файл ліцензії не надає Converter.	Отримайте ліцензію, яка включає можливість Converter.
Помилка 500, пов’язана з сесією	UseSession() розташовано після UseDoconut() або відсутня реєстрація кешу.	Переконайтеся, що app.UseSession() виконується перед app.UseDoconut() і що сервіс кешу зареєстровано.

---

8. Запустіть застосунок і подивіться на віджет у дії

1. Зберіть та запустіть проєкт ASP.NET Core.
2. Відкрийте сторінку, що містить елемент <div id="doconut-convert"></div> і включає скрипт конвертера Doconut (скрипт подається автоматично з /doconut-res/doconutConverter.js).
3. Перетягніть підтримуваний файл (PDF, DOCX, DWG тощо) у область перетягування.
4. Віджет викличе ?convert=open, потім ?convert=run і, нарешті, покаже посилання Download, яке вказує на ?convert=download.

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

---

Наступний крок: Додайте наведені вище фрагменти коду у ваш Program.cs (або Startup.cs), переконайтеся, що файл ліцензії присутній, і запустіть застосунок. Віджет конвертера drop‑in буде активний без будь‑яких подальших змін на боці сервера.