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 — 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 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 um 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(). 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 gera uma exceção na inicialização por falta de licença, um arquivo legado TRIAL, ou uma licença não temporária que não concede a capacidade Converter — um InvalidOperationException levantado de dentro de AddDoconut(), antes que o aplicativo atenda solicitações. Registros temporários de Demonstração/NFR são aceitos; após sua expiração de calendário, a conversão continua disponível com saída com 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 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 solicitações.

// Injete DocumentConverter; seu construtor é interno, então nunca `new` ele.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension inclui o ponto inicial. password é null a menos que o documento esteja protegido.
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 de 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ê obtém o documento HTML (imagens incorporadas como Base64) como um stream, da mesma forma que todo outro 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 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 o allowedTargets real para qualquer arquivo que acabou de ser enviado, e é isso que deve alimentar o seletor.

Widget incorporável

Os endpoints ?convert=open|run|download do widget são opcionais e desativados por padrão — seguros por padrão. Ative-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= respondem com 404 — mas o próprio arquivo JS ainda é servido de qualquer forma (é um recurso estático simples incorporado; apenas os endpoints com os quais ele se comunica são restritos). AddConverterWidget() ainda requer que o plugin Converter esteja registrado e uma licença que conceda Converter — isso não concede direitos de conversão por si só.

Personalize 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();         // volta para a tela idle/drop; não dispara onReady novamente
conv.loadFile(file);  // inicia o fluxo com um objeto File; não faz nada a menos que esteja ocioso
conv.destroy();       // remove ouvintes, esvazia o mount; a instância torna‑se inutilizável após isso

Construa sua própria interface

O widget é apenas um cliente para este contrato HTTP — construa sua própria interface 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 enviada são armazenados no servidor com um TTL de 30 minutos; quando esse período expira, run responde com 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 da área de armazenamento.

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

Modos de falha, agrupados por rota:

Propriedade de recurso

O conversor retorna um MemoryStream buscável posicionado em zero. O chamador possui esse fluxo e deve descartá‑lo após copiar ou retornar seu conteúdo. O serviço DocumentConverter em si é sem estado e é resolvido por injeção de dependência; não construa nem 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 duração da sessão do visualizador. Fechar um resultado de visualizador não exclui um armazenamento de download ainda válido, e redefinir o widget do navegador não estende nenhum dos TTLs.

Solução de problemas

Marca d'água

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

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