Sistema di Plugin

Il core di Doconut rimane snello; le funzionalità opzionali vengono fornite come plugin — pacchetti NuGet separati che contribuiscono con visualizzatori o servizi e vengono attivati dalla tua licenza. Questa pagina spiega il modello di registrazione, come il gating della licenza si comporta a runtime e come collegare il tuo visualizzatore.

Registrazione di un plugin

Ogni pacchetto plugin espone una classe plugin. La registri una volta, all'avvio:

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

AddPlugin<TPlugin>() istanzia il plugin e invoca la sua callback Register sul registro dei plugin mantenuto in DoconutOptions. Tutto ciò che un plugin contribuisce è etichettato con la capacità richiesta del plugin. AddDoconut() valida immediatamente i plugin registrati: una licenza mancante, un file legacy TRIAL o una licenza a pagamento senza la capacità provoca il fallimento dell'avvio con InvalidOperationException. Una registrazione Temporanea/Demo viene mantenuta oltre la scadenza, ma le sue capacità a runtime vengono revocate dopo la data di scadenza.

Il contratto

Un plugin implementa un'interfaccia deliberatamente piccola:

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

All'interno di Register, il builder accetta due tipi di contributi:

• builder.RegisterViewer(".dcm", () => new DicomViewer()) — un visualizzatore per un'estensione di file,
• builder.RegisterService<TContract>(() => …) — un servizio tipizzato che altre parti della pipeline possono recuperare.

Capacità e gating

Le capacità sono le unità di licenza. Converter e Dicom vengono forniti come plugin opzionali; Search e Annotation sono funzionalità integrate con lo stesso gating. Il visualizzatore di base non è una capacità — è il prerequisito, esposto come IsViewerLicensed nel servizio di licenza.

La validazione all'avvio normalmente impedisce a un plugin non licenziato di entrare nella pipeline di richiesta. La factory del visualizzatore applica anche due regole difensive a runtime, che sono importanti se i diritti cambiano dopo l'avvio:

• Il plugin sovrascrive un visualizzatore integrato (un plugin richiede un'estensione gestita anche dal registro integrato): con la capacità concessa, il visualizzatore del plugin prevale; senza di essa, Doconut torna silenziosamente al visualizzatore integrato. Gli utenti vedono comunque il loro documento — semplicemente non ottengono la funzionalità del plugin.
• Formato solo plugin (ad es. .dcm — DICOM non ha un visualizzatore integrato): senza la capacità la chiamata di apertura fallisce in modo definitivo:

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

Una licenza Temporanea attiva concede tutte le capacità (con visualizzazione di base pulita, senza filigrana). Questa è una fonte classica di sorprese al go-live: registrare gli stessi plugin con una licenza acquistata che omette una delle loro capacità fa fallire AddDoconut() durante l'avvio. Confronta IsCapabilityGranted(...) con il tuo piano prima del deployment. D'altro canto: con nessuna licenza, nulla è concesso — una licenza mancante non è una licenza Temporanea.

Lo stesso gating appare lato client: Viewer.ReferenceScripts() e ReferenceCss() emettono i bundle di script/style per le funzionalità soggette a licenza (search, annotation, …) solo quando la licenza le abilita, così l'interfaccia del widget rimane coerente con ciò che il server farà realmente.

Mappa delle funzionalità e dei plugin

L'interfaccia del prodotto usa “plugin” come etichetta generica di funzionalità, ma la registrazione sul server differisce:

Pacchetti plugin rilasciati

Ciascuno ha una pagina dedicata sotto Plugin con la sua configurazione e utilizzo.

Visualizzatori personalizzati — il tuo gestore di formato

Puoi collegare un visualizzatore alla pipeline senza scrivere un pacchetto plugin, direttamente da Program.cs:

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

I visualizzatori personalizzati hanno la precedenza su tutto — sia gli integrati che i plugin — e non sono soggetti a gating di licenza (sono il tuo codice). La factory ricade su un ImageConfig quando non fornisci una configurazione predefinita.

Punti chiave

• I plugin sono registrati esplicitamente e la loro LicenseCapability viene validata durante AddDoconut() — diritti mancanti o insufficienti non temporanei falliscono rapidamente.
• I plugin di tipo override degradano in modo elegante; i formati solo plugin falliscono con una LicenseException.
• Una licenza Temporanea attiva sblocca tutto; la licenza di produzione sblocca ciò che hai acquistato. Verifica con IDoconutLicenseService prima di distribuire.