Plugin de conversion

Le plugin Converter 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 Converter stable :

dotnet add package Doconut.NET6.Converter

Pour fixer le plugin à la version actuelle 26.7.0, transmettez la version séparément :

dotnet add package Doconut.NET6.Converter --version 26.7.0

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

Enregistrer le plugin

Il n'existe pas de méthode AddConverter() — le modèle de plugins de Doconut est uniforme. Chaque plugin, y compris Converter, 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.NET6.Converter, installé à côté du paquet du visualiseur 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 déclenchée depuis l'intérieur de AddDoconut(), avant que l'application ne serve les requêtes. Les enregistrements temporaires Démo/NFR sont acceptés ; après leur expiration calendaire, 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 depuis l'injection de dépendances 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.

// Injectez DocumentConverter ; son constructeur est interne, donc ne le `new` jamais.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension inclut le point initial. password est nul sauf si le document est protégé.
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 sur la surcharge du flux doit inclure le point initial (".xlsx", pas "xlsx") — le convertisseur le compare au catalogue des formats et une extension seule ne sera pas résolue. Et malgré son nom, WordToHtmlAsync renvoie Task<Stream>, pas Task<string> — vous obtenez le document HTML (images incorporées en Base64) sous forme de flux, comme chaque autre résultat de conversion.

Formats cibles

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

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

Widget à intégrer

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= répondent 404 — mais le fichier JS lui‑même est toujours servi (c’est une ressource statique simple intégrée ; seuls les points de terminaison auxquels il accède sont protégés). AddConverterWidget() nécessite toujours que le plugin Converter soit enregistré et une licence qui accorde Converter — cela ne confère pas de droits de conversion en soi.

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();         // retour à l'écran d'inactivité/de dépôt ; ne relance pas onReady
conv.loadFile(file);  // démarre le flux avec un objet File ; no‑op sauf si actuellement inactif
conv.destroy();       // supprime les écouteurs, vide le mount ; l'instance est inutilisable après cela

Construisez votre propre interface

Le widget n’est qu’un client de ce contrat HTTP — créez votre propre interface directement contre celui‑ci pour une expérience utilisateur 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 ce délai écoulé, run répond 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 lorsque la conversion se termine — tandis que resultToken est un jeton de session de visualiseur ordinaire dont la durée de vie suit le cache de session du visualiseur, indépendamment du stockage.

sourceExt dans la réponse open n’a pas de point initial (p. ex. "docx") — la convention opposée du paramètre sourceExtension sur DocumentConverter.ConvertAsync, qui en nécessite un.

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

Propriété des ressources

Le convertisseur renvoie un MemoryStream recherchable 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 construisez pas ou ne libérez pas le service manuellement.

Pour le widget web, les caches de téléversement et de téléchargement ont des TTL indépendants de 30 minutes. Un resultToken de visualisation suit la durée de vie de la session du visualiseur à la place. Fermer le résultat d'un visualiseur ne supprime pas un cache de téléchargement encore valide, et réinitialiser le widget du navigateur n'étend aucun des deux 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érive en interne à partir de l'état IsViewerLicensed et IsTemporary de la licence, et le gestionnaire ?convert=run du widget effectue la vérification équivalente (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.