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

Вступ

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

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

---

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

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

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

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

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

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

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

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

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

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

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, проте не кожен формат джерела може створювати будь-яку ціль. Користувацький інтерфейс повинен показувати лише ті цілі, які дозволені для завантаженого джерела, а не всі значення переліку.

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

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

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

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

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

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

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

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

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

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

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