Conversão de Documentos no Lado do Servidor em .NET com Doconut

Introdução

A conversão de documentos no lado do servidor permite que uma aplicação gere uma saída normalizada sem automatizar o Microsoft Office ou enviar a fonte para um serviço de conversão online separado. Isso pode simplificar portais de documentos, trabalhos em segundo plano e fluxos de exportação controlados—mas a aplicação hospedeira ainda controla controle de acesso, armazenamento, retenção, monitoramento e entrega do resultado.

O Plugin Conversor .NET 8 da Doconut expõe a conversão por meio do serviço DocumentConverter injetado por dependência. Este guia foca no modelo atual de registro e API e evita acoplar a conversão a uma sessão de visualizador.

---

Instale os pacotes correspondentes

Instale os pacotes base do visualizador e do conversor:

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

Mantenha ambos os pacotes na mesma versão de lançamento. Quando builds reproduzíveis são importantes, fixe a versão no arquivo de projeto ou passe o mesmo valor --version para ambos os comandos.

Registre o Plugin Conversor

Os plugins são registrados dentro do callback de opções AddDoconut. Não há um método de registro separado AddConverter():

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

A aplicação deve usar uma licença que conceda a capacidade de Conversor. Resolva erros de inicialização e licenciamento antes de aceitar trabalhos de conversão; não os adie para uma fila em segundo plano onde se tornam mais difíceis de diagnosticar.

Converta um arquivo a partir de C#

Injete DocumentConverter no endpoint ou serviço que possui a solicitação de conversão. O construtor do conversor é interno, portanto o código da aplicação não deve instanciá‑lo diretamente.

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");
});

O stream retornado é buscável e está posicionado no início. O chamador o possui e deve descartá‑lo após copiar ou retornar o conteúdo.

Converta um stream enviado

A sobrecarga de stream requer a extensão da fonte—incluindo o ponto inicial—porque o conversor a usa para resolver o formato da fonte:

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");
});

Trate o nome do arquivo e a extensão como entrada não confiável. Imponha limites de upload, valide o tipo da fonte, autorize o usuário solicitante e evite usar o nome de arquivo enviado como caminho de armazenamento.

Escolha destinos com base nas capacidades reais

O plugin expõe um enum ConversionTarget, mas nem todo formato de origem pode produzir qualquer destino. Uma UI personalizada deve mostrar apenas os destinos permitidos para a origem enviada, em vez de exibir todos os valores do enum.

Ao usar o widget opcional de conversor da Doconut, sua resposta aberta inclui allowedTargets. Use essa resposta como a fonte da verdade para o arquivo atual.

Projete a conversão em segundo plano como um fluxo de trabalho de aplicação

O conversor pode ser chamado a partir de um serviço de aplicação ou de um trabalhador enfileirado. Um job robusto normalmente inclui:

1. Uma solicitação autenticada que registra a origem e o destino desejado.
2. Uma mensagem de fila contendo um ID de job da aplicação, não credenciais brutas.
3. Um trabalhador que recupera a origem por meio de uma abstração de armazenamento autorizada.
4. Uma operação de conversão limitada com cancelamento.
5. Armazenamento de saída durável com regras explícitas de retenção.
6. Uma atualização de status que não expõe caminhos internos ou detalhes sensíveis de exceção.

Meça a concorrência com documentos representativos antes de definir a quantidade de trabalhadores. O custo da conversão varia conforme o formato de origem, complexidade do documento, fontes, imagens e destino de saída.

Mantenha as reivindicações de segurança precisas

Executar o conversor dentro da sua aplicação .NET significa que a operação de conversão não requer automação do Microsoft Office ou uma API de conversão online separada. Isso não garante automaticamente privacidade, conformidade, exclusão ou criptografia para todo o sistema.

Essas propriedades dependem de como a aplicação autentica usuários, recupera arquivos de origem, configura armazenamento, protege logs, distribui a saída e remove dados temporários ou retidos.

Lista de verificação operacional

• Mantenha as versões de Doconut.NET8 e Doconut.NET8.Converter alinhadas.
• Registre ConverterPlugin durante a configuração de serviços.
• Resolva DocumentConverter por injeção de dependência.
• Inclua o ponto inicial nas extensões de origem de streams.
• Descarte os streams de origem e de resultado.
• Use cancelamento e limites de tamanho de arquivo ao nível da aplicação.
• Valide o suporte de origem‑para‑destino em vez de assumir que todo par funciona.
• Teste fidelidade e uso de recursos com arquivos representativos.
• Mantenha decisões de armazenamento, autorização, auditoria e retenção no código da aplicação.

Consulte a visão geral oficial do Visão geral do Plugin Conversor Doconut e a documentação do Doconut para informações atuais sobre o produto e integração.