Конвертація документів на боці сервера в .NET з Doconut

Вступ

Конвертація документів на боці сервера дозволяє застосунку створювати уніфікований результат без автоматизації Microsoft Office або надсилання вихідного файлу до окремого онлайн‑сервісу конвертації. Це може спростити портали документів, фонова завдання та контрольовані процеси експорту — проте хост‑застосунок залишається власником контролю доступу, сховища, зберігання, моніторингу та доставки результату.

Abstract document formats flowing through a conversion pipeline into one normalized output

Плагін .NET 8 Converter від Doconut надає конвертацію через сервіс DocumentConverter, який впроваджується за допомогою dependency injection. Цей посібник зосереджений на поточній реєстрації та моделі API і уникає прив’язки конвертації до сеансу переглядача.

Встановлення відповідних пакетів

Встановіть базові пакети переглядача та конвертера:

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Converter

Тримайте обидва пакети на одній версії релізу. Коли важливі відтворювані збірки, зафіксуйте версію у файлі проєкту або передайте однакове значення --version обом командам.

Реєстрація плагіна конвертера

Плагіни реєструються всередині зворотного виклику параметрів AddDoconut. Окремого методу реєстрації AddConverter() не існує:

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

Застосунок повинен використовувати ліцензію, яка надає можливість конвертера. Виправте помилки запуску та ліцензування перед прийняттям завдань конвертації; не відкладай їх у фонову чергу, де їх важче діагностувати.

Конвертація файлу з C#

Впровадьте DocumentConverter у кінцеву точку або сервіс, який обробляє запит на конвертацію. Конструктор конвертера є internal, тому код застосунку не повинен створювати його безпосередньо.

app.MapPost("/api/convert", async (
    DocumentConverter converter,
    CancellationToken ct) =>
{
    await using Stream pdf = await converter.ConvertAsync(
        "documents/contract.docx",
        ConversionTarget.Pdf,
        ct: ct);

    using var copy = new MemoryStream();
    await pdf.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "contract.pdf");
});

Повернений потік підтримує переміщення та розташований на початку. Викликаюча сторона володіє ним і повинна звільнити його після копіювання або повернення вмісту.

Конвертація завантаженого потоку

Перевантаження для потоку потребує розширення джерела — включаючи початкову крапку — оскільки конвертер використовує його для визначення формату джерела:

app.MapPost("/api/convert-upload", async (
    IFormFile file,
    DocumentConverter converter,
    CancellationToken ct) =>
{
    var extension = Path.GetExtension(file.FileName);
    await using var source = file.OpenReadStream();
    await using Stream output = await converter.ConvertAsync(
        source,
        extension,
        ConversionTarget.Pdf,
        password: null,
        ct: ct);

    using var copy = new MemoryStream();
    await output.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "converted.pdf");
});

Розглядайте ім'я файлу та розширення як недовірений ввід. Забезпечте обмеження розміру завантажень, перевірте тип джерела, авторизуйте користувача, що робить запит, і уникайте використання поданого імені файлу як шляху зберігання.

Вибір цілей на основі реальних можливостей

Плагін надає перелік ConversionTarget у вигляді enum, проте не кожен формат джерела може генерувати будь-яку ціль. Користувацький інтерфейс має показувати лише ті цілі, які дозволені для завантаженого джерела, а не всі значення enum.

При використанні додаткового віджету конвертера від Doconut, його відкритий відповідь містить allowedTargets. Використовуйте цю відповідь як джерело правди для поточного файлу.

Проектування фонового конвертування як робочого процесу застосунку

Конвертер можна викликати з сервісу застосунку або з черги робіт. Надійне завдання зазвичай включає:

Автентифікований запит, який фіксує джерело та бажану ціль.
Повідомлення черги, що містить ідентифікатор завдання застосунку, а не необроблені облікові дані.
Працівник, який отримує джерело через авторизовану абстракцію сховища.
Обмежена операція конвертації з можливістю скасування.
Стійке сховище вихідних даних з чіткими правилами зберігання.
Оновлення статусу, яке не розкриває внутрішні шляхи або конфіденційні деталі виключень.

Вимірюйте рівень паралельності за допомогою репрезентативних документів перед вибором кількості робітників. Вартість конвертації залежить від формату джерела, складності документа, шрифтів, зображень та цільового формату.

Точність безпекових вимог

Запуск конвертера всередині вашого .NET застосунку означає, що операція конвертації не потребує автоматизації Microsoft Office або окремого онлайн API конвертації. Це не гарантує автоматично конфіденційність, відповідність, видалення чи шифрування для всієї системи.

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

Операційний чек‑лист

Тримайте версії Doconut.NET8 та Doconut.NET8.Converter синхронізованими.
Зареєструйте ConverterPlugin під час конфігурації сервісів.
Отримуйте DocumentConverter через dependency injection.
Включайте початкову крапку у розширеннях джерела потоку.
Звільняйте потоки джерела та результату.
Використовуйте скасування та обмеження розміру файлів на рівні застосунку.
Перевіряйте підтримку відповідності джерело‑ціль, а не припускайте, що кожна пара працює.
Тестуйте точність та використання ресурсів за допомогою репрезентативних файлів.
Тримайте рішення щодо сховища, авторизації, аудиту та зберігання в коді застосунку.

Дивіться офіційний огляд Doconut Converter Plugin та Doconut documentation для актуальної інформації про продукт та інтеграцію.