Plugin Conversor

O plugin Converter transforma o Doconut em um serviço de conversão de documentos. Ele fornece o motor por trás da fachada pública DocumentConverter e — opcionalmente — um widget pronto para uso com seu próprio contrato HTTP, permitindo que você converta documentos a partir de C#, do widget ou de um frontend que você mesmo desenvolva.

Instalar o pacote

Instale a versão estável mais recente do plugin Converter:

dotnet add package Doconut.NET6.Converter

Para fixar o plugin na versão atual 26.7.0, passe a versão separadamente:

dotnet add package Doconut.NET6.Converter --version 26.7.0

Mantenha o pacote Converter na mesma versão que o Doconut.NET6. O ID do pacote é Doconut.NET6.Converter; .26.7.0 aparece apenas no nome do arquivo .nupkg baixado.

Registrar o plugin

Não existe o método AddConverter() — o modelo de plugins do Doconut é uniforme. Todo plugin, inclusive o Converter, registra‑se da mesma forma: chame AddPlugin<TPlugin>() dentro de AddDoconut(). O ConverterPlugin é distribuído em seu próprio pacote NuGet, Doconut.NET6.Converter, instalado ao lado do pacote base do visualizador.

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

Essa chamada lança uma exceção na inicialização se a licença estiver ausente, se houver um arquivo legado TRIAL ou se a licença não‑temporária não conceder a capacidade Converter — uma InvalidOperationException gerada dentro de AddDoconut(), antes que o aplicativo atenda solicitações. Registros temporários de demonstração/NFR são aceitos; após seu vencimento, a conversão continua disponível com saída marcada por marca d'água. Não há nível gratuito silencioso. Consulte License Setup para saber como as licenças são carregadas.

Converter a partir de C#

Cada conversão devolve um MemoryStream buscável posicionado em 0, pronto para leitura ou cópia imediata. Resolva DocumentConverter a partir do DI onde precisar — ele é sem estado por design, portanto uma única instância pode ser reutilizada com segurança entre requisições.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Dois detalhes fáceis de errar: sourceExtension na sobrecarga que aceita stream deve incluir o ponto inicial (".xlsx", não "xlsx" ) — o conversor o compara com o catálogo de formatos e uma extensão sem ponto não será resolvida. E, apesar do nome, WordToHtmlAsync devolve Task<Stream>, não Task<string> — você recebe o documento HTML (imagens embutidas como Base64) como stream, assim como todo resultado de conversão.

Formatos de destino

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Nem todo formato de origem converte para todo destino — o plugin mapeia a família de formato de cada origem (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, documento web) para seu próprio conjunto fixo de destinos permitidos. Não codifique esse enum como a lista de destinos da sua UI: ?convert=open devolve os allowedTargets reais para o arquivo que acabou de ser enviado, e é isso que deve alimentar um seletor.

Widget pronto para uso

Os endpoints ?convert=open|run|download do widget são opcionais e vêm desativados por padrão — seguros por padrão. Habilite‑os no servidor, junto ao registro do plugin:

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

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Sem AddConverterWidget(), os três endpoints ?convert= respondem 404 — mas o arquivo JS ainda é servido (é um recurso estático embutido; apenas os endpoints que ele chama são restritos). AddConverterWidget() ainda requer que o plugin Converter esteja registrado e que a licença conceda Converter — ele não concede direitos de conversão por conta própria.

Personalizar o widget

Opções de inicialização passadas para Doconut.convert(selector, options):

Callbacks:

Doconut.convert() devolve a própria instância do widget — mantenha‑a para controlar o widget programaticamente:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // volta à tela ociosa/de arraste; não dispara onReady novamente
conv.loadFile(file);  // inicia o fluxo com um objeto File; não faz nada se não estiver ocioso
conv.destroy();       // remove listeners, esvazia a montagem; a instância fica inutilizável após isso

Construir seu próprio frontend

O widget é apenas um cliente para este contrato HTTP — construa seu próprio frontend contra ele diretamente para uma UX diferente. Todas as três rotas ficam sob o ramo ASP.NET onde UseDoconut() está montado (normalmente /doconut):

Os bytes da fonte enviados são armazenados no servidor com TTL de 30 minutos; ao expirar esse período, run responde 404 e o arquivo deve ser reaberto. O resultado convertido permanece na mesma stash — downloadToken recebe sua própria janela fresca de 30 minutos quando a conversão termina — enquanto resultToken é um token de sessão de visualizador comum cujo tempo de vida segue o cache da sessão do visualizador, independente da stash.

sourceExt na resposta de open não tem ponto inicial (ex.: "docx") — a convenção oposta ao parâmetro sourceExtension de DocumentConverter.ConvertAsync, que requer o ponto.

Modos de falha, agrupados por rota:

Propriedade dos recursos

O conversor devolve um MemoryStream buscável posicionado em zero. O chamador possui esse stream e deve descartá‑lo após copiar ou devolver seu conteúdo. O serviço DocumentConverter em si é sem estado e é resolvido via injeção de dependência; não construa nem descarte o serviço manualmente.

Para o widget web, as stashes de upload e download têm TTLs independentes de 30 minutos. Um resultToken de visualizador segue a vida da sessão do visualizador. Fechar um resultado de visualizador não exclui uma stash de download ainda válida, e redefinir o widget no navegador não estende nenhum dos TTLs.

Solução de problemas

Marcação d'água

Com ConverterPlugin registrado, a licença do host está em um dos três estados:

Ambos os caminhos de chamada calculam a bandeira a partir da mesma regra: a fachada C# DocumentConverter a deriva internamente do estado IsViewerLicensed e IsTemporary da licença, e o manipulador ?convert=run do widget faz a verificação equivalente (IsViewerLicensed && !IsTrial && !IsTemporary) para preencher o campo watermarked que devolve. Uma integração pode ser construída e testada de ponta a ponta com uma licença de avaliação antes da compra — apenas os bytes de saída mudam.