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.

Questo modello è nuovo in questa versione. La precedente libreria .NET Standard non aveva alcun registro dei plugin: la conversione viveva nel visualizzatore stesso e le licenze dei plugin venivano installate tramite chiamate statiche Viewer.SetLicensePlugin(...). Nessuno dei due è un meccanismo di registrazione qui.

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 contro il registro dei plugin tenuto su DoconutOptions. Tutto ciò che un plugin contribuisce è etichettato con la capability richiesta del plugin. AddDoconut() valida i plugin registrati immediatamente: una licenza mancante, un file legacy TRIAL, o una licenza a pagamento senza la capability provoca il fallimento dell'avvio con InvalidOperationException. Una registrazione Temporanea/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; }                          // es. "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // il cancello della licenza
    void Register(IDoconutPluginBuilder builder); // contribuisci visualizzatori/servizi
}

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

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 sul 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 che anche il registro integrato gestisce): con la capability concessa, il visualizzatore del plugin prevale; senza di essa, Doconut torna silenziosamente al visualizzatore integrato. Gli utenti vedono ancora 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 Temporanea 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 Temporanea.

Lo stesso controllo appare lato client: Viewer.ReferenceScripts() e ReferenceCss() emettono i bundle script/style per le funzionalità controllate dalla licenza (ricerca, annotazione, …) 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 utilizza "plugin" come etichetta di funzionalità ampia, ma la registrazione sul server differisce:

Annotazione e Ricerca normale non usano AddPlugin<TPlugin>(); i loro bundle vengono emessi solo quando la licenza concede la capability corrispondente. Convertitore e DICOM sono le implementazioni opt-in IDoconutPlugin rilasciate per questo set di documentazione.

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

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(),               // implementa IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // opzionale default config
});

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

Conclusioni

• I plugin sono registrati esplicitamente e il loro LicenseCapability è validato durante AddDoconut() — un diritto mancante o insufficiente non temporaneo fallisce rapidamente.
• I plugin in stile override degradano elegantemente; i formati solo plugin falliscono con un LicenseException.
• Una licenza Temporanea attiva sblocca tutto; la produzione sblocca ciò che hai acquistato. Verifica con IDoconutLicenseService prima di rilasciare.