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, vous permettant de convertir des documents depuis C#, depuis le widget, ou depuis une interface que vous créez vous-même.

Installer le package

Installez le plugin Converter le plus récent et stable :

dotnet add package Doconut.NET6.Converter

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

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

Conservez le package Converter à la même version que Doconut.NET6. L'ID du package est Doconut.NET6.Converter ; .26.7.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 Converter, s'enregistre de la même façon : appelez AddPlugin<TPlugin>() à l'intérieur de AddDoconut(). ConverterPlugin est fourni dans son propre package NuGet, Doconut.NET6.Converter, installé à côté du package 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 déclenché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 calendaire, la conversion reste disponible avec une sortie filigranée. Il n'existe aucun 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ù vous en avez besoin — il est sans état par conception, ainsi une seule instance peut être réutilisée en toute sécurité entre les requêtes.

// 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 de 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

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 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 cet enum 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 prêt à l'emploi

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 lui-même est toujours servi (c'est une ressource statique intégrée simple ; seuls les points de terminaison qu'il utilise sont protégés). AddConverterWidget() nécessite toujours que le plugin Converter soit enregistré et qu'une licence accordant Converter soit présente — il ne confère pas de 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();         // back to the idle/drop screen; does not re-fire onReady
conv.loadFile(file);  // starts the flow with a File object; no-op unless currently idle
conv.destroy();       // removes listeners, empties the mount; the instance is unusable after this

Construire votre propre interface

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

Les octets source téléchargé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 ré‑ouvert. 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 visualisation 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 (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 retourné son contenu. Le service DocumentConverter lui‑même est sans état et est résolu via l'injection de dépendances ; ne le construisez ni ne le libérez manuellement.

Pour le widget web, les stockages d'upload 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 un résultat de visualisation ne supprime pas un stockage 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 est dans l'un des trois états :

Les deux chemins d'appel calculent le drapeau selon la même règle : la façade C# DocumentConverter le déduit en interne à partir des états 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 avec une licence d'évaluation avant l'achat — seuls les octets de sortie changent.