Sistema di Plugin

Estendi il visualizzatore con i 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, cosa succede all'avvio quando una licenza non copre un plugin e come collegare il tuo visualizzatore.

Registrazione di un plugin

Ogni pacchetto plugin espone una classe plugin. Registrala una sola volta, in Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// Un plugin registrato la cui licenza è mancante genera un'eccezione qui, in Application_Start, e il
// il sito risponde quindi a ogni richiesta con un 500 vuoto. Il motivo è nel registro eventi di Windows.

AddPlugin<TPlugin>() crea il plugin e gli consente di registrare i suoi contributi con DoconutOptions. Tutto ciò che un plugin contribuisce è etichettato con la capacità richiesta del plugin, e DoconutHost.Initialize verifica ogni plugin registrato rispetto alla licenza prima che il sito serva la sua prima richiesta.

Una licenza mancante per il plugin interrompe il sito

Quando nessuna licenza attiva concede la capacità di un plugin registrato — nessuna licenza, un file legacy TRIAL, o una licenza a pagamento senza quella capacità — DoconutHost.Initialize lancia InvalidOperationException da Application_Start:

text
The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

In System.Web, un'eccezione in Application_Start non produce una pagina di errore. Ogni richiesta risponde con un 500 vuoto, il log di IIS non mostra nulla di utile, e il messaggio appare solo nel registro eventi di Windows (registro Applicazione, origine ASP.NET). Quando un sito smette di rispondere subito dopo l'aggiunta di una riga AddPlugin, controlla prima i file di licenza in wwwroot — vedi License Setup.

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 gate della licenza
    void Register(IDoconutPluginBuilder builder); // contribuisci visualizzatori/servizi
}

All'interno di Register, il builder accetta due tipi di contributo:

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

Capacità e gating

Le capacità sono le unità di licenza. Converter, Dicom e Signer vengono forniti come plugin opzionali; Search e Annotation sono funzionalità integrate con lo stesso gating. Il visualizzatore di base non è una capacità — è il prerequisito, esposto come IsViewerLicensed sul servizio di licenza.

La convalida all'avvio normalmente mantiene un plugin non licenziato fuori dalla pipeline di richieste. La factory del visualizzatore applica anche due regole difensive, importanti se i diritti cambiano mentre il sito è in esecuzione:

  • Un plugin che sovrascrive un visualizzatore integrato (rivendica un'estensione gestita anche da un visualizzatore integrato): con la capacità concessa, il visualizzatore del plugin prevale; senza di essa, Doconut ritorna al visualizzatore integrato. Gli utenti vedono comunque il loro documento; semplicemente non ottengono il comportamento del plugin.
  • Un formato solo plugin (.dcm e .ima — DICOM non ha un visualizzatore integrato): senza la capacità, l'apertura fallisce:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Una licenza Temporanea attiva concede ogni capacità. Questo è un classico sorpresa al go-live: le stesse righe AddPlugin che sono state eseguite durante la valutazione interrompono il sito quando la licenza acquistata omette una di quelle capacità. Confronta IsCapabilityGranted(...) con ciò che hai acquistato prima del deployment. Con nessuna licenza, nulla è concesso — una licenza mancante non è una licenza Temporanea.

Lo stesso gating raggiunge il browser: Viewer.ReferenceScripts() e ReferenceCss() emettono i file per le funzionalità con gating di licenza (Ricerca, Annotazione) solo quando la licenza le concede, così la pagina non offre mai una funzionalità che il server rifiuterà.

Mappa delle funzionalità e dei plugin

FunzionalitàCome viene abilitataCapacitàContribuisce
AnnotazioneIntegrata nel visualizzatore; includi le risorse di annotazioneAnnotationCreazione nel browser, persistenza della sessione, esportazioni incorporate
RicercaIntegrata nei visualizzatori di formati ricercabili; includi le risorse di ricercaSearchIndice di testo nativo, evidenziazioni, navigazione dei risultati
ConvertitoreInstalla Doconut.NETFramework.Converter e registra ConverterPluginConverterServizio di conversione C# e un widget web opzionale
DICOMInstalla Doconut.NETFramework.Dicom e registra DicomPluginDicomVisualizzazione di immagini mediche per .dcm e .ima
FirmatarioInstalla Doconut.NETFramework.Signer e registra SignerPluginSignerFirme visibili e sigilli digitali per PDF e Word: servizio di firma C# e un widget web opzionale

Annotazione e Ricerca non utilizzano AddPlugin<TPlugin>(). Convertitore, DICOM e Firmatario hanno ciascuno una pagina sotto Plugin con la loro configurazione e utilizzo. In questo pacchetto, DICOM rende pagine, fotogrammi e animazioni, ma non legge i metadati tecnici — vedi DICOM Plugin.

Visualizzatori personalizzati — il tuo gestore di formato

Puoi collegare un visualizzatore alla pipeline senza scrivere un pacchetto plugin, direttamente in Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),                        // implementa IFormatViewer
        () => new ImageConfig { ImageResolution = 150 });  // configurazione predefinita opzionale
});

// Il gestore di formato che la factory 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 la precedenza su tutto — sia integrati che plugin — e non sono soggetti a gating di licenza: sono il tuo codice. Quando non fornisci una configurazione predefinita, la factory utilizza un ImageConfig.

Conclusioni

  • I plugin sono registrati esplicitamente in DoconutHost.Initialize, e le loro capacità sono validate lì; un diritto mancante interrompe il sito con un 500 vuoto la cui ragione è nel registro eventi di Windows.
  • 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.

Questa pagina è stata utile?