Enregistrer et activer le widget convertisseur intégré de Doconut dans .NET 8

Le widget intégré est l’interface prête à l’emploi de Doconut pour télécharger un fichier, lancer une conversion et télécharger le résultat.
Par défaut, les trois points de terminaison ?convert= du widget renvoient 404 ; ils ne deviennent actifs que lorsque vous enregistrez le plugin Converter et appelez AddConverterWidget() sur DoconutOptions.

Ci-dessous se trouve une configuration de démarrage complète, prête à copier‑coller, qui satisfait les deux exigences.

---

1. Prérequis – licence et prise en charge de la session

• Licence – Le plugin Converter nécessite une licence qui accorde la capacité Converter. Placez le fichier (par ex., Doconut.Viewer.lic) quelque part accessible par l’application et pointez DoconutOptions.LicensePath vers celui‑ci.
• État de session – Le modèle de sécurité de Doconut stocke les jetons de session de document dans la session ASP.NET Core. Ajoutez un cache distribué et AddSession() avant que le middleware ne soit configuré.

builder.Services.AddDistributedMemoryCache();   // requis pour la session
builder.Services.AddSession();                  // active la session IDistributedCache‑backed

---

2. Enregistrer les services principaux de Doconut

AddDoconut() est le point d’entrée unique qui injecte le visualiseur, le service de licence et le registre de plugins.

builder.Services.AddDoconut(options =>
{
    // Indiquez à Doconut où trouver le fichier de licence.
    options.LicensePath = "Doconut.Viewer.lic";

    // Enregistrez le plugin Converter – cela valide également la capacité de licence.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Si la licence n’inclut pas la capacité Converter, l’appel ci‑dessus lève InvalidOperationException et l’application ne démarrera pas. Ce comportement d’échec rapide vous empêche de déployer une version mal licenciée.

---

3. Activer le widget avec AddConverterWidget

Le widget est optionnel. L’appel à AddConverterWidget() enregistre les trois points de terminaison de conversion (?convert=open, ?convert=run, ?convert=download) et configure une petite quantité de paramètres côté client (taille maximale de téléchargement, chemins de base, etc.).

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

    // Activez l’interface UI intégrée et définissez la limite de téléchargement côté client.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // pré‑vérification côté client ; le serveur applique sa propre limite
    });
});

Seul l’appel AddConverterWidget crée les points de terminaison ; le fichier JavaScript statique (doconutConverter.js) est toujours servi comme ressource intégrée, mais il échouera à contacter le serveur si les points de terminaison sont absents.

---

4. Configurer le middleware dans le bon ordre

Le middleware qui sert les ressources statiques (UseDoconutResources) doit s’exécuter avant le middleware terminal du visualiseur (UseDoconut). Le middleware de session doit également être placé plus tôt car Doconut valide la session à chaque requête.

app.UseSession();           // doit précéder UseDoconut()
app.UseDoconutResources();  // sert le JS, le CSS, les images
app.UseDoconut();           // gère les requêtes ?convert= et les pages de document

Avec ce pipeline en place, une requête vers /doconut-res/doconutConverter.js réussit, et le widget peut appeler /doconut?convert=open, /doconut?convert=run et /doconut?convert=download.

---

5. Ce que fait réellement le widget

Phase	Point de terminaison serveur	Réponse typique
Ouverture	?convert=open	Renvoie une charge utile JSON contenant un token, le nombre de pages, l’extension source et la liste des formats cibles autorisés.
Exécution	?convert=run	Démarre la conversion et renvoie un downloadToken, le nombre de pages du résultat, le nom de fichier suggéré, et un indicateur précisant si la sortie est filigranée.
Téléchargement	?convert=download	Diffuse le fichier converti lorsque le client suit l’URL de téléchargement fournie.

Côté client, le widget effectue une vérification de taille avant le téléchargement contre widget.MaxUploadMb. Si le fichier dépasse cette limite, le widget annule le téléchargement et déclenche le rappel onError avec phase = "open" et un message convivial. Le serveur impose sa propre limite et répondra 413 Payload Too Large si la requête passe la vérification client.

---

6. Accrocher aux événements du widget (côté C# non requis)

Tous les rappels (onReady, onSourceLoaded, onConverted, onError, etc.) sont des fonctions JavaScript fournies par la page qui héberge le widget. Comme la question porte sur le côté enregistrement, vous n’avez pas besoin d’écrire du code C# supplémentaire pour gérer ces rappels — le widget les invoque automatiquement une fois les points de terminaison actifs.

---

7. Pièges courants et comment les éviter

Symptôme	Cause probable	Solution
404 on /doconut?convert=open	AddConverterWidget() a été omis.	Ajoutez l’appel comme indiqué dans la section 3.
L’application échoue au démarrage avec InvalidOperationException concernant une capacité manquante	Le fichier de licence n’accorde pas Converter.	Obtenez une licence qui inclut la capacité Converter.
Erreur liée à la session 500	UseSession() placé après UseDoconut() ou enregistrement du cache manquant.	Assurez‑vous que app.UseSession() s’exécute avant app.UseDoconut() et qu’un service de cache est enregistré.

---

8. Exécuter l’application et voir le widget en action

1. Compilez et exécutez le projet ASP.NET Core.
2. Ouvrez une page contenant un élément <div id="doconut-convert"></div> et incluant le script de conversion Doconut (le script est servi automatiquement depuis /doconut-res/doconutConverter.js).
3. Glissez‑déposez un fichier pris en charge (PDF, DOCX, DWG, etc.) sur la zone de dépôt.
4. Le widget appellera ?convert=open, puis ?convert=run, et enfin présentera un lien Télécharger pointant vers ?convert=download.

Si les trois points de terminaison répondent avec du JSON au lieu de 404, le widget est correctement enregistré et prêt pour une utilisation en production.

Étape suivante : Ajoutez les extraits de code ci‑dessus à votre Program.cs (ou Startup.cs), vérifiez que le fichier de licence est présent, puis lancez l’application. Le widget convertisseur intégré sera actif sans aucune autre modification côté serveur.