DoconutExtensions

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.

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 fail‑fast (veja DoconutOptions → validação de inicialização) e registra o grafo completo de serviços:

ServiceLifetimeRole
DoconutOptionsSingletonO objeto de configuração
IViewerFactorySingletonMapeia extensões para visualizadores de formato
IDocumentSessionManagerSingletonToken → cache de sessão (IMemoryCache também está registrado)
IDoconutLicenseServiceSingletonLicença carregada uma vez na inicialização (precedência: LicenseStream → LicenseContent → LicensePath → pesquisa automática)
PageImageServiceSingletonPipeline de imagem de página (marca d'água/rotação/escala/anotações)
Document security (access store)SingletonConcessões para vinculação token‑para‑sessão
ViewerTransientA fachada pública de abrir/fechar
DocumentConverterTransientFachada de conversão — requer o plugin Converter
DistributedDocumentPublisher—Publica os artefatos de um documento no armazenamento compartilhado
Health check "doconut"—Reporta o estado da 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; ambas são substituídas por este único registro.

Dois comportamentos importantes:

  • O conversor requer seu plugin. Resolver DocumentConverter sem 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. Uma licença ausente, arquivo legado TRIAL ou licença paga sem a capacidade de plugin registrada falham no momento da chamada AddDoconut(). Registros temporários/Demo permanecem válidos após a data de expiração, enquanto os controles 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:

csharp
app.MapHealthChecks("/health");

UseDoconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Adiciona o middleware de imagem de página Doconut. Ele responde a toda requisição que contenha 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 Core Concepts → How the Viewer Works). Quando UnsafeMode é false, a camada de segurança do documento é conectada automaticamente antes dele.

Não recebe argumentos. Passar uma instância de DoconutOptions aqui era o formato da biblioteca anterior e não compila mais.

O exemplo de referência encaminha as requisições do widget através de um ramo de caminho, mantendo o formato histórico da requisição:

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() 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 ordem.

Esta é a substituição suportada para conectar manualmente o middleware de recurso incorporado com app.UseMiddleware<EmbeddedResourceMiddleware>().

Servindo a partir de armazenamento compartilhado

Existem duas outras registrações 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 Distributed Deployments; as assinaturas são:

text
IServiceCollection AddDoconutDistributedAsyncPublish(...)   // fila de publicação em segundo plano opcional
IServiceCollection AddDoconutDistributedWidgets(...)        // armazenamento compartilhado para uploads de widgets

O lado de leitura é um middleware separado do pacote Doconut.Clouds:

text
IApplicationBuilder UseDoconutCloud<THandler>(
    this IApplicationBuilder app,
    Action<CloudOptions>? configure = null,
    string pathPrefix = "/doconut-cloud")
    where THandler : BaseCloudHandler

UseDoconutWebFarm(...) e WebFarmOptions não existem nesta versão. Consulte o migration guide para o mapeamento configuração por configuração.

Recapitulação da ordem

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

Esta página foi útil?