DoconutOptions

Configura i servizi Doconut

DoconutOptions (namespace Doconut) è l'oggetto di configurazione unico per l'intero SDK. Lo configuri una volta, all'interno di AddDoconut(), ed è registrato come singleton.

Questo è un cambiamento di posizione tanto quanto di forma. Nella precedente libreria .NET Standard un l'istanza DoconutOptions era costruita al momento del pipeline e passata a UseDoconut(new DoconutOptions { … }). Qui il middleware non accetta alcuna opzione — tutto è impostato durante la registrazione del servizio.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Proprietà

TipoProprietàPredefinitoDescrizione
boolShowDoconutInfofalseQuando true, una richiesta middleware senza token restituisce un banner di versione (Doconut <version> is running on <host>) invece di 404. Utile come controllo rapido; lascia false in produzione.
boolUnsafeModefalseQuando true, salta il controllo di sicurezza della sessione ASP.NET nelle richieste di pagina. Lascia false in produzione su un singolo nodo (vedi Concetti di base → Sessioni e Sicurezza). Precedentemente scritto UnSafeMode.
stringMiddlewarePath"/doconut"Valore di coordinazione per l'endpoint page-image. Viene validato, ma non monta un ramo del pipeline; mantienilo allineato con la mappatura reale UseDoconut() e il client BasePath.
stringResourcesPath"/doconut-res"Prefisso del percorso URL per le risorse JS/CSS/immagine/font incorporate.
stringLicensePath""Percorso al file di licenza. Vuoto → fonte di licenza successiva, poi scoperta automatica; se non trovato → stato di valutazione con filigrana senza capacità.
stringLicenseContent""Contenuto XML grezzo della licenza (database, variabile d'ambiente, gestore segreti). Ha precedenza su LicensePath.
Stream?LicenseStreamnullLicenza come stream, letta una volta all'avvio. Ha precedenza su entrambe le altre fonti.
boolResetLicensefalseFlag di compatibilità riservato. L'implementazione corrente non lo utilizza; riavvia l'applicazione dopo aver sostituito una licenza.
DoconutPluginRegistryPluginRegistry—Registro in sola lettura che raccoglie i contributi dei plugin; consumato dalla factory del visualizzatore. Popolalo tramite AddPlugin<T>().

Priorità delle licenze (applicata durante la registrazione del servizio): LicenseStream → LicenseContent → LicensePath → scoperta automatica (vedi Guida introduttiva → Configurazione licenza).

Metodi

AddPlugin<TPlugin>()

text
DoconutOptions AddPlugin<TPlugin>() where TPlugin : IDoconutPlugin, new()

Usa questo metodo per i pacchetti Converter, DICOM e Signer rilasciati con opt-in. L'annotazione e la ricerca normale sono funzionalità con licenza integrate e non utilizzano AddPlugin<TPlugin>().

Registra un plugin di prima parte (Converter, DICOM, Signer). Fluent — restituisce l'istanza delle opzioni. AddDoconut() genera InvalidOperationException per una licenza mancante, file legacy TRIAL, o licenza a pagamento che non concede la capacità del plugin. Le registrazioni temporanee/Demo sono mantenute oltre la scadenza e diventano soggette al filtro di runtime (vedi Concetti di base → Sistema plugin).

Il widget Converter con opt-in è abilitato con AddConverterWidget() e reso disponibile tramite la proprietà in sola lettura ConverterWidget; le sue opzioni sono documentate nella pagina del plugin Converter (Plugins → Plugin Converter). Il widget Signer con opt-in è abilitato allo stesso modo, con AddSignerWidget(), e reso disponibile tramite la proprietà in sola lettura SignerWidget; vedi Plugin Signer.

RegisterViewer(extension, factory, defaultConfig?)

text
DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — punto iniziale opzionale
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

Registra un visualizzatore personalizzato per un'estensione di file. I visualizzatori personalizzati hanno precedenza su quelli integrati e sui visualizzatori dei plugin e non sono soggetti a licenza. Quando defaultConfig è omesso e un documento si apre senza una configurazione esplicita, viene usato un ImageConfig.

Genera ArgumentException (Extension must be a non-empty file extension.) per un'estensione vuota e ArgumentNullException per una factory nulla.

Validazione all'avvio

AddDoconut() valida le opzioni fail-fast, così una configurazione errata appare come un'eccezione chiara all'avvio invece di 404 confusi al momento della richiesta:

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

Configurazioni comuni

csharp
// Produzione: licenza esplicita, tutto bloccato (tutte le impostazioni di sicurezza predefinite)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Percorsi personalizzati (ad es. per evitare un conflitto di percorso)
builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});

Quando modifichi ResourcesPath, mantieni sincronizzato il ResPath del widget client (vedi ViewerConfig). Questa è una delle due impostazioni client-side che falliscono senza un messaggio di errore.

MiddlewarePath non è un mapper automatico di route ASP.NET Core. Se Doconut deve rispondere solo sotto un prefisso personalizzato, monta UseDoconut() su quel ramo (ad esempio con app.Map("/docs-engine", branch => branch.UseDoconut())) e imposta il client BasePath su quel prefisso senza il / iniziale ('docs-engine'). Un'alternativa comune mantiene la forma storica della richiesta DocImage.axd su un ramo MapWhen con BasePath: '/'.

Questa pagina è stata utile?