Plugin Convertisseur

Le plugin Convertisseur transforme Doconut en un service de conversion de documents. Il fournit le moteur derrière la façade publique DocumentConverter, et — en option — un widget prêt à l'emploi avec son propre contrat HTTP, afin que vous puissiez convertir des documents depuis C#, depuis le widget, ou depuis une interface que vous créez vous-même.

Installer le paquet

Installez le dernier plugin Convertisseur stable :

dotnet add package Doconut.NETStandard.Converter

Pour fixer le plugin à la version actuelle 26.8.0, indiquez la version séparément :

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

Conservez le paquet Convertisseur à la même version que Doconut.NETStandard. L'ID du paquet est Doconut.NETStandard.Converter ; .26.8.0 n'apparaît que dans le nom du fichier .nupkg téléchargé.

Enregistrer le plugin

Il n'existe pas de méthode AddConverter() — le modèle de plugins de Doconut est uniforme. Chaque plugin, y compris Convertisseur, s'enregistre de la même façon : appelez AddPlugin<TPlugin>() à l'intérieur de AddDoconut(). ConverterPlugin est fourni dans son propre paquet NuGet, Doconut.NETStandard.Converter, installé à côté du paquet de visualisation de base.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Cet appel lève une exception au démarrage en cas de licence manquante, d'un fichier TRIAL hérité, ou d'une licence non temporaire qui ne confère pas la capacité Converter — une InvalidOperationException générée depuis l'intérieur de AddDoconut(), avant que l'application ne traite les requêtes. Les enregistrements temporaires Démo/NFR sont acceptés ; après leur expiration calendrier, la conversion reste disponible avec une sortie filigranée. Il n'existe pas de niveau gratuit silencieux. Voir Configuration de licence pour savoir comment les licences sont chargées.

Convertir depuis C#

Chaque conversion renvoie un MemoryStream recherchable positionné à 0, prêt à être lu ou copié immédiatement. Résolvez DocumentConverter via l'injection de dépendances (DI) où que vous en ayez besoin — il est sans état par conception, ainsi une seule instance peut être réutilisée en toute sécurité entre les requêtes.

viewer.Converter.GetConverter() n'existe pas ici. La conversion n'est plus accessible via l'instance du visualiseur : injectez Doconut.DocumentConverter à la place.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Deux détails faciles à se tromper : sourceExtension dans la surcharge de flux doit inclure le point initial (".xlsx", pas "xlsx") — le convertisseur le compare au catalogue des formats et une extension sans point ne sera pas résolue. Et malgré son nom, WordToHtmlAsync renvoie Task<Stream>, pas Task<string> — vous obtenez le document HTML (images intégrées en Base64) sous forme de flux, comme chaque autre résultat de conversion.

Formats cibles

ConversionTarget (espace de noms Doconut.Configs.Conversion) possède 45 membres :

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

Cette énumération couvre toutes les familles sources. La bibliothèque précédente disposait d'un type *ConfigConverter par famille — WordConfigConverter, ExcelConfigConverter, etc. — chacun avec sa propre énumération imbriquée EnTargetFormat, ainsi qu'une énumération SourceFormatConverter pour l'entrée. Tout cela a disparu ; voir le guide de migration.

Toutes les sources ne se convertissent pas vers toutes les cibles — le plugin associe chaque famille de format source (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagramme, Projet/Tâche, PSD, document web) à son propre ensemble fixe de cibles autorisées. Ne codez pas en dur cette énumération comme liste de cibles de votre interface : ?convert=open renvoie les allowedTargets réels pour le fichier qui vient d'être téléchargé, et c'est ce qui doit alimenter le sélecteur.

Widget intégrable

Les points de terminaison ?convert=open|run|download du widget sont optionnels et désactivés par défaut — sécurisés par défaut. Activez‑les côté serveur, en même temps que l’enregistrement du plugin :

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;
    });
});

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Sans AddConverterWidget(), les trois points de terminaison ?convert= renvoient 404 — mais le fichier JS est tout de même servi (c’est une ressource statique intégrée ; seuls les points de terminaison qu’il contacte sont protégés). AddConverterWidget() nécessite toujours que le plugin Converter soit enregistré et qu’une licence accordant Converter soit présente — il n’accorde pas les droits de conversion à lui seul.

Personnaliser le widget

Options d’initialisation passées à Doconut.convert(selector, options) :

Rappels :

Doconut.convert() renvoie l’instance du widget elle‑même — conservez‑la pour piloter le widget de façon programmatique :

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // revient à l’écran d’attente/dépose ; ne relance pas onReady
conv.loadFile(file);  // démarre le flux avec un objet File ; aucune action si le widget n’est pas en attente
conv.destroy();       // supprime les écouteurs, vide le montage ; l’instance devient inutilisable après cela

Créez votre propre interface

Le widget n’est qu’un client pour ce contrat HTTP — construisez votre propre interface directement contre celui‑ci pour une UX différente. Les trois routes se trouvent sous la branche ASP.NET où UseDoconut() est montée (généralement /doconut) :

Les octets source téléversés sont stockés côté serveur avec un TTL de 30 minutes ; une fois cette fenêtre écoulée, run renvoie 404 et le fichier doit être rouvert. Le résultat converti vit dans le même stockage — downloadToken obtient sa propre fenêtre fraîche de 30 minutes à la fin de la conversion — tandis que resultToken est un jeton de session de visualiseur ordinaire dont la durée suit le cache de session du visualiseur, indépendamment du stockage.

sourceExt dans la réponse open ne comporte pas de point initial (ex. "docx") — l’inverse de la convention du paramètre sourceExtension de DocumentConverter.ConvertAsync, qui en nécessite un.

Modes d’échec, regroupés par route :

Propriété des ressources

Le convertisseur renvoie un MemoryStream séekable positionné à zéro. L'appelant possède ce flux et doit le libérer après l'avoir copié ou après avoir renvoyé son contenu. Le service DocumentConverter lui‑même est sans état et est résolu via l’injection de dépendances ; ne pas créer ou libérer le service manuellement.

Pour le widget web, les caches de téléchargement et de téléversement ont des TTL indépendants de 30 minutes. Un resultToken de visualiseur suit la durée de vie de la session du visualiseur à la place. Fermer un résultat de visualiseur ne supprime pas un cache de téléchargement encore valide, et réinitialiser le widget du navigateur n’allonge aucun des TTL.

Dépannage

Filigrane

Avec ConverterPlugin enregistré, la licence de l’hôte se trouve dans l’un des trois états :

Les deux chemins d’appel calculent le drapeau à partir de la même règle : la façade C# DocumentConverter le déduit en interne à partir de l’état IsViewerLicensed et IsTemporary de la licence, et le gestionnaire ?convert=run du widget effectue la même vérification (IsViewerLicensed && !IsTrial && !IsTemporary) pour remplir le champ watermarked qu’il renvoie. Une intégration peut être construite et testée de bout en bout sur une licence d’évaluation avant l’achat — seuls les octets de sortie changent.