Зарегистрировать и включить виджет Doconut Drop‑in Converter в .NET 8

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

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

---

1. Требования – лицензия и поддержка сессий

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

builder.Services.AddDistributedMemoryCache();   // требуется для сеанса
builder.Services.AddSession();                  // включает сеанс, поддерживаемый IDistributedCache

---

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. Подключить middleware в правильном порядке

Middleware, обслуживающий статические ресурсы (UseDoconutResources), должен выполняться до конечного middleware просмотрщика (UseDoconut). Middleware сессий также должен быть размещён раньше, так как 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‑полезность, содержащую 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 на /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 converter будет работать без дополнительных серверных изменений.