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:

csharp
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:

csharp
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à 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 (.dcm e .ima — DICOM non ha un visualizzatore integrato): senza la capability la chiamata di apertura fallisce in modo critico:
text
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 abilitataCapabilityContribuisce
AnnotazioneIntegrata nel visualizzatore; includi risorse di annotazioneAnnotationAutorizzazione nel browser, persistenza della sessione e esportazioni incorporate
RicercaIntegrata nei visualizzatori di formati ricercabili; includi risorse di ricerca e abilita l'estrazione dove necessarioSearchIndice di testo nativo, evidenziazioni e navigazione dei risultati
ConvertitoreInstalla Doconut.NET8.Converter e registra ConverterPluginConverterServizio di conversione C# e widget web opzionale
DICOMInstalla Doconut.NET8.Dicom e registra DicomPluginDicomVisualizzazione di immagini mediche per .dcm e .ima
FirmatarioInstalla Doconut.NET8.Signer e registra SignerPluginSignerFirme 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

PluginPacchettoCapabilityContribuisce
ConvertitoreDoconut.NET8.ConverterConverterCapability di conversione dei documenti
DICOMDoconut.NET8.DicomDicomVisualizzazione di immagini mediche (.dcm e .ima — formati solo plugin)
FirmatarioDoconut.NET8.SignerSignerFirma 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:

csharp
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 durante AddDoconut() — 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 IDoconutLicenseService prima di distribuire.

Questa pagina è stata utile?