DoconutOptions – Documentazione Doconut

DoconutOptions (namespace Doconut) è l'oggetto di configurazione unico per l'intero SDK. Lo configuri una sola volta, nel callback che passi a DoconutHost.Initialize in Application_Start.

csharp

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Proprietà

Tipo	Proprietà	Predefinito	Descrizione
`bool`	`UnsafeMode`	`false`	Quando `false`, `DocImage.axd` serve una pagina solo alla sessione ASP.NET che ha aperto il documento (o, in un farm, al browser con un ticket firmato). Quando `true`, qualsiasi richiesta contenente il token viene servita. Lascialo `false` — vedi Sessioni e Sicurezza.
`bool`	`ShowDoconutInfo`	`false`	Quando `true`, una richiesta `DocImage.axd` senza token risponde `Doconut <version> is running on <host>` invece di `404`. Utile come verifica rapida; lascia `false` in produzione.
`string`	`ResourcesPath`	`"/doconut-res"`	Prefisso URL sotto il quale il modulo delle risorse serve gli script, gli stili e le immagini incorporati.
`string`	`LicensePath`	`""`	Percorso completo al file di licenza. Vuoto → la fonte di licenza successiva, poi scoperta automatica; se non trovato → valutazione con filigrana senza funzionalità.
`string`	`LicenseContent`	`""`	Contenuto grezzo della licenza (database, variabile d'ambiente, archivio segreto). Ha precedenza su `LicensePath`.
`Stream?`	`LicenseStream`	`null`	Licenza come stream, letta una volta all'avvio. Ha precedenza su entrambe le altre fonti.
`string`	`MiddlewarePath`	`"/doconut"`	Non utilizzato da System.Web. Il punto finale della pagina è sempre il gestore `DocImage.axd` dichiarato in `Web.config`. Il valore è comunque convalidato all'avvio (vedi sotto).
`bool`	`ResetLicense`	`false`	Non utilizzato. La licenza viene letta una volta, in `DoconutHost.Initialize`; ricicla il pool dell'applicazione dopo aver sostituito una licenza.
`DoconutPluginRegistry`	`PluginRegistry`	—	Registro di sola lettura dei contributi dei plugin, popolato da `AddPlugin<T>()`.

Priorità della licenza: LicenseStream → LicenseContent → LicensePath → scoperta automatica (vedi Configurazione Licenza).

Metodi

AddPlugin<TPlugin>()

text

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

Registra un plugin (Converter, DICOM). Fluent — restituisce l'istanza delle opzioni. Annotation e Search sono funzionalità con licenza integrate e non lo usano.

Se nessuna licenza attiva concede la capacità del plugin, DoconutHost.Initialize genera InvalidOperationException da Application_Start, e il sito risponde a ogni richiesta con un 500 vuoto finché non viene risolto; il messaggio è nel registro eventi di Windows (vedi Sistema Plugin).

Add…Widget()

text

DoconutOptions AddConverterWidget(Action<ConverterWidgetOptions>? configure = null)

I widget plug‑and‑play sono disattivati per impostazione predefinita. Ogni chiamata Add…Widget() attiva gli endpoint di quel widget su DocImage.axd e richiede che il plugin corrispondente sia registrato. Il modulo delle risorse serve lo script del widget indipendentemente dall'abilitazione, quindi un widget che si carica e dipinge ma risponde 404 alla sua prima azione manca di questa chiamata. Il widget Converter è documentato in Plugin Converter.

RegisterViewer(extension, 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 sui visualizzatori integrati e sui 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

DoconutHost.Initialize convalida le opzioni prima di creare qualsiasi cosa:

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.

MiddlewarePath è verificato anche se System.Web non lo utilizza mai, quindi lascialo al valore predefinito. Come ogni eccezione lanciata da Application_Start, un fallimento di convalida appare come un 500 vuoto su ogni richiesta, con il messaggio nel registro eventi di Windows.

Configurazioni comuni

csharp

// Production: explicit license, everything else at its secure default.
public static void ProductionLicense() =>
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
    });

// Custom resource path (e.g. to avoid a route conflict). Keep the viewer's ResPath and any MVC
// IgnoreRoute in step with it: "/docs-assets" means ResPath: 'docs-assets/images'.
public static void CustomResourcePath() =>
    Doconut.DoconutHost.Initialize(options =>
    {
        options.ResourcesPath = "/docs-assets";
    });

Quando cambi ResourcesPath, modifica tre cose insieme: l'opzione, il ResPath del widget ('docs-assets/images' per "/docs-assets"), e, in MVC, l'IgnoreRoute per il percorso delle risorse (routes.IgnoreRoute("docs-assets/{*pathInfo}")). L'endpoint DocImage.axd non si sposta: il suo percorso è impostato dall'attributo path del gestore in Web.config.