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 :

csharp
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 :

text
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 :

csharp
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 un IFormatViewer (le plugin DICOM enregistre .dcm et .ima de 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 (.dcm et .ima — DICOM n’a pas de visualiseur intégré) : sans la capacité, l’ouverture échoue :
text
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éeCapacitéContribue
AnnotationIntégré au visualiseur ; inclure les ressources d’annotationAnnotationCréation dans le navigateur, persistance de session, exportations gravées
RechercheIntégré aux visualiseurs de formats recherchables ; inclure les ressources de rechercheSearchIndex texte natif, surlignages, navigation des résultats
ConvertisseurInstaller Doconut.NETFramework.Converter et enregistrer ConverterPluginConverterService de conversion C# et un widget web optionnel
DICOMInstaller Doconut.NETFramework.Dicom et enregistrer DicomPluginDicomVisualisation d’images médicales pour .dcm et .ima
SignataireInstaller Doconut.NETFramework.Signer et enregistrer SignerPluginSignerSignatures 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 :

csharp
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 un 500 vide 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 IDoconutLicenseService avant la mise en production.

Cette page était-elle utile ?