Плагин Конвертера

Плагин Converter превращает Doconut в сервис конвертации документов. Он предоставляет движок, стоящий за публичным фасадом DocumentConverter, и — при желании — готовый к использованию виджет со своим HTTP‑контрактом, так что вы можете конвертировать документы из C#, из виджета или из собственного фронтенда.

Установить пакет

Установите последнюю стабильную версию плагина Converter:

dotnet add package Doconut.NET8.Converter

Чтобы зафиксировать плагин на текущем выпуске 26.7.0, передайте версию отдельно:

dotnet add package Doconut.NET8.Converter --version 26.7.0

Держите пакет Converter той же версии, что и Doconut.NET8. Идентификатор пакета — Doconut.NET8.Converter; .26.7.0 появляется только в имени скачанного файла .nupkg.

Зарегистрировать плагин

Метода AddConverter() не существует — модель плагинов Doconut единообразна. Каждый плагин, включая Converter, регистрируется одинаково: вызовите AddPlugin<TPlugin>() внутри AddDoconut(). ConverterPlugin поставляется в собственном пакете NuGet, Doconut.NET8.Converter, установленном рядом с базовым пакетом просмотрщика.

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

Этот вызов бросает исключение при запуске из‑за отсутствующей лицензии, устаревшего файла TRIAL или непостоянной лицензии, не предоставляющей возможности Converter — InvalidOperationException, возникшее внутри AddDoconut(), до того как приложение начнёт обслуживать запросы. Принимаются временные регистрации Demo/NFR; после их календарного истечения конвертация остаётся доступной с водяным знаком на выводе. Тихого бесплатного уровня нет. См. Настройка лицензии для информации о загрузке лицензий.

Конвертировать из C#

Каждая конверсия возвращает перемещаемый MemoryStream, позиционированный на 0, готовый к чтению или копированию сразу. Получите DocumentConverter из DI там, где он нужен — он без состояния по дизайну, поэтому один экземпляр безопасно переиспользовать между запросами.

// Внедрите DocumentConverter; его конструктор internal, поэтому никогда не `new` его.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension включает ведущую точку. password равен null, если только документ не защищён.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Две детали, которые легко перепутать: sourceExtension в перегрузке потока должен включать ведущую точку (".xlsx", а не "xlsx") — конвертер сопоставляет её с каталогом форматов, и простое расширение не будет найдено. И несмотря на название, WordToHtmlAsync возвращает Task<Stream>, а не Task<string> — вы получаете HTML‑документ (изображения встроены как Base64) в виде потока, как и любой другой результат конверсии.

Целевые форматы

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Не каждый источник конвертируется в каждый целевой формат — плагин сопоставляет семейство форматов источника (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, web document) со своим фиксированным набором разрешённых целей. Не жёстко кодируйте этот enum в списке целей вашего UI: ?convert=open возвращает фактический allowedTargets для любого только что загруженного файла, и именно это должно управлять выбором.

Встраиваемый виджет

The widget's ?convert=open|run|download endpoints are opt-in and disabled out of the box — secure by default. Enable them server-side, alongside the plugin registration:

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

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Without AddConverterWidget(), the three ?convert= endpoints answer 404 — but the JS file itself is still served regardless (it's a plain embedded static resource; only the endpoints it talks to are gated). AddConverterWidget() still requires the Converter plugin to be registered and a license that grants Converter — it doesn't grant conversion rights on its own.

Настройка виджета

Init options passed to Doconut.convert(selector, options):

Обратные вызовы:

Doconut.convert() возвращает сам экземпляр виджета — держите его, чтобы управлять виджетом программно:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // возврат к экрану простоя/отбрасывания; не вызывает повторно onReady
conv.loadFile(file);  // запускает поток с объектом File; без действия, если сейчас не в простое
conv.destroy();       // удаляет слушатели, очищает mount; после этого экземпляр непригоден к использованию

Создайте собственный фронтенд

The widget is just a client for this HTTP contract — build your own frontend against it directly for a different UX. All three routes sit under the ASP.NET branch where UseDoconut() is mounted (normally /doconut):

Uploaded source bytes are stashed server-side with a 30-minute TTL; once that window lapses, run answers 404 and the file must be re-opened. The converted result lives in the same stash — downloadToken gets its own fresh 30-minute window when the conversion completes — while resultToken is an ordinary viewer session token whose lifetime follows the viewer's session cache, independent of the stash.

sourceExt в ответе open не имеет ведущей точки (например, "docx") — противоположная конвенция параметру sourceExtension в DocumentConverter.ConvertAsync, который требует её.

Сценарии отказов, сгруппированные по маршруту:

Владение ресурсом

Конвертер возвращает позиционируемый в ноль MemoryStream. Вызывающая сторона владеет этим потоком и должна освободить его после копирования или возврата его содержимого. Сервис DocumentConverter сам по себе без состояния и получается через внедрение зависимостей; не создавайте и не освобождайте сервис вручную.

Для веб‑виджета загрузочные и скачиваемые хранилища имеют независимые TTL в 30 минут. resultToken просмотрщика следует времени жизни сессии просмотрщика. Закрытие результата просмотрщика не удаляет ещё действительное хранилище загрузки, и сброс виджета браузера не продлевает ни один из TTL.

Устранение неполадок

Водяные знаки

При зарегистрированном ConverterPlugin лицензия хоста находится в одном из трёх состояний:

Оба пути вызова вычисляют флаг по одному и тому же правилу: фасад DocumentConverter на C# выводит его внутренне из состояния лицензии IsViewerLicensed и IsTemporary, а обработчик ?convert=run виджета выполняет эквивалентную проверку (IsViewerLicensed && !IsTrial && !IsTemporary), чтобы заполнить поле watermarked, которое он возвращает. Интеграцию можно построить и протестировать сквозным образом на оценочной лицензии до покупки — меняются только байты вывода.