Серверное преобразование документов в .NET с Doconut

Введение

Преобразование документов на стороне сервера позволяет приложению генерировать нормализованный вывод без автоматизации Microsoft Office или отправки исходного файла в отдельный онлайн‑сервис преобразования. Это может упростить документальные порталы, фоновые задачи и контролируемые рабочие процессы экспорта, но хост‑приложение по‑прежнему отвечает за контроль доступа, хранение, удержание, мониторинг и доставку результата.

Плагин .NET 8 Converter от Doconut предоставляет возможность преобразования через внедряемый сервис 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 Converter и Документацию Doconut для актуальной информации о продукте и интеграции.