Plugin Conversor

O plugin Converter 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 do C#, do widget ou de um frontend que você mesmo desenvolva.

Instalar o pacote

Instale o plugin Converter mais recente e estável:

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 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 método AddConverter() — o modelo de plugins do Doconut é uniforme. Cada plugin, incluindo o Converter, registra‑se da mesma forma: chame AddPlugin<TPlugin>() dentro de AddDoconut(). 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>();
});

Esta chamada gera 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 seu vencimento, 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 do C#

Cada conversão retorna um MemoryStream pesquisá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 o `new`.
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 fonte converte para todo destino — o plugin mapeia a família de formatos de cada fonte (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 o arquivo que acabou de ser enviado, e isso é o 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. Habilite-os no lado do 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 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 — não concede direitos de conversão por si só.

Personalizar o widget

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

Retornos de chamada:

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();         // voltar para a tela idle/drop; não dispara onReady novamente
conv.loadFile(file);  // inicia o fluxo com um objeto File; no-op a menos que esteja atualmente idle
conv.destroy();       // remove listeners, esvazia o mount; a instância fica inutilizável após isso

Crie sua própria interface

O widget é apenas um cliente para este contrato HTTP — construa sua própria interface diretamente sobre 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 enviados são armazenados no servidor com um TTL de 30 minutos; quando essa janela 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 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 do recurso

O conversor devolve um MemoryStream buscável posicionado em zero. O chamador possui esse fluxo e deve descartá‑lo após copiar ou devolver 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 a bandeira a partir da mesma regra: a fachada C# DocumentConverter a 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.