Registre e habilite o widget drop‑in de conversão Doconut no .NET 8

O widget drop‑in é a interface pronta da Doconut para enviar um arquivo, executar uma conversão e baixar o resultado.
Por padrão, os três endpoints ?convert= do widget retornam 404; eles só ficam ativos quando você registra o plug-in Converter e chama AddConverterWidget() em DoconutOptions.

A seguir, uma configuração completa, pronta para copiar e colar, que atende a ambos os requisitos.

---

1. Pré‑requisitos – licença e suporte a sessão

• Licença – O plug-in Converter requer uma licença que conceda a capacidade Converter. Coloque o arquivo (por exemplo, Doconut.Viewer.lic) em um local acessível pelo aplicativo e aponte DoconutOptions.LicensePath para ele.
• Estado de sessão – O modelo de segurança da Doconut armazena tokens de sessão de documento na sessão do ASP.NET Core. Adicione um cache distribuído e AddSession() antes que o middleware seja configurado.

builder.Services.AddDistributedMemoryCache();   // necessário para a sessão
builder.Services.AddSession();                  // habilita sessão baseada em IDistributedCache‑backed

---

2. Registre os serviços principais da Doconut

AddDoconut() é o ponto de entrada único que injeta o visualizador, o serviço de licença e o registro de plug-ins.

builder.Services.AddDoconut(options =>
{
    // Informe ao Doconut onde encontrar o arquivo de licença.
    options.LicensePath = "Doconut.Viewer.lic";

    // Registre o plugin Converter – isso também valida a capacidade da licença.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Se a licença não incluir a capacidade Converter, a chamada acima lança InvalidOperationException e a aplicação não iniciará. Esse comportamento de falha rápida impede que você implante uma versão com licença incorreta.

---

3. Ative o widget com AddConverterWidget

O widget é opcional. Chamar AddConverterWidget() registra os três endpoints de conversão (?convert=open, ?convert=run, ?convert=download) e configura uma pequena quantidade de ajustes do lado do cliente (tamanho máximo de upload, caminhos base, etc.).

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

    // Habilite a UI drop‑in e defina o limite de upload do lado do cliente.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // pré‑verificação do cliente; o servidor impõe seu próprio limite
    });
});

Somente a chamada AddConverterWidget cria os endpoints; o arquivo JavaScript estático (doconutConverter.js) é sempre servido como recurso incorporado, mas falhará ao contatar o servidor se os endpoints estiverem ausentes.

---

4. Conecte o middleware na ordem correta

O middleware que serve ativos estáticos (UseDoconutResources) deve ser executado antes do middleware de visualizador terminal (UseDoconut). O middleware de sessão também precisa ser colocado antes, pois a Doconut valida a sessão em cada requisição.

app.UseSession();           // deve preceder UseDoconut()
app.UseDoconutResources();  // serve JS, CSS, imagens
app.UseDoconut();           // lida com ?convert= e solicitações de página de documento

Com esse encadeamento configurado, uma requisição para /doconut-res/doconutConverter.js tem sucesso, e o widget pode chamar /doconut?convert=open, /doconut?convert=run e /doconut?convert=download.

---

5. O que o widget realmente faz

Fase	Endpoint do servidor	Resposta típica
Abrir	?convert=open	Retorna um payload JSON contendo um token, contagem de páginas, extensão de origem e a lista de formatos de destino permitidos.
Executar	?convert=run	Inicia a conversão e retorna um downloadToken, contagem de páginas resultantes, nome de arquivo sugerido e uma bandeira indicando se a saída está com marca d'água.
Baixar	?convert=download	Transmite o arquivo convertido quando o cliente segue a URL de download fornecida.

Do lado do cliente, o widget realiza uma verificação de tamanho pré‑upload contra widget.MaxUploadMb. Se o arquivo exceder esse limite, o widget aborta o upload e dispara o callback onError com phase = "open" e uma mensagem amigável. O servidor impõe seu próprio limite e responderá 413 Payload Too Large se a requisição passar pela verificação do cliente.

---

6. Conectando aos eventos do widget (lado C# não é necessário)

Todos os callbacks (onReady, onSourceLoaded, onConverted, onError, etc.) são funções JavaScript fornecidas pela página que hospeda o widget. Como a pergunta foca no lado de registro, você não precisa escrever nenhum código C# adicional para lidar com esses callbacks — o widget os invoca automaticamente assim que os endpoints estiverem ativos.

---

7. Armadilhas comuns e como evitá‑las

Sintoma	Causa provável	Correção
404 em /doconut?convert=open	O AddConverterWidget() foi omitido.	Adicione a chamada conforme mostrado na seção 3.
A aplicação falha ao iniciar com InvalidOperationException sobre capacidade ausente	O arquivo de licença não concede Converter.	Obtenha uma licença que inclua a capacidade Converter.
Erro relacionado à sessão 500	O UseSession() foi colocado após UseDoconut() ou o registro de cache está ausente.	Garanta que app.UseSession() seja executado antes de app.UseDoconut() e que um serviço de cache esteja registrado.

---

8. Execute o aplicativo e veja o widget em ação

1. Compile e execute o projeto ASP.NET Core.
2. Abra uma página que contenha um elemento <div id="doconut-convert"></div> e inclua o script conversor da Doconut (o script é servido automaticamente a partir de /doconut-res/doconutConverter.js).
3. Arraste um arquivo suportado (PDF, DOCX, DWG, etc.) para a área de soltura.
4. O widget chamará ?convert=open, depois ?convert=run, e finalmente apresentará um link de Download que aponta para ?convert=download.

Se os três endpoints responderem com JSON em vez de 404, o widget está corretamente registrado e pronto para uso em produção.

---

Próximo passo: Adicione os trechos de código acima ao seu Program.cs (ou Startup.cs), verifique se o arquivo de licença está presente e inicie o aplicativo. O widget conversor drop‑in estará ativo sem quaisquer outras alterações no lado do servidor.