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 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 tenuto su DoconutOptions. Tutto ciò che un plugin contribuisce è etichettato con la capability richiesta del plugin. AddDoconut() convalida 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; }                          // 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(".dcm", () => new DicomViewer()) — un visualizzatore per un'estensione di file,
• builder.RegisterService<TContract>(() => …) — un servizio tipizzato che altre parti della pipeline possono cercare.

Capacità e gating

Le capability 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 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 vince; 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 esempio .dcm — DICOM non ha un visualizzatore integrato): senza la capability la chiamata di apertura fallisce in modo definitivo:

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. L'altro lato: 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 script/style per le funzionalità soggette a 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

Il prodotto UI usa “plugin” come etichetta di funzionalità ampia, ma la registrazione del server differisce:

Annotazione e Ricerca normale non utilizzano AddPlugin<TPlugin>(); i loro bundle vengono emessi solo quando la licenza concede la capacità corrispondente. Convertitore e DICOM sono implementazioni opt‑in IDoconutPlugin.

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 nella 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 di 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.