Sistema de Plugins
Estenda o visualizador com plugins
O núcleo do Doconut permanece enxuto; funcionalidades opcionais são entregues como plugins — pacotes NuGet separados que fornecem 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 integrar seu próprio visualizador.
Registrando um plugin
Cada pacote de plugin expõe uma classe de plugin. Registre-a uma 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
// 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(extension, factory)— um visualizador para uma extensão de arquivo; a fábrica retorna umIFormatViewer(o plugin DICOM registra.dcme.imadesta forma),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, Dicom e Signer 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 importantes se os direitos mudarem enquanto o site está em execução:
- Um plugin que substitui um visualizador incorporado (ele reivindica uma extensão que também é tratada por um visualizador incorporado): com a capacidade licenciada, o visualizador do plugin prevalece; sem ela, 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 (
.dcme.ima— DICOM não possui 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 ao entrar em produção: as mesmas linhas AddPlugin que foram executadas durante a avaliação interrompem o site quando a licença adquirida omite uma dessas capacidades. Compare IsCapabilityGranted(...) com o que você comprou 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 (Busca, Anotação) somente quando a licença os concede, de modo que a página nunca oferece um recurso que o servidor recusará.
Mapa de recursos e plugins
| Recurso | Como é habilitado | Capacidade | Contribui |
|---|---|---|---|
| Anotação | Integrado ao visualizador; inclui os recursos de anotação | Annotation | Criação no navegador, persistência de sessão, exportações incorporadas |
| Busca | Integrado aos visualizadores de formatos pesquisáveis; inclui os recursos de busca | Search | Índice de texto nativo, realces, navegação de resultados |
| Conversor | Instale Doconut.NETFramework.Converter e registre ConverterPlugin | Converter | Serviço de conversão C# e um widget web opcional |
| DICOM | Instale Doconut.NETFramework.Dicom e registre DicomPlugin | Dicom | Visualização de imagens médicas para .dcm e .ima |
| Assinador | Instale Doconut.NETFramework.Signer e registre SignerPlugin | Signer | Assinaturas visíveis e selos digitais para PDF e Word: serviço de assinatura C# e um widget web opcional |
Anotação e Busca não utilizam AddPlugin<TPlugin>(). Conversor, DICOM e Assinador cada um tem 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 integrar um visualizador ao pipeline sem escrever um pacote de plugin, diretamente em Application_Start:
Doconut.DoconutHost.Initialize(options =>
{
options.RegisterViewer(
".myext",
() => new MyCustomViewer(), // implements IFormatViewer
() => new ImageConfig { ImageResolution = 150 }); // configuração padrão opcional
});
// O manipulador de formato que a fábrica cria. Substitua esses membros pela sua própria renderização.
public sealed class MyCustomViewer : Doconut.Core.Interfaces.IFormatViewer
{
public ViewerType ViewerType => ViewerType.None;
public int TotalPages => 0;
public int DefaultWidth => 0;
public int DefaultHeight => 0;
public bool PreferOcr => false;
public Task LoadAsync(Stream documentStream, BaseConfig config, CancellationToken ct = default)
=> Task.CompletedTask;
public Task<byte[]> GetPageImageAsync(int pageNumber, CancellationToken ct = default)
=> Task.FromResult(Array.Empty<byte>());
public void Dispose() { }
}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
- Plugins são registrados explicitamente em
DoconutHost.Initialize, e suas capacidades são validadas lá; um direito ausente interrompe o site com um500vazio, cuja razão está no log de eventos do Windows. - Plugins do tipo 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
IDoconutLicenseServiceantes de publicar.
Esta página foi útil?