DoconutOptions – Documentazione Doconut

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

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

csharp

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

Proprietà

Tipo	Proprietà	Predefinito	Descrizione
`bool`	`ShowDoconutInfo`	`false`	Quando `true`, una richiesta middleware senza token restituisce un banner di versione invece di un 404. Utile come verifica rapida; lascia `false` in produzione.
`bool`	`UnsafeMode`	`false`	Quando `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). In precedenza scritto `UnSafeMode`.
`string`	`MiddlewarePath`	`"/doconut"`	Valore di coordinamento per l'endpoint pagina-immagine. Viene convalidato, ma non monta un ramo del pipeline; mantienilo allineato con la mappatura reale di `UseDoconut()` e con il `BasePath` del client.
`string`	`ResourcesPath`	`"/doconut-res"`	Prefisso del percorso URL per le risorse JS/CSS/immagine/font incorporate.
`string`	`LicensePath`	`""`	Percorso al file di licenza. Vuoto → fonte di licenza successiva, poi scoperta automatica; se non trovato → stato di valutazione con filigrana senza funzionalità.
`string`	`LicenseContent`	`""`	Contenuto XML grezzo della licenza (database, variabile d'ambiente, gestore segreti). Ha precedenza su `LicensePath`.
`Stream?`	`LicenseStream`	`null`	Licenza come stream, letta una sola volta all'avvio. Ha precedenza su entrambe le altre fonti.
`bool`	`ResetLicense`	`false`	Flag di compatibilità riservata. L'implementazione attuale non la utilizza; riavvia l'applicazione dopo aver sostituito una licenza.
`DoconutPluginRegistry`	`PluginRegistry`	—	Registro di sola lettura che raccoglie i contributi dei plugin; consumato dalla factory del visualizzatore. Popolalo tramite `AddPlugin<T>()`.

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

Metodi

AddPlugin()

text

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

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

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

Il widget Converter opzionale è abilitato con AddConverterWidget() e reso disponibile tramite la proprietà di sola lettura ConverterWidget; le sue opzioni sono documentate nella pagina del Plugin Converter (Plugin → Plugin Converter).

RegisterViewer(estensione, factory, defaultConfig?)

text

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — leading dot optional
    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.

Convalida 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 deve essere un percorso non vuoto che inizia con '/'.
DoconutOptions.ResourcesPath deve essere un percorso non vuoto che inizia con '/'.
DoconutOptions.MiddlewarePath e ResourcesPath devono essere percorsi diversi.

Configurazioni comuni

csharp

// Production: explicit license, everything locked down (all security defaults)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Custom paths (e.g. to avoid a route conflict)
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 lato client che falliscono senza un messaggio di errore.

MiddlewarePath non è un mapper di route automatico di 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 BasePath del client sulla stessa URL. L'applicazione di riferimento invece mantiene la forma storica della richiesta DocImage.axd su un ramo MapWhen con BasePath: '/'.