ExtensõesDoconut
Registro de serviços e middleware
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 registrações de middleware.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // chame UseSession() antes de UseDoconut()
app.UseDoconutResources(); // deve ser registrado antes de UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() responde a cada requisição que o alcança, portanto monte‑o em seu próprio ramo com app.Map.
AddDoconut
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)Constrói o DoconutOptions, valida‑os de forma fail‑fast (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 |
| Serviço de cache de sessão | Singleton | Token → cache de sessão (IMemoryCache também está registrado) |
IDoconutLicenseService | Singleton | Licença carregada uma vez na inicialização (precedência: LicenseStream → LicenseContent → LicensePath → busca automática) |
| Pipeline de página‑imagem | Singleton | Executa processamento de imagens para páginas (marca d'água, rotação, escala, anotações) |
| Segurança de documento (armazenamento de acesso) | Singleton | Concessões para vinculação token‑sessão |
Viewer | Transitório | A fachada pública de abrir/fechar |
DocumentConverter | Transitório | Fachada de conversão — requer o plugin Converter |
DocumentSigner | Transitório | Fachada de assinatura — requer o plugin Signer (veja Plugin Signer) |
DistributedDocumentPublisher | Transitório | Publica os artefatos de um documento no armazenamento compartilhado |
Verificação de saúde "doconut" | — | Relata o estado de licença/expiração através das verificações de saúde do ASP.NET |
Não há chamada equivalente na biblioteca .NET Standard anterior. Ela construía new Viewer(cache, accessor) por requisição e passava opções para o middleware; ambos são substituídos por este único registro.
Dois comportamentos importantes de se conhecer:
- Converter requer seu plugin. Resolver
DocumentConvertersemoptions.AddPlugin<ConverterPlugin>()lança:
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentSigner segue a mesma regra: sem options.AddPlugin<SignerPlugin>() lança No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
- A elegibilidade do plugin é validada na inicialização. Uma licença ausente, arquivo legado
TRIAL, ou licença paga sem a capacidade de plugin registrada falha no momentoAddDoconut(). Registros temporários/Demo sobrevivem à sua data de expiração, enquanto os portões de tempo de execução revogam as capacidades expiradas.
A verificação de saúde 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:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)Adiciona o middleware de página‑imagem Doconut. Ele atende a toda 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) — e responde a qualquer outra requisição com 404 (ou o banner ShowDoconutInfo): nunca encaminha a requisição para o restante do pipeline. Monte‑o em seu próprio ramo, como nos exemplos desta página. Quando UnsafeMode está false, a camada de segurança de documento é conectada automaticamente antes dele.
Não aceita argumentos. Passar uma instância DoconutOptions aqui era o formato da biblioteca anterior e não compila mais.
Uma configuração comum mantém o formato histórico de requisição DocImage.axd com um ramo MapWhen (o cliente então usa BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
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() emitem 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.
Esta é a substituição suportada para conectar manualmente o middleware de tratamento de recursos incorporados.
Servindo a partir de armazenamento compartilhado
Existem duas registrações adicionais para implantações onde o nó que renderiza um documento não é necessariamente o nó que serve suas páginas. Ambas são cobertas de ponta a ponta em Implantações Distribuídas; as assinaturas são:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // fila de publicação em segundo plano com opt-in
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // armazenamento de apoio compartilhado para uploads de widgetO lado de leitura é um middleware separado da assembly Doconut.Clouds, que é entregue no mesmo pacote:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerUseDoconutWebFarm(...) e WebFarmOptions não existem nesta versão. Consulte o guia de migração para o mapeamento configuração por configuração.
Recapitulação da ordem
app.UseRouting();
app.UseSession(); // chame UseSession() antes de UseDoconut()
app.UseDoconutResources(); // deve ser registrado antes de UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // ou um ramo MapWhenEsta página foi útil?