Sistema de Plugins

O núcleo do Doconut permanece enxuto; funcionalidades opcionais são entregues como plugins — pacotes NuGet separados que contribuem com visualizadores ou serviços e são ativados pela sua licença. Esta página explica o modelo de registro, o que acontece na inicialização quando uma licença não cobre um plugin e como conectar seu próprio visualizador.

Registrando um plugin

Cada pacote de plugin expõe uma classe de plugin. Registre-a uma única vez, em Application_Start:

Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// Um plugin registrado cuja licença está ausente lança aqui, em Application_Start, e o
// o site então responde a cada requisição com um 500 vazio. O motivo está no log de eventos do Windows.

AddPlugin<TPlugin>() cria o plugin e permite que ele registre suas contribuições com DoconutOptions. Tudo o que um plugin contribui é marcado com a capacidade requerida do plugin, e DoconutHost.Initialize verifica cada plugin registrado contra a licença antes que o site atenda sua primeira solicitação.

Uma licença de plugin ausente interrompe o site

Quando nenhuma licença ativa concede a capacidade de um plugin registrado — nenhuma licença, um arquivo legado TRIAL, ou uma licença paga sem essa capacidade — DoconutHost.Initialize lança InvalidOperationException de Application_Start:

The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

No System.Web, uma exceção em Application_Start não gera uma página de erro. Cada solicitação responde com um 500 vazio, o log do IIS não mostra nada útil, e a mensagem aparece apenas no log de eventos do Windows (log de Aplicação, origem ASP.NET). Quando um site deixa de responder logo após a adição de uma linha AddPlugin, verifique primeiro os arquivos de licença em wwwroot — veja Configuração de Licença.

O contrato

Um plugin implementa uma interface deliberadamente pequena:

public interface IDoconutPlugin
{
    string Name { get; }                          // por exemplo "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // o portão de licença
    void Register(IDoconutPluginBuilder builder); // contribuir visualizadores/serviços
}

Dentro de Register, o construtor aceita dois tipos de contribuição:

• builder.RegisterViewer(".dcm", () => new DicomViewer()) — um visualizador para uma extensão de arquivo,
• builder.RegisterService<TContract>(() => …) — um serviço tipado que outras partes do pipeline podem localizar.

Capacidades e restrição

Capacidades são as unidades de licença. Converter e Dicom são entregues como plugins opcionais; Search e Annotation são recursos incorporados restritos da mesma forma. O visualizador base não é uma capacidade — é o pré-requisito, exposto como IsViewerLicensed no serviço de licença.

A validação na inicialização normalmente impede que um plugin não licenciado entre no pipeline de solicitações. A fábrica de visualizadores também aplica duas regras defensivas, que são relevantes se os direitos mudarem enquanto o site está em execução:

• Um plugin que substitui um visualizador incorporado (ele reivindica uma extensão que um visualizador incorporado também trata): com a capacidade licenciada, o visualizador do plugin prevalece; sem ela, o Doconut recorre ao visualizador incorporado. Os usuários ainda veem seu documento; apenas não obtêm o comportamento do plugin.
• Um formato exclusivo de plugin (.dcm e .ima — DICOM não tem visualizador incorporado): sem a capacidade, a abertura falha:

LicenseException: This document type requires the 'Dicom' plugin license.

Uma licença Temporária ativa concede todas as capacidades. Isso é uma surpresa clássica no go-live: as mesmas linhas AddPlugin que foram executadas durante a avaliação interrompem o site quando a licença comprada omite uma dessas capacidades. Compare IsCapabilityGranted(...) com o que você adquiriu antes de implantar. Com nenhuma licença, nada é concedido — uma licença ausente não é uma licença Temporária.

A mesma restrição chega ao navegador: Viewer.ReferenceScripts() e ReferenceCss() emitem os arquivos para recursos restritos por licença (Pesquisa, Anotação) somente quando a licença os concede, portanto a página nunca oferece um recurso que o servidor recusará.

Mapa de recursos e plugins

Anotação e Pesquisa não utilizam AddPlugin<TPlugin>(). Conversor e DICOM cada um têm uma página em Plugins com sua configuração e uso. Neste pacote, DICOM renderiza páginas, quadros e animações, mas não lê metadados técnicos — veja Plugin DICOM.

Visualizadores personalizados — seu próprio manipulador de formato

Você pode conectar um visualizador ao pipeline sem escrever um pacote de plugin, diretamente em Application_Start:

Doconut.DoconutHost.Initialize(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),                        // implementa IFormatViewer
        () => new ImageConfig { ImageResolution = 150 });  // configuração padrão opcional
});

Visualizadores personalizados têm precedência sobre tudo — incorporados e plugins igualmente — e não são restritos por licença: são seu código. Quando você não fornece uma configuração padrão, a fábrica usa um ImageConfig.

Conclusões

• Os plugins são registrados explicitamente em DoconutHost.Initialize, e suas capacidades são validadas lá; um direito ausente interrompe o site com um 500 vazio, cuja razão está no log de eventos do Windows.
• Plugins no estilo de substituição degradam graciosamente; formatos exclusivos de plugin falham com um LicenseException.
• Uma licença Temporária ativa desbloqueia tudo; a produção desbloqueia o que você comprou. Verifique com IDoconutLicenseService antes de enviar.