Sistema di Plugin

Il nucleo 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 integrare il tuo visualizzatore.

Registrazione di un plugin

Ogni pacchetto plugin espone una classe plugin. La registri una sola 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 il suo callback Register sul registro dei plugin contenuto in DoconutOptions. Tutto ciò che un plugin contribuisce è etichettato con la capability richiesta del plugin. AddDoconut() convalida immediatamente i plugin registrati: una licenza mancante, un file legacy TRIAL o una licenza a pagamento senza la capability provoca il fallimento dell'avvio con InvalidOperationException. Una registrazione Temporary/Demo viene mantenuta oltre la scadenza, ma le sue capability 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.

Capability e gating

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

La convalida 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 dichiara un'estensione gestita anche dal registro integrato): con la capability concessa, il visualizzatore del plugin prevale; senza di essa, Doconut ritorna 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 capability la chiamata di apertura fallisce in modo critico:

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

Una licenza Temporary attiva concede tutte le capability (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 capability fa fallire AddDoconut() durante l'avvio. Confronta IsCapabilityGranted(...) con il tuo piano prima di distribuire. D'altro canto: con nessuna licenza, nulla è concesso — una licenza mancante non è una licenza Temporary.

Lo stesso controllo appare lato client: Viewer.ReferenceScripts() e ReferenceCss() generano i bundle di script/stile per le funzionalità controllate dalla licenza (search, annotation, …) solo quando la licenza le abilita, così l'interfaccia del widget rimane coerente con ciò che il server farà effettivamente.

Mappa delle funzionalità e dei plugin

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

Annotation e Search normale non utilizzano AddPlugin<TPlugin>(); i loro bundle vengono emessi solo quando la licenza concede la capability corrispondente. Converter e DICOM sono le implementazioni IDoconutPlugin opzionali rilasciate per questo set di documentazione.

Gli artefatti .NET 6 approvati contengono Doconut.NET6.Converter e Doconut.NET6.Dicom alla stessa versione del pacchetto core.

Pacchetti plugin rilasciati

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

Visualizzatori personalizzati — il tuo gestore di formato

Puoi inserire un visualizzatore nella 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 integrati che 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 vengono registrati esplicitamente e la loro LicenseCapability viene convalidata durante AddDoconut() — un diritto mancante o insufficiente non temporaneo fallisce rapidamente.
• I plugin di tipo override degradano in modo elegante; i formati solo plugin falliscono con una LicenseException.
• Una licenza Temporary attiva sblocca tutto; la produzione sblocca ciò che hai acquistato. Verifica con IDoconutLicenseService prima di distribuire.