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 Kontrolle über Zugriff, Speicherung, Aufbewahrung, Überwachung und Auslieferung des Ergebnisses.

Doconut's .NET 8 Converter Plugin stellt die Konvertierung über den dependency‑injectierten DocumentConverter‑Service bereit. Dieser Leitfaden konzentriert sich auf die aktuelle Registrierung und das API‑Modell und vermeidet eine Kopplung der Konvertierung an eine Viewer‑Sitzung.

---

Passende Pakete installieren

Installieren Sie die Basis‑Viewer‑ und Converter‑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, pinnen 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()‑Registrierungsmethode:

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

Die Anwendung muss eine Lizenz verwenden, die die Converter‑Funktionalität freischaltet. 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 verarbeitet. Der Konstruktor des Converters ist intern, daher sollte Anwendungscode ihn nicht direkt instanziieren.

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 seek‑fähig 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 – inklusive des führenden Punkts – weil der Converter diese 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 unzuverlässige Eingaben. Erzwingen Sie Upload‑Grenzwerte, validieren Sie den Quelltyp, autorisieren Sie den anfragenden Benutzer und vermeiden Sie die Verwendung des übermittelten Dateinamens als Speicherpfad.

Zielformate anhand tatsächlicher 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 zu listen.

Wenn Sie das optionale Converter‑Widget von Doconut verwenden, enthält die offene Antwort allowedTargets. Nutzen Sie diese Antwort als Quelle der Wahrheit für die aktuelle Datei.

Hintergrundkonvertierung als Anwendungs‑Workflow entwerfen

Der Converter kann aus einem Anwendungs‑Service oder einem Warteschlangen‑Worker aufgerufen werden. Ein robustes Job‑Setup umfasst typischerweise:

1. Eine authentifizierte Anfrage, die Quelle und gewünschtes Ziel protokolliert.
2. Eine Warteschlangen‑Nachricht, die eine Anwendungs‑Job‑ID enthält, nicht rohe Anmeldedaten.
3. Einen Worker, der die Quelle über eine autorisierte Speicher‑Abstraktion abruft.
4. Einen begrenzten Konvertierungsvorgang mit Abbruch‑Möglichkeit.
5. Dauerhafte Ausgabespeicherung mit expliziten Aufbewahrungsregeln.
6. Ein Status‑Update, das interne Pfade oder sensible Ausnahme‑Details nicht preisgibt.

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

Sicherheitsansprüche präzise halten

Den Converter innerhalb Ihrer .NET‑Anwendung auszuführen bedeutet, dass der Konvertierungsvorgang keine Microsoft‑Office‑Automatisierung oder ein separates Online‑Konvertierungs‑API benötigt. Das garantiert jedoch nicht automatisch Privatsphäre, Compliance, Löschung oder Verschlüsselung für das Gesamtsystem.

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

Operative Checkliste

• Halten Sie Doconut.NET8‑ und Doconut.NET8.Converter‑Versionen 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.
• Nutzen Sie Abbruch‑Mechanismen und anwendungsseitige Dateigrößen‑Grenzwerte.
• Validieren Sie die Unterstützung von Quelle‑zu‑Ziel‑Kombinationen, anstatt jede Paarung anzunehmen.
• Testen Sie Treue und Ressourcenverbrauch mit repräsentativen Dateien.
• Behalten Sie Entscheidungen zu Speicherung, Autorisierung, Auditing und Aufbewahrung im Anwendungscode.

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