DoconutOptions – Documentação Doconut

DoconutOptions (namespace Doconut) é o único objeto de configuração para todo o SDK. Você o configura uma vez, no callback que passa para DoconutHost.Initialize em Application_Start.

csharp

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Propriedades

Tipo	Propriedade	Padrão	Descrição
`bool`	`UnsafeMode`	`false`	Quando `false`, `DocImage.axd` serve uma página apenas para a sessão ASP.NET que abriu o documento (ou, em um farm, para o navegador com um ticket assinado). Quando `true`, qualquer requisição que contenha o token é atendida. Deixe como `false` — veja Sessões e Segurança.
`bool`	`ShowDoconutInfo`	`false`	Quando `true`, uma requisição `DocImage.axd` sem token responde `Doconut <version> is running on <host>` em vez de `404`. Útil como verificação rápida; deixe `false` em produção.
`string`	`ResourcesPath`	`"/doconut-res"`	Prefixo de URL sob o qual o módulo de recursos serve os scripts, estilos e imagens incorporados.
`string`	`LicensePath`	`""`	Caminho completo para o arquivo de licença. Vazio → a próxima fonte de licença, então descoberta automática; nada encontrado → avaliação com marca d'água sem funcionalidades.
`string`	`LicenseContent`	`""`	Conteúdo bruto da licença (banco de dados, variável de ambiente, armazenamento secreto). Tem precedência sobre `LicensePath`.
`Stream?`	`LicenseStream`	`null`	Licença como um stream, lida uma vez na inicialização. Tem precedência sobre ambas as outras fontes.
`string`	`MiddlewarePath`	`"/doconut"`	Não usado pelo System.Web. O endpoint da página é sempre o manipulador `DocImage.axd` declarado em `Web.config`. O valor ainda é validado na inicialização (veja abaixo).
`bool`	`ResetLicense`	`false`	Não usado. A licença é lida uma vez, em `DoconutHost.Initialize`; recicle o pool de aplicações após substituir uma licença.
`DoconutPluginRegistry`	`PluginRegistry`	—	Registro somente leitura das contribuições de plugins, preenchido por `AddPlugin<T>()`.

Precedência da licença: LicenseStream → LicenseContent → LicensePath → descoberta automática (veja Configuração de Licença).

Métodos

AddPlugin<TPlugin>()

text

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

Registra um plugin (Conversor, DICOM). Fluente — retorna a instância de opções. Anotação e Busca são recursos licenciados incorporados e não o utilizam.

Se nenhuma licença ativa conceder a capacidade do plugin, DoconutHost.Initialize lança InvalidOperationException a partir de Application_Start, e o site responde a todas as requisições com um 500 vazio até que isso seja corrigido; a mensagem está no log de eventos do Windows (veja Sistema de Plugins).

Add…Widget()

text

DoconutOptions AddConverterWidget(Action<ConverterWidgetOptions>? configure = null)

Os widgets prontos para uso estão desativados por padrão. Cada chamada Add…Widget() habilita os endpoints desse widget em DocImage.axd e requer que o plugin correspondente esteja registrado. O módulo de recursos serve o script do widget independentemente de você tê-lo habilitado, portanto um widget que carrega e renderiza mas responde 404 na primeira ação está faltando essa chamada. O widget Conversor está documentado em Plugin Conversor.

RegisterViewer(extension, factory, defaultConfig?)

text

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — leading dot optional
    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 controlados 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 de Inicialização

DoconutHost.Initialize valida as opções antes de construir qualquer coisa:

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.

MiddlewarePath é verificado mesmo que o System.Web nunca o use, portanto deixe-o no padrão. Como toda exceção lançada a partir de Application_Start, uma falha de validação aparece como um 500 vazio em todas as requisições, com a mensagem no log de eventos do Windows.

Configurações Comuns

csharp

// Production: explicit license, everything else at its secure default.
public static void ProductionLicense() =>
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
    });

// Custom resource path (e.g. to avoid a route conflict). Keep the viewer's ResPath and any MVC
// IgnoreRoute in step with it: "/docs-assets" means ResPath: 'docs-assets/images'.
public static void CustomResourcePath() =>
    Doconut.DoconutHost.Initialize(options =>
    {
        options.ResourcesPath = "/docs-assets";
    });

Quando você altera ResourcesPath, altere três coisas juntas: a opção, o ResPath do widget ('docs-assets/images' para "/docs-assets"), e, no MVC, o IgnoreRoute para o caminho de recurso (routes.IgnoreRoute("docs-assets/{*pathInfo}")). O endpoint DocImage.axd não se move: seu caminho é definido pelo atributo path do manipulador em Web.config.