DoconutOptions – Documentation Doconut

DoconutOptions (namespace Doconut) est l'objet de configuration unique pour l'ensemble du SDK. Vous le configurez une fois, dans le rappel que vous transmettez à DoconutHost.Initialize dans 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>();
});

Propriétés

Type	Propriété	Valeur par défaut	Description
`bool`	`UnsafeMode`	`false`	Lorsque `false`, `DocImage.axd` ne sert une page qu'à la session ASP.NET qui a ouvert le document (ou, dans un serveur en grappe, au navigateur via un ticket signé). Lorsque `true`, toute requête portant le jeton est servie. Laissez-le `false` — voir Sessions et sécurité.
`bool`	`ShowDoconutInfo`	`false`	Lorsque `true`, une requête `DocImage.axd` sans jeton répond `Doconut <version> is running on <host>` au lieu de `404`. Utile comme test de fumée ; laissez `false` en production.
`string`	`ResourcesPath`	`"/doconut-res"`	Préfixe d'URL sous lequel le module de ressources sert les scripts, styles et images intégrés.
`string`	`LicensePath`	`""`	Chemin complet vers le fichier de licence. Vide → la source de licence suivante, puis découverte automatique ; rien trouvé → version d'évaluation filigranée sans fonctionnalités.
`string`	`LicenseContent`	`""`	Contenu brut de la licence (base de données, variable d'environnement, magasin secret). Prend le pas sur `LicensePath`.
`Stream?`	`LicenseStream`	`null`	Licence sous forme de flux, lue une fois au démarrage. Prend le pas sur les deux autres sources.
`string`	`MiddlewarePath`	`"/doconut"`	Non utilisé par System.Web. Le point de terminaison de la page est toujours le gestionnaire `DocImage.axd` déclaré dans `Web.config`. La valeur est toujours validée au démarrage (voir ci‑dessous).
`bool`	`ResetLicense`	`false`	Non utilisé. La licence est lue une fois, dans `DoconutHost.Initialize` ; recyclez le pool d'applications après avoir remplacé une licence.
`DoconutPluginRegistry`	`PluginRegistry`	—	Registre en lecture seule des contributions de plugins, rempli par `AddPlugin<T>()`.

Priorité des licences : LicenseStream → LicenseContent → LicensePath → découverte automatique (voir Configuration de licence).

Méthodes

AddPlugin<TPlugin>()

text

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

Enregistre un plugin (Converter, DICOM). Fluent — renvoie l'instance d'options. Annotation et Search sont des fonctionnalités intégrées sous licence et ne l'utilisent pas.

Si aucune licence active n'accorde la capacité du plugin, DoconutHost.Initialize lève InvalidOperationException depuis Application_Start, et le site répond à chaque requête avec un 500 vide jusqu'à ce que le problème soit résolu ; le message se trouve dans le journal d'événements Windows (voir Système de plugins).

Add…Widget()

text

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

Les widgets prêts à l'emploi sont désactivés par défaut. Chaque appel Add…Widget() active les points de terminaison de ce widget sur DocImage.axd, et nécessite que le plugin correspondant soit enregistré. Le module de ressources sert le script du widget qu'il soit activé ou non, ainsi un widget qui se charge et s'affiche mais répond 404 lors de sa première action manque cet appel. Le widget Converter est documenté dans Plugin Converter.

RegisterViewer(extension, factory, defaultConfig?)

text

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — point initial facultatif
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

Enregistre un visualiseur personnalisé pour une extension de fichier. Les visualiseurs personnalisés ont la priorité sur les visualiseurs intégrés et ceux des plugins et ne sont pas soumis à une licence. Lorsque defaultConfig est omis et qu'un document s'ouvre sans configuration explicite, un ImageConfig est utilisé.

Lève ArgumentException (Extension must be a non-empty file extension.) pour une extension vide et ArgumentNullException pour une usine nulle.

Validation au démarrage

DoconutHost.Initialize valide les options avant de créer quoi que ce soit :

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 est vérifié même si System.Web ne l'utilise jamais, donc laissez-le à sa valeur par défaut. Comme chaque exception levée depuis Application_Start, un échec de validation apparaît comme un 500 vide sur chaque requête, avec le message dans le journal d'événements Windows.

Configurations courantes

csharp

// Production: licence explicite, tout le reste à sa valeur sécurisée par défaut.
public static void ProductionLicense() =>
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
    });

// Chemin de ressource personnalisé (p. ex. pour éviter un conflit de route). Conservez le ResPath du visualiseur et tout MVC
// IgnoreRoute en phase avec cela : "/docs-assets" signifie ResPath : 'docs-assets/images'.
public static void CustomResourcePath() =>
    Doconut.DoconutHost.Initialize(options =>
    {
        options.ResourcesPath = "/docs-assets";
    });

Lorsque vous modifiez ResourcesPath, modifiez trois éléments simultanément : l'option, le ResPath du widget ('docs-assets/images' pour "/docs-assets"), et, en MVC, le IgnoreRoute pour le chemin de la ressource (routes.IgnoreRoute("docs-assets/{*pathInfo}")). Le point de terminaison DocImage.axd ne bouge pas : son chemin est défini par l'attribut path du gestionnaire dans Web.config.