DoconutExtensions – Doconut Documentação

DoconutExtensions (namespace Doconut.Middleware) é a classe estática com as três chamadas que todo host Doconut faz: um registro de serviço e duas registragens de middleware.

csharp

builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseDoconutResources(); // BEFORE UseDoconut()
app.UseDoconut();

AddDoconut

text

IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)

Constrói o DoconutOptions, valida‑os de forma imediata (veja DoconutOptions → Validação de inicialização) e registra o grafo completo de serviços:

Serviço	Tempo de vida	Função
`DoconutOptions`	Singleton	O objeto de configuração
`IViewerFactory`	Singleton	Mapeia extensões para visualizadores de formato
`IDocumentSessionManager`	Singleton	Token → cache de sessão (`IMemoryCache` também é registrado)
`IDoconutLicenseService`	Singleton	Licença carregada uma vez na inicialização (precedência: `LicenseStream` → `LicenseContent` → `LicensePath` → busca automática)
`PageImageService`	Singleton	Pipeline de imagem de página (marca d'água/rotação/escala/anotações)
Segurança de documento (armazenamento de acesso)	Singleton	Concessões para associação token‑sessão
`Viewer`	Transient	A fachada pública de abertura/fechamento
`DocumentConverter`	Transient	Fachada de conversão — requer o plugin Converter
Verificação de integridade `"doconut"`	—	Relata o estado da licença/expiração através das verificações de integridade do ASP.NET

Dois comportamentos importantes

O Converter requer seu plugin. Tentar resolver DocumentConverter sem ter chamado options.AddPlugin<ConverterPlugin>() gera a exceção:

text

InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

A elegibilidade do plugin é validada na inicialização. Falta de licença, arquivo legado TRIAL ou licença paga sem a capacidade de um plugin registrado faz a chamada AddDoconut() falhar. Registros temporários/demonstração permanecem válidos após a data de expiração, enquanto as restrições em tempo de execução revogam as capacidades expiradas.

A verificação de integridade integra‑se ao mecanismo padrão do ASP.NET Core — mapeie‑a se quiser o estado da licença no seu endpoint de saúde:

csharp

app.MapHealthChecks("/health");

UseDoconut

text

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Adiciona o middleware de imagem de página Doconut. Ele responde a cada requisição que contém o parâmetro de consulta ?token= — páginas, miniaturas, busca, anotações, ações de página (a tabela completa de requisições está em Conceitos Principais → Como o Visualizador Funciona). Quando UnsafeMode é false, a camada de segurança de documento é conectada automaticamente antes dele.

O exemplo de referência encaminha as requisições do widget através de um ramo de caminho:

csharp

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconutResources

text

IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

Serve os JS, CSS, imagens e fontes incorporados em DoconutOptions.ResourcesPath (padrão /doconut-res). Estes são os arquivos para os quais Viewer.ReferenceCss() / ReferenceScripts() geram tags.

Sempre chame antes de UseDoconut(). Se a área do visualizador permanecer vazia e o console do navegador mostrar 404s para /doconut-res/..., esta chamada está ausente ou fora de lugar.

Ordering recap

csharp

app.UseRouting();
app.UseSession();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1st Doconut call
app.UseDoconut();          // 2nd Doconut call (or via a MapWhen branch)