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 release. La precedente libreria .NET Standard non aveva un 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 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 mantenuto su 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 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; }                          // ad 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(extension, factory) — un visualizzatore per un'estensione di file; la factory restituisce un IFormatViewer (il plugin DICOM registra .dcm e .ima in questo modo),
• 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 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 richiede un'estensione che anche il registro integrato gestisce): con la capability concessa, il visualizzatore del plugin prevale; senza di essa, Doconut ritorna 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 classica fonte 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:

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 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 }); // configurazione predefinita opzionale
});

I visualizzatori personalizzati hanno la 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 è convalidato 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 distribuire.