Conversion de documents côté serveur en .NET avec Doconut

Introduction

La conversion de documents côté serveur permet à une application de générer une sortie normalisée sans automatiser Microsoft Office ni envoyer la source à un service de conversion en ligne séparé. Cela peut simplifier les portails de documents, les tâches en arrière-plan et les flux d'exportation contrôlés—mais l'application hôte conserve le contrôle d'accès, le stockage, la rétention, la surveillance et la livraison du résultat.

Formats de documents abstraits circulant à travers un pipeline de conversion vers une sortie normalisée

Le plugin de conversion .NET 8 de Doconut expose la conversion via le service DocumentConverter injecté par dépendance. Ce guide se concentre sur le modèle d'enregistrement et d'API actuel et évite de coupler la conversion à une session de visualisation.

Installer les packages correspondants

Installez les packages de visualisation et de conversion de base :

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Converter

Conservez les deux packages sur la même version de publication. Lorsque la reproductibilité des builds est importante, épinglez la version dans le fichier de projet ou transmettez la même valeur --version aux deux commandes.

Enregistrer le plugin de conversion

Les plugins s'enregistrent dans le rappel d'options AddDoconut. Il n'existe pas de méthode d'enregistrement séparée AddConverter() :

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

L'application doit utiliser une licence qui accorde la capacité de conversion. Résolvez les erreurs de démarrage et de licence avant d'accepter des travaux de conversion ; ne les reportez pas à une file d'attente en arrière-plan où elles deviennent plus difficiles à diagnostiquer.

Convertir un fichier depuis C#

Injectez DocumentConverter dans le point de terminaison ou le service qui gère la demande de conversion. Le constructeur du convertisseur est interne, ainsi le code de l'application ne doit pas l'instancier directement.

app.MapPost("/api/convert", async (
    DocumentConverter converter,
    CancellationToken ct) =>
{
    await using Stream pdf = await converter.ConvertAsync(
        "documents/contract.docx",
        ConversionTarget.Pdf,
        ct: ct);

    using var copy = new MemoryStream();
    await pdf.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "contract.pdf");
});

Le flux retourné est recherchable et positionné au début. L'appelant en est propriétaire et doit le libérer après l'avoir copié ou renvoyé le contenu.

Convertir un flux téléchargé

La surcharge de flux nécessite l'extension source—y compris son point initial—car le convertisseur l'utilise pour déterminer le format source :

app.MapPost("/api/convert-upload", async (
    IFormFile file,
    DocumentConverter converter,
    CancellationToken ct) =>
{
    var extension = Path.GetExtension(file.FileName);
    await using var source = file.OpenReadStream();
    await using Stream output = await converter.ConvertAsync(
        source,
        extension,
        ConversionTarget.Pdf,
        password: null,
        ct: ct);

    using var copy = new MemoryStream();
    await output.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "converted.pdf");
});

Considérez le nom de fichier et l'extension comme des entrées non fiables. Appliquez des limites d'upload, validez le type source, autorisez l'utilisateur demandeur et évitez d'utiliser le nom de fichier soumis comme chemin de stockage.

Choisir les cibles parmi les capacités réelles

Le plugin expose une énumération ConversionTarget, mais chaque format source ne peut pas produire chaque cible. Une interface personnalisée doit afficher uniquement les cibles autorisées pour la source téléchargée plutôt que d'afficher toutes les valeurs de l'énumération.

Lors de l'utilisation du widget de conversion optionnel de Doconut, sa réponse ouverte inclut allowedTargets. Utilisez cette réponse comme source de vérité pour le fichier actuel.

Concevoir la conversion en arrière-plan comme flux de travail d'application

Le convertisseur peut être appelé depuis un service d'application ou un travailleur en file d'attente. Un travail robuste comprend généralement :

Une requête authentifiée qui enregistre la source et la cible souhaitée.
Un message de file d'attente contenant un ID de travail d'application, pas des informations d'identification brutes.
Un travailleur qui récupère la source via une abstraction de stockage autorisée.
Une opération de conversion bornée avec annulation.
Un stockage de sortie durable avec des règles de rétention explicites.
Une mise à jour de statut qui n'expose pas les chemins internes ni les détails sensibles des exceptions.

Mesurez la concurrence avec des documents représentatifs avant de choisir le nombre de travailleurs. Le coût de conversion varie selon le format source, la complexité du document, les polices, les images et la cible de sortie.

Maintenir les affirmations de sécurité précises

Exécuter le convertisseur au sein de votre application .NET signifie que l'opération de conversion ne nécessite pas d'automatisation de Microsoft Office ni d'API de conversion en ligne séparée. Cela ne garantit pas automatiquement la confidentialité, la conformité, la suppression ou le chiffrement pour l'ensemble du système.

Ces propriétés dépendent de la façon dont l'application authentifie les utilisateurs, récupère les fichiers sources, configure le stockage, protège les journaux, distribue la sortie et supprime les données temporaires ou conservées.

Liste de contrôle opérationnelle

Conservez les versions de Doconut.NET8 et Doconut.NET8.Converter alignées.
Enregistrez ConverterPlugin lors de la configuration des services.
Résolvez DocumentConverter via l'injection de dépendances.
Incluez le point initial dans les extensions source du flux.
Libérez les flux source et résultat.
Utilisez l'annulation et les limites de taille de fichier au niveau de l'application.
Validez la prise en charge source‑vers‑cible au lieu de supposer que chaque paire fonctionne.
Testez la fidélité et l'utilisation des ressources avec des fichiers représentatifs.
Conservez les décisions de stockage, d'autorisation, d'audit et de rétention dans le code de l'application.

Consultez l'aperçu officiel du Plugin de conversion Doconut et la Documentation Doconut pour les informations actuelles sur le produit et l'intégration.