DoconutOptions

Configure os serviços Doconut

DoconutOptions (namespace Doconut) é o único objeto de configuração para todo o SDK. Você o configura uma vez, dentro de AddDoconut(), e ele é registrado como um singleton.

Esta é uma mudança de localização tanto quanto de forma. Na biblioteca .NET Standard anterior, uma instância DoconutOptions era construída no momento do pipeline e passada para UseDoconut(new DoconutOptions { … }). Aqui o middleware não recebe opções — tudo é definido durante o registro do serviço.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Propriedades

TipoPropriedadePadrãoDescrição
boolShowDoconutInfofalseQuando true, uma solicitação de middleware sem token retorna um banner de versão (Doconut <version> is running on <host>) em vez de 404. Útil como verificação rápida; deixe false em produção.
boolUnsafeModefalseQuando true, ignora a verificação de segurança da sessão ASP.NET nas solicitações de página. Deixe false em produção em um único nó (veja Conceitos Básicos → Sessões & Segurança). Anteriormente escrito UnSafeMode.
stringMiddlewarePath"/doconut"Valor de coordenação para o endpoint page-image. É validado, mas não monta um ramo de pipeline; mantenha alinhado com o mapeamento real UseDoconut() e o cliente BasePath.
stringResourcesPath"/doconut-res"Prefixo de caminho URL para os recursos incorporados de JS/CSS/imagem/fonte.
stringLicensePath""Caminho para o arquivo de licença. Vazio → próxima fonte de licença, então descoberta automática; nada encontrado → estado de avaliação com marca d'água e sem capacidades.
stringLicenseContent""Conteúdo bruto de licença XML (banco de dados, variável de ambiente, gerenciador de segredos). Tem precedência sobre LicensePath.
Stream?LicenseStreamnullLicença como fluxo, lida uma vez na inicialização. Tem precedência sobre ambas as outras fontes.
boolResetLicensefalseFlag de compatibilidade reservada. A implementação atual não a consome; reinicie a aplicação após substituir uma licença.
DoconutPluginRegistryPluginRegistry—Registro somente leitura que coleta contribuições de plugins; consumido pela fábrica de visualizadores. Preencha via AddPlugin<T>().

Precedência de licença (aplicada no registro do serviço): LicenseStream → LicenseContent → LicensePath → descoberta automática (veja Introdução → Configuração de Licença).

Métodos

AddPlugin<TPlugin>()

text
DoconutOptions AddPlugin<TPlugin>() where TPlugin : IDoconutPlugin, new()

Use este método para os pacotes Converter, DICOM e Signer lançados como opt-in. Anotação e Busca normal são recursos licenciados incorporados e não utilizam AddPlugin<TPlugin>().

Registra um plugin de primeira parte (Converter, DICOM, Signer). Fluente — retorna a instância de opções. AddDoconut() lança InvalidOperationException para licença ausente, arquivo legado TRIAL, ou licença paga que não concede a capacidade do plugin. Registros Temporários/Demo são mantidos após a expiração e tornam‑se sujeitos ao gate de tempo de execução (veja Conceitos Básicos → Sistema de Plugins).

O widget Converter opt-in é habilitado com AddConverterWidget() e exposto através da propriedade somente‑leitura ConverterWidget; suas opções estão documentadas na página do Plugin Converter (Plugins → Plugin Converter). O widget Signer opt‑in é habilitado da mesma forma, com AddSignerWidget(), e exposto através da propriedade somente‑leitura SignerWidget; veja Plugin Signer.

RegisterViewer(extensão, fábrica, configPadrão?)

text
DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — ponto inicial opcional
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

Registra um visualizador personalizado para uma extensão de arquivo. Visualizadores personalizados têm precedência sobre visualizadores incorporados e de plugins e não são restritos por licença. Quando defaultConfig é omitido e um documento abre sem uma configuração explícita, um ImageConfig é usado.

Lança ArgumentException (Extension must be a non-empty file extension.) para uma extensão vazia e ArgumentNullException para uma fábrica nula.

Validação na inicialização

AddDoconut() valida as opções falha rápida, de modo que uma má configuração aparece como uma exceção clara na inicialização em vez de 404s confusos no tempo de requisição:

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

Configurações comuns

csharp
// Produção: licença explícita, tudo bloqueado (todos os padrões de segurança)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Caminhos personalizados (por exemplo, para evitar um conflito de rota)
builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});

Quando você altera ResourcesPath, mantenha o ResPath do widget cliente sincronizado (veja ViewerConfig). Esta é uma das duas configurações do lado do cliente que falham sem mensagem de erro.

MiddlewarePath não é um mapeador automático de rotas ASP.NET Core. Se Doconut deve responder apenas abaixo de um prefixo personalizado, monte UseDoconut() naquele ramo (por exemplo com app.Map("/docs-engine", branch => branch.UseDoconut())) e defina o BasePath do cliente para esse prefixo sem o / inicial ('docs-engine'). Uma alternativa comum mantém o formato histórico de solicitação DocImage.axd em um ramo MapWhen com BasePath: '/'.

Esta página foi útil?