Sistema de Plugins

Amplía el visor con plugins

El núcleo de Doconut se mantiene ligero; la funcionalidad opcional se entrega como plugins — paquetes NuGet separados que aportan visores o servicios y se activan mediante su licencia. Esta página explica el modelo de registro, lo que ocurre al iniciar cuando una licencia no cubre un plugin, y cómo conectar su propio visor.

Registro de un plugin

Cada paquete de plugin expone una clase de plugin. Regístrela una vez, en Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// Un plugin registrado cuya licencia falta lanza aquí, en Application_Start, y el
// sitio luego responde a cada solicitud con un 500 vacío. La razón está en el registro de eventos de Windows.

AddPlugin<TPlugin>() crea el plugin y le permite registrar sus contribuciones con DoconutOptions. Todo lo que un plugin aporta está etiquetado con la capacidad requerida del plugin, y DoconutHost.Initialize verifica cada plugin registrado contra la licencia antes de que el sitio sirva su primera solicitud.

Una licencia de plugin faltante detiene el sitio

Cuando ninguna licencia activa otorga la capacidad de un plugin registrado — ninguna licencia en absoluto, un archivo legado TRIAL, o una licencia paga sin esa capacidad — DoconutHost.Initialize lanza InvalidOperationException desde Application_Start:

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

En System.Web, una excepción en Application_Start no genera una página de error. Cada solicitud responde con un 500 vacío, el registro de IIS no muestra nada útil, y el mensaje aparece solo en el registro de eventos de Windows (registro de Aplicaciones, origen ASP.NET). Cuando un sitio deja de responder justo después de que se añadió una línea AddPlugin, verifique primero los archivos de licencia en wwwroot — vea Configuración de Licencia.

El contrato

Un plugin implementa una interfaz deliberadamente pequeña:

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // p.ej. "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // la puerta de licencia
    void Register(IDoconutPluginBuilder builder); // contribuir visores/servicios
}

Dentro de Register, el constructor acepta dos tipos de contribución:

  • builder.RegisterViewer(extension, factory) — un visor para una extensión de archivo; la fábrica devuelve un IFormatViewer (el plugin DICOM registra .dcm y .ima de esta manera),
  • builder.RegisterService<TContract>(() => …) — un servicio tipado que otras partes del pipeline pueden buscar.

Capacidades y control de acceso

Las capacidades son las unidades de licencia. Converter, Dicom y Signer se entregan como plugins opcionales; Search y Annotation son funciones integradas controladas de la misma manera. El visor base no es una capacidad — es el requisito previo, expuesto como IsViewerLicensed en el servicio de licencias.

La validación al iniciar normalmente mantiene un plugin sin licencia fuera del pipeline de solicitudes. La fábrica de visores también aplica dos reglas defensivas, que son importantes si los derechos cambian mientras el sitio está en ejecución:

  • Un plugin que sobrescribe un visor integrado (reclama una extensión que también maneja un visor integrado): con la capacidad licenciada, el visor del plugin gana; sin ella, Doconut recurre al visor integrado. Los usuarios siguen viendo su documento; simplemente no obtienen el comportamiento del plugin.
  • Un formato solo de plugin (.dcm y .ima — DICOM no tiene visor integrado): sin la capacidad, la apertura falla:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Una licencia Temporal activa otorga todas las capacidades. Eso es una sorpresa clásica al entrar en producción: las mismas líneas AddPlugin que se ejecutaron durante la evaluación detienen el sitio cuando la licencia comprada omite una de esas capacidades. Compare IsCapabilityGranted(...) con lo que compró antes de desplegar. Con ninguna licencia en absoluto, no se otorga nada — una licencia faltante no es una licencia Temporal.

El mismo control llega al navegador: Viewer.ReferenceScripts() y ReferenceCss() emiten los archivos para funciones controladas por licencia (Búsqueda, Anotación) solo cuando la licencia los otorga, por lo que la página nunca ofrece una función que el servidor rechazará.

Mapa de funciones y plugins

FunciónCómo se habilitaCapacidadContribuye
AnotaciónIntegrado en el visor; incluye los recursos de anotaciónAnnotationAutoría en el navegador, persistencia de sesión, exportaciones incrustadas
BúsquedaIntegrado en visores de formatos buscables; incluye los recursos de búsquedaSearchÍndice de texto nativo, resaltados, navegación de resultados
ConvertidorInstale Doconut.NETFramework.Converter y registre ConverterPluginConverterServicio de conversión C# y un widget web opcional
DICOMInstale Doconut.NETFramework.Dicom y registre DicomPluginDicomVisualización de imágenes médicas para .dcm y .ima
FirmanteInstale Doconut.NETFramework.Signer y registre SignerPluginSignerFirmas visibles y sellos digitales para PDF y Word: servicio de firma C# y un widget web opcional

Anotación y Búsqueda no utilizan AddPlugin<TPlugin>(). Convertidor, DICOM y Firmante cada uno tienen una página bajo Plugins con su configuración y uso. En este paquete, DICOM renderiza páginas, marcos y animaciones, pero no lee metadatos técnicos — vea Plugin DICOM.

Visores personalizados — su propio manejador de formato

Puede conectar un visor al pipeline sin escribir un paquete de plugin, directamente en Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),                        // implementa IFormatViewer
        () => new ImageConfig { ImageResolution = 150 });  // configuración predeterminada opcional
});

// El manejador de formato que crea la fábrica. Reemplaza estos miembros con tu propio renderizado.
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() { }
}

Los visores personalizados tienen precedencia sobre todo — tanto los integrados como los plugins — y no están controlados por licencia: son su código. Cuando no proporciona una configuración predeterminada, la fábrica usa un ImageConfig.

Conclusiones

  • Los plugins se registran explícitamente en DoconutHost.Initialize, y sus capacidades se validan allí; una autorización faltante detiene el sitio con un 500 vacío cuya razón está en el registro de eventos de Windows.
  • Los plugins de estilo sobrescritura se degradan de forma elegante; los formatos solo de plugin fallan con un LicenseException.
  • Una licencia Temporal activa desbloquea todo; la producción desbloquea lo que compró. Verifique con IDoconutLicenseService antes de lanzar.

¿Fue útil esta página?