Serverseitige Dokumentkonvertierung in .NET mit Doconut

Einführung

Serverseitige Dokumentkonvertierung ermöglicht es einer Anwendung, eine normalisierte Ausgabe zu erzeugen, ohne Microsoft Office zu automatisieren oder die Quelle an einen separaten Online-Konvertierungsdienst zu senden. Das kann Dokumentenportale, Hintergrundjobs und kontrollierte Export-Workflows vereinfachen – doch die Host-Anwendung behält weiterhin die Zugriffskontrolle, Speicherung, Aufbewahrung, Überwachung und Bereitstellung des Ergebnisses.

Das .NET 8 Converter Plugin von Doconut stellt die Konvertierung über den dependency-injected DocumentConverter Service bereit. Dieser Leitfaden konzentriert sich auf das aktuelle Registrierungs- und API‑Modell und vermeidet die Kopplung der Konvertierung an eine Viewer‑Sitzung.

---

Passende Pakete installieren

Installieren Sie die Basis‑Viewer‑ und Konverter‑Pakete:

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

Halten Sie beide Pakete auf derselben Release‑Version. Wenn reproduzierbare Builds wichtig sind, fixieren Sie die Version in der Projektdatei oder übergeben Sie denselben --version‑Wert an beide Befehle.

Das Converter‑Plugin registrieren

Plugins werden innerhalb des AddDoconut Options‑Callbacks registriert. Es gibt keine separate AddConverter() Registrierungs‑Methode:

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

Die Anwendung muss eine Lizenz verwenden, die die Converter‑Funktionalität gewährt. Beheben Sie Start‑ und Lizenzierungsfehler, bevor Sie Konvertierungsaufgaben annehmen; verschieben Sie sie nicht in eine Hintergrundwarteschlange, wo sie schwerer zu diagnostizieren sind.

Eine Datei aus C# konvertieren

Injizieren Sie DocumentConverter in den Endpunkt oder Service, der die Konvertierungsanfrage besitzt. Der Konstruktor des Converters ist intern, sodass Anwendungs‑Code ihn nicht direkt instanziieren sollte.

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");
});

Der zurückgegebene Stream ist seekable und am Anfang positioniert. Der Aufrufer besitzt ihn und sollte ihn nach dem Kopieren oder Zurückgeben des Inhalts freigeben.

Einen hochgeladenen Stream konvertieren

Die Stream‑Überladung benötigt die Quell‑Erweiterung – einschließlich des führenden Punktes –, da der Converter sie zur Ermittlung des Quellformats verwendet:

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");
});

Behandeln Sie Dateiname und Erweiterung als nicht vertrauenswürdige Eingaben. Erzwingen Sie Upload‑Grenzwerte, validieren Sie den Quelltyp, autorisieren Sie den anfordernden Benutzer und vermeiden Sie die Verwendung des übermittelten Dateinamens als Speicherpfad.

Zielformate basierend auf tatsächlichen Fähigkeiten auswählen

Das Plugin stellt ein ConversionTarget‑Enum bereit, aber nicht jedes Quellformat kann jedes Ziel erzeugen. Eine benutzerdefinierte UI sollte nur die für die hochgeladene Quelle zulässigen Ziele anzeigen, anstatt jedes Enum‑Element darzustellen.

Bei Verwendung des optionalen Converter‑Widgets von Doconut enthält die offene Antwort allowedTargets. Nutzen Sie diese Antwort als Quelle der Wahrheit für die aktuelle Datei.

Hintergrundkonvertierung als Anwendungs‑Workflow gestalten

Der Converter kann von einem Anwendungsservice oder einem Warteschlangen‑Worker aufgerufen werden. Ein robustes Job‑Setup beinhaltet normalerweise:

1. Eine authentifizierte Anfrage, die die Quelle und das gewünschte Ziel aufzeichnet.
2. Eine Warteschlangen‑Nachricht, die eine Anwendungs‑Job‑ID enthält, nicht rohe Anmeldeinformationen.
3. Einen Worker, der die Quelle über eine autorisierte Speicher‑Abstraktion abruft.
4. Eine begrenzte Konvertierungsoperation mit Abbruch.
5. Dauerhafte Ausgabespeicherung mit expliziten Aufbewahrungsregeln.
6. Ein Status‑Update, das keine internen Pfade oder sensible Ausnahme‑Details preisgibt.

Messen Sie die Parallelität mit repräsentativen Dokumenten, bevor Sie die Anzahl der Worker festlegen. Die Konvertierungskosten variieren je nach Quellformat, Dokumentenkomplexität, Schriftarten, Bildern und Ausgabeziel.

Sicherheitsansprüche präzise halten

Der Betrieb des Converters innerhalb Ihrer .NET‑Anwendung bedeutet, dass die Konvertierungsoperation keine Microsoft‑Office‑Automatisierung oder ein separates Online‑Konvertierungs‑API erfordert. Sie garantiert jedoch nicht automatisch Datenschutz, Compliance, Löschung oder Verschlüsselung für das gesamte System.

Diese Eigenschaften hängen davon ab, wie die Anwendung Benutzer authentifiziert, Quelldateien abruft, Speicher konfiguriert, Protokolle schützt, Ausgaben verteilt und temporäre oder aufbewahrte Daten entfernt.

Operative Checkliste

• Halten Sie die Versionen von Doconut.NET8 und Doconut.NET8.Converter synchron.
• Registrieren Sie ConverterPlugin während der Service‑Konfiguration.
• Lösen Sie DocumentConverter über Dependency Injection auf.
• Fügen Sie den führenden Punkt bei Stream‑Quell‑Erweiterungen ein.
• Geben Sie Quell‑ und Ergebnis‑Streams frei.
• Verwenden Sie Abbruch und anwendungsbezogene Dateigrößen‑Grenzwerte.
• Validieren Sie die Unterstützung von Quelle‑zu‑Ziel, anstatt anzunehmen, dass jedes Paar funktioniert.
• Testen Sie Genauigkeit und Ressourcenverbrauch mit repräsentativen Dateien.
• Behalten Sie Speicher‑, Autorisierungs‑, Prüf‑ und Aufbewahrungsentscheidungen im Anwendungscode.

Siehe die offizielle Doconut Converter‑Plugin Übersicht und die Doconut Dokumentation für aktuelle Produkt‑ und Integrationsinformationen.