DoconutOptions

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 singleton.

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

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

Propriedades

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

Métodos

AddPlugin<TPlugin>()

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

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

Registra um plugin de primeira‑parte (Converter, DICOM). Fluent — 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 ficam sujeitos ao gate de tempo de execução (veja Conceitos Principais → Sistema de Plugins).

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

RegisterViewer(extension, factory, defaultConfig?)

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 limitados por licença. Quando defaultConfig é omitido e um documento abre sem configuração explícita, um ImageConfig é usado.

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

Validação na inicialização

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

As mensagens de erro lançadas durante a validação são:

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

// 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 (ex.: para evitar conflito de rotas)
builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});

Ao alterar 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 do ASP.NET Core. Se o 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 a mesma URL. A aplicação de referência, por sua vez, mantém a forma histórica de requisição DocImage.axd em um ramo MapWhen com BasePath: '/'.