Système de plugins
Étendre le visualiseur avec des plugins
Le cœur de Doconut reste léger ; les fonctionnalités optionnelles sont livrées sous forme de plugins — des packages NuGet séparés qui apportent des visualiseurs ou des services et sont activés par votre licence. Cette page explique le modèle d’enregistrement, ce qui se passe au démarrage lorsqu’une licence ne couvre pas un plugin, et comment intégrer votre propre visualiseur.
Enregistrement d'un plugin
Chaque package de plugin expose une classe de plugin. Enregistrez‑la une fois, dans Application_Start :
Doconut.DoconutHost.Initialize(options =>
{
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// Un plugin enregistré dont la licence est manquante lance ici, dans Application_Start, et le
// le site répond alors à chaque requête avec un 500 vide. La raison se trouve dans le journal d'événements Windows.AddPlugin<TPlugin>() crée le plugin et le laisse enregistrer ses contributions avec DoconutOptions. Tout ce qu’un plugin apporte est étiqueté avec la capacité requise du plugin, et DoconutHost.Initialize vérifie chaque plugin enregistré par rapport à la licence avant que le site ne traite sa première requête.
Une licence de plugin manquante arrête le site
Lorsqu'aucune licence active n'accorde la capacité d'un plugin enregistré — aucune licence du tout, un fichier legacy TRIAL, ou une licence payante sans cette capacité — DoconutHost.Initialize lance InvalidOperationException depuis Application_Start :
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.Dans System.Web, une exception dans Application_Start ne génère pas de page d’erreur. Chaque requête renvoie un 500 vide, le journal IIS n’affiche rien d’utile, et le message apparaît uniquement dans le journal d’événements Windows (journal Application, source ASP.NET). Lorsqu’un site cesse de répondre juste après l’ajout d’une ligne AddPlugin, vérifiez d’abord les fichiers de licence dans wwwroot — voir Configuration de la licence.
Le contrat
Un plugin implémente une interface délibérément petite :
public interface IDoconutPlugin
{
string Name { get; } // par ex. "Doconut DICOM Viewer"
LicenseCapability RequiredCapability { get; } // la porte de licence
void Register(IDoconutPluginBuilder builder); // contribuer viewers/services
}À l’intérieur de Register, le constructeur accepte deux types de contribution :
builder.RegisterViewer(extension, factory)— un visualiseur pour une extension de fichier ; la fabrique renvoie unIFormatViewer(le plugin DICOM enregistre.dcmet.imade cette manière),builder.RegisterService<TContract>(() => …)— un service typé que d’autres parties du pipeline peuvent rechercher.
Capacités et filtrage
Les capacités sont les unités de licence. Converter, Dicom et Signer sont fournis comme plugins optionnels ; Search et Annotation sont des fonctionnalités intégrées filtrées de la même façon. Le visualiseur de base n’est pas une capacité — c’est le prérequis, exposé comme IsViewerLicensed sur le service de licence.
La validation au démarrage empêche normalement un plugin non licencié d’entrer dans le pipeline de requêtes. La fabrique de visualiseur applique également deux règles de défense, qui importent si les droits changent pendant l’exécution du site :
- Un plugin qui surcharge un visualiseur intégré (il revendique une extension déjà gérée par un visualiseur intégré) : si la capacité est licenciée, le visualiseur du plugin l’emporte ; sinon, Doconut revient au visualiseur intégré. Les utilisateurs voient toujours leur document ; ils n’obtiennent simplement pas le comportement du plugin.
- Un format uniquement pris en charge par un plugin (
.dcmet.ima— DICOM n’a pas de visualiseur intégré) : sans la capacité, l’ouverture échoue :
LicenseException: This document type requires the 'Dicom' plugin license.Une licence Temporaire active accorde toutes les capacités. C’est une surprise classique lors du passage en production : les mêmes lignes AddPlugin qui ont fonctionné pendant l’évaluation arrêtent le site lorsque la licence achetée omet l’une de ces capacités. Comparez IsCapabilityGranted(...) avec ce que vous avez acheté avant le déploiement. Avec aucune licence du tout, rien n’est accordé — une licence manquante n’est pas une licence Temporaire.
Le même filtrage s’applique au navigateur : Viewer.ReferenceScripts() et ReferenceCss() émettent les fichiers pour les fonctionnalités filtrées par licence (Recherche, Annotation) uniquement lorsque la licence les accorde, de sorte que la page n’offre jamais une fonctionnalité que le serveur refusera.
Carte des fonctionnalités et des plugins
| Fonctionnalité | Comment elle est activée | Capacité | Contribue |
|---|---|---|---|
| Annotation | Intégré au visualiseur ; inclure les ressources d’annotation | Annotation | Création dans le navigateur, persistance de session, exportations gravées |
| Recherche | Intégré aux visualiseurs de formats recherchables ; inclure les ressources de recherche | Search | Index texte natif, surlignages, navigation des résultats |
| Convertisseur | Installer Doconut.NETFramework.Converter et enregistrer ConverterPlugin | Converter | Service de conversion C# et un widget web optionnel |
| DICOM | Installer Doconut.NETFramework.Dicom et enregistrer DicomPlugin | Dicom | Visualisation d’images médicales pour .dcm et .ima |
| Signataire | Installer Doconut.NETFramework.Signer et enregistrer SignerPlugin | Signer | Signatures visibles et sceaux numériques pour PDF et Word : service de signature C# et un widget web optionnel |
Annotation et Recherche n’utilisent pas AddPlugin<TPlugin>(). Convertisseur, DICOM et Signataire ont chacun une page sous Plugins avec leur configuration et utilisation. Dans ce package, DICOM rend les pages, les cadres et les animations, mais ne lit pas les métadonnées techniques — voir Plugin DICOM.
Visualiseurs personnalisés — votre propre gestionnaire de format
Vous pouvez brancher un visualiseur dans le pipeline sans écrire de package de plugin, directement dans Application_Start :
Doconut.DoconutHost.Initialize(options =>
{
options.RegisterViewer(
".myext",
() => new MyCustomViewer(), // implémente IFormatViewer
() => new ImageConfig { ImageResolution = 150 }); // configuration par défaut optionnelle
});
// Le gestionnaire de format que la fabrique crée. Remplacez ces membres par votre propre rendu.
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() { }
}Les visualiseurs personnalisés ont la priorité sur tout — intégrés et plugins confondus — et ne sont pas filtrés par licence : ce sont votre code. Lorsque vous ne fournissez aucune configuration par défaut, la fabrique utilise un ImageConfig.
Points clés
- Les plugins sont enregistrés explicitement dans
DoconutHost.Initialize, et leurs capacités sont validées à cet endroit ; un droit manquant arrête le site avec un500vide dont la raison se trouve dans le journal d’événements Windows. - Les plugins de type surcharge se dégradent gracieusement ; les formats uniquement pris en charge par un plugin échouent avec un
LicenseException. - Une licence Temporaire active débloque tout ; la production débloque ce que vous avez acheté. Vérifiez avec
IDoconutLicenseServiceavant la mise en production.
Cette page était-elle utile ?