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, como o controle de licença se comporta em tempo de execução e como conectar seu próprio visualizador.

Registrando um plugin

Cada pacote de plugin expõe uma classe de plugin. Você a registra uma única vez, na inicialização:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddPlugin<TPlugin>() instancia o plugin e invoca seu callback Register contra o registro de plugins mantido em DoconutOptions. Tudo o que um plugin contribui é marcado com a capability requerida do plugin. AddDoconut() valida os plugins registrados imediatamente: uma licença ausente, arquivo legado TRIAL ou licença paga sem a capability faz a inicialização falhar com InvalidOperationException. Um registro Temporary/Demo é mantido após a expiração, mas suas capabilities em tempo de execução são revogadas após a data de expiração.

O contrato

Um plugin implementa uma interface deliberadamente pequena:

public interface IDoconutPlugin
{
    string Name { get; }                          // e.g. "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // the license gate
    void Register(IDoconutPluginBuilder builder); // contribute viewers/services
}

Dentro de Register, o builder aceita dois tipos de contribuições:

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

Capabilities e controle

Capabilities são as unidades de licença. Converter e Dicom são entregues como plugins opcionais; Search e Annotation são recursos incorporados controlados da mesma forma. O visualizador base não é uma capability — ele é 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 requisições. A fábrica de visualizadores também aplica duas regras defensivas em tempo de execução, que são relevantes se a elegibilidade mudar após a inicialização:

• Plugin substitui um visualizador incorporado (um plugin reivindica uma extensão que o registro incorporado também trata): com a capability licenciada, o visualizador do plugin prevalece; sem ela, Doconut recua silenciosamente para o visualizador incorporado. Os usuários ainda veem seu documento — apenas não obtêm o recurso do plugin.
• Formato exclusivo de plugin (ex.: .dcm — DICOM não possui visualizador incorporado): sem a capability a chamada de abertura falha de forma crítica:

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

Uma licença Temporary ativa concede todas as capabilities (com visualização base limpa, sem marca d'água). Esta é uma fonte clássica de surpresas na implantação: registrar os mesmos plugins com uma licença comprada que omite uma de suas capabilities faz AddDoconut() falhar durante a inicialização. Compare IsCapabilityGranted(...) com seu plano antes de implantar. O lado oposto: com nenhuma licença, nada é concedido — uma licença ausente não é uma licença Temporary.

O mesmo controle aparece no lado do cliente: Viewer.ReferenceScripts() e ReferenceCss() emitem os pacotes de script/estilo para os recursos controlados por licença (search, annotation, …) apenas quando a licença os habilita, de modo que a UI do widget permanece consistente com o que o servidor realmente fará.

Mapa de recursos e plugins

A UI do produto usa “plugin” como um rótulo amplo de recurso, mas o registro no servidor difere:

Annotation e Search normais não utilizam AddPlugin<TPlugin>(); seus pacotes são emitidos apenas quando a licença concede a capability correspondente. Converter e DICOM são as implementações IDoconutPlugin opt-in lançadas para este conjunto de documentação.

Os artefatos .NET 6 aprovados contêm Doconut.NET6.Converter e Doconut.NET6.Dicom na mesma versão que o pacote principal.

Pacotes de plugins lançados

Cada um tem uma página dedicada em Plugins com sua configuração e uso.

Visualizadores personalizados — seu próprio manipulador de formato

Você pode conectar um visualizador ao pipeline sem escrever um pacote de plugin, diretamente de Program.cs:

builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // implements IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // optional default config
});

Visualizadores personalizados têm precedência sobre tudo — incorporados e plugins igualmente — e não são controlados por licença (são seu código). A fábrica recorre a um ImageConfig quando você não fornece uma configuração padrão.

Conclusões

• Plugins são registrados explicitamente e sua LicenseCapability é validada durante AddDoconut() — falta ou insuficiência de direito não temporário falha rapidamente.
• Plugins de estilo sobrescrito degradam graciosamente; formatos exclusivos de plugin falham com um LicenseException.
• Uma licença Temporary ativa desbloqueia tudo; a licença de produção desbloqueia o que você comprou. Verifique com IDoconutLicenseService antes de distribuir.