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

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

Встановити пакет

Встановіть останню стабільну версію плагіна Конвертер:

dotnet add package Doconut.NETStandard.Converter

Щоб зафіксувати плагін на поточному випуску 26.8.0, передайте версію окремо:

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

Тримайте пакет Конвертер на тій же версії, що і Doconut.NETStandard. Ідентифікатор пакету — Doconut.NETStandard.Converter; .26.8.0 з’являється лише у назві завантаженого файлу .nupkg.

Зареєструвати плагін

Методу AddConverter() не існує — модель плагінів Doconut уніфікована. Кожен плагін, включаючи Конвертер, реєструється однаково: викличте 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 замість цього.

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

// sourceExtension включає початкову крапку. password є null, якщо документ не захищений.
Stream png = await converter.ConvertAsync(stream, ".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

Цей перелік охоплює всі сімейства джерел. Попередня бібліотека мала тип *ConfigConverter для кожного сімейства — WordConfigConverter, ExcelConfigConverter тощо — кожен зі своїм вкладеним переліченням EnTargetFormat, плюс перелічення SourceFormatConverter для вхідних даних. Усі вони видалені; дивіться посібник з міграції.

Не кожне джерело конвертується у кожну ціль — плагін зіставляє сімейство форматів джерела (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, веб‑документ) зі своїм фіксованим набором дозволених цілей. Не жорстко кодуйте цей перелік як список цілей у вашому 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 — проте сам файл JS все одно подається (це простий вбудований статичний ресурс; лише точки доступу, до яких він звертається, захищені). AddConverterWidget() все ще вимагає реєстрації плагіна Converter та ліцензії, яка надає Converter — вона не надає прав на конвертацію самостійно.

Налаштування віджета

Початкові параметри, передані до Doconut.convert(selector, options):

Зворотні виклики:

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

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // повернутись до екрану idle/drop; не викликає знову onReady
conv.loadFile(file);  // запускає потік з File об’єктом; no-op, якщо не перебуває у стані idle
conv.destroy();       // видаляє слухачі, очищає mount; екземпляр після цього не придатний до використання

Створіть власний інтерфейс

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

Завантажені байти джерела зберігаються на боці сервера з TTL 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, яке він повертає. Інтеграцію можна створити та протестувати повністю на оцінювальній ліцензії перед покупкою — змінюються лише байти вихідних даних.