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

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

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

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

dotnet add package Doconut.NETStandard.Converter

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

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

Поддерживайте пакет Converter в той же версии, что и Doconut.NETStandard. Идентификатор пакета — Doconut.NETStandard.Converter; .26.8.0 присутствует только в имени загруженного файла .nupkg.

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

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

viewer.Converter.GetConverter() здесь не существует. Конвертация больше не доступна через экземпляр просмотрщика: вместо этого внедряйте Doconut.DocumentConverter.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
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) в виде потока, как и любой другой результат конвертации.

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

ConversionTarget (пространство имён Doconut.Configs.Conversion) содержит 45 членов:

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

Этот один enum охватывает все семейства источников. В предыдущей библиотеке был тип *ConfigConverter для каждого семейства — WordConfigConverter, ExcelConfigConverter и т.д. — каждый со своим вложенным enum EnTargetFormat, плюс enum SourceFormatConverter для входных форматов. Всё это исчезло; см. руководство по миграции.

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

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

Конечные точки ?convert=open|run|download виджета являются опциональными и по умолчанию отключены — это обеспечивает безопасность из коробки. Включите их на стороне сервера вместе с регистрацией плагина:

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>

Без вызова AddConverterWidget() три конечные точки ?convert= возвращают 404 — но сам файл JavaScript всё равно отдается (это простой встроенный статический ресурс; защищены только те конечные точки, к которым он обращается). AddConverterWidget() всё равно требует, чтобы плагин Converter был зарегистрирован и была лицензия, предоставляющая Converter — она не предоставляет права на конвертацию сама по себе.

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

Параметры инициализации, передаваемые в Doconut.convert(selector, options):

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

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

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

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

Виджет — это лишь клиент для данного HTTP‑контракта; вы можете построить собственный фронтенд, взаимодействующий с ним напрямую, чтобы обеспечить иной пользовательский опыт. Все три маршрута находятся под веткой ASP.NET, где смонтирован UseDoconut() (обычно /doconut):

Загруженные байты источника сохраняются на сервере со сроком жизни 30 минут; после истечения этого окна запрос run возвращает 404, и файл необходимо открыть заново. Преобразованный результат хранится в том же хранилище — downloadToken получает собственное новое 30‑минутное окно после завершения конвертации, тогда как resultToken является обычным токеном сессии просмотрщика, срок жизни которого следует кэшу сессии просмотрщика, независимо от хранилища.

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

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

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

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

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

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

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

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

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