Sistema di Plugin
Estendi il visualizzatore con i 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 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 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() 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; } // 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 unIFormatViewer(il plugin DICOM registra.dcme.imain questo modo),builder.RegisterService<TContract>(() => …)— un servizio tipizzato che altre parti della pipeline possono cercare.
Capability e gating
Le capability sono le unità della licenza. Converter, Dicom e Signer 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 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 plugin vince; 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 (
.dcme.ima— 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 usa “plugin” come etichetta di funzionalità ampia, ma la registrazione sul server differisce:
| Funzionalità | Come viene abilitata | Capability | Contribuisce |
|---|---|---|---|
| Annotazione | Integrata nel visualizzatore; includi risorse di annotazione | Annotation | Autorizzazione nel browser, persistenza della sessione e esportazioni incorporate |
| Ricerca | Integrata nei visualizzatori di formati ricercabili; includi risorse di ricerca e abilita l'estrazione dove necessario | Search | Indice di testo nativo, evidenziazioni e navigazione dei risultati |
| Convertitore | Installa Doconut.NET8.Converter e registra ConverterPlugin | Converter | Servizio di conversione C# e widget web opzionale |
| DICOM | Installa Doconut.NET8.Dicom e registra DicomPlugin | Dicom | Visualizzazione di immagini mediche per .dcm e .ima |
| Firmatario | Installa Doconut.NET8.Signer e registra SignerPlugin | Signer | Firme visibili e sigilli digitali per PDF e Word: servizio di firma C# e widget web opzionale |
Annotazione e Ricerca normale non usano AddPlugin<TPlugin>(); i loro bundle vengono emessi solo quando la licenza concede la capability corrispondente. Convertitore, DICOM e Firmatario sono implementazioni IDoconutPlugin opzionali.
Pacchetti plugin rilasciati
| Plugin | Pacchetto | Capability | Contribuisce |
|---|---|---|---|
| Convertitore | Doconut.NET8.Converter | Converter | Capability di conversione dei documenti |
| DICOM | Doconut.NET8.Dicom | Dicom | Visualizzazione di immagini mediche (.dcm e .ima — formati solo plugin) |
| Firmatario | Doconut.NET8.Signer | Signer | Firma di PDF e Word |
Ciascuno ha una pagina dedicata sotto Plugin con la sua configurazione e utilizzo.
Visualizzatori personalizzati — il tuo gestore di formati
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
});
// Il gestore di formato che la fabbrica crea. Sostituisci questi membri con il tuo rendering.
public sealed class MyCustomViewer : Doconut.Core.Interfaces.IFormatViewer
{
public ViewerType ViewerType => ViewerType.None;
public int TotalPages => 0;
public int DefaultWidth => 0;
public int DefaultHeight => 0;
public bool PreferOcr => false;
public Task LoadAsync(Stream documentStream, BaseConfig config, CancellationToken ct = default)
=> Task.CompletedTask;
public Task<byte[]> GetPageImageAsync(int pageNumber, CancellationToken ct = default)
=> Task.FromResult(Array.Empty<byte>());
public void Dispose() { }
}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 duranteAddDoconut()— un diritto mancante o insufficiente non temporaneo fallisce rapidamente. - I plugin di tipo 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
IDoconutLicenseServiceprima di distribuire.
Questa pagina è stata utile?