Серверное преобразование документов в .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.Viewer.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 для актуальной информации о продукте и интеграции.