Plugin Conversor

O plugin Conversor transforma o Doconut em um serviço de conversão de documentos. Ele fornece o mecanismo por trás da fachada pública DocumentConverter e — mediante opt‑in — 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 o plugin Conversor mais recente e estável:

dotnet add package Doconut.NET8.Converter

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

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

Mantenha o pacote Conversor na mesma versão que Doconut.NET8. O ID do pacote é Doconut.NET8.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. Cada plugin, incluindo o Conversor, registra‑se da mesma forma: chame AddPlugin<TPlugin>() dentro de AddDoconut(). O ConverterPlugin é distribuído em seu próprio pacote NuGet, Doconut.NET8.Converter, instalado ao lado do pacote base do visualizador.

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

Esta chamada lança uma exceção na inicialização quando falta uma licença, há um arquivo legado TRIAL, ou uma licença não temporária que não concede a capacidade Converter — uma InvalidOperationException gerada dentro de AddDoconut(), antes que o aplicativo atenda às 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 marca‑d’água. Não há nível gratuito silencioso. Veja Configuração de Licença para saber como as licenças são carregadas.

Converter a partir de C#

Cada conversão retorna um MemoryStream pesquisável posicionado em 0, pronto para leitura ou cópia imediata. Resolva DocumentConverter a partir da injeção de dependência 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 que são 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 retorna Task<Stream>, não Task<string> — você recebe o documento HTML (imagens incorporadas como Base64) como um stream, assim como todo o resto dos resultados 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 toda origem converte para todo destino — o plugin mapeia cada família de formato de origem (Word, Excel, PowerPoint, PDF, CAD, Imagem, Email, Diagrama, Projeto/Tarefa, 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 retorna os allowedTargets reais para o arquivo que acabou de ser enviado, e isso é o que deve alimentar o seletor.

Widget pronto para uso

Os endpoints ?convert=open|run|download do widget são opt‑in e ficam desativados por padrão — seguros por padrão. Habilite‑os no servidor, juntamente com o 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= retornam 404 — mas o arquivo JS ainda é servido de qualquer forma (é um recurso estático embutido simples; apenas os endpoints com os quais ele se comunica são restritos). AddConverterWidget() ainda requer que o plugin Conversor esteja registrado e que exista uma licença que conceda Converter — ele não concede direitos de conversão por si só.

Personalizar o widget

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

Callbacks:

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

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // back to the idle/drop screen; does not re-fire onReady
conv.loadFile(file);  // starts the flow with a File object; no-op unless currently idle
conv.destroy();       // removes listeners, empties the mount; the instance is unusable after this

Construir seu próprio frontend

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

Os bytes da fonte carregada são armazenados no servidor com um TTL de 30 minutos; quando esse período expira, run responde 404 e o arquivo deve ser reaberto. O resultado convertido permanece na mesma área de armazenamento — downloadToken obtém 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 de sessão do visualizador, independente do armazenamento.

sourceExt na resposta open não tem ponto inicial (ex.: "docx") — o oposto da convenção do parâmetro sourceExtension em DocumentConverter.ConvertAsync, que requer o ponto.

Modos de falha, agrupados por rota

Propriedade de recursos

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

Para o widget web, os armazenamentos 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 um armazenamento de download ainda válido, e redefinir o widget no navegador não estende nenhum dos TTLs.

Solução de Problemas

Marcação d’água

Com o 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 retorna. 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.