Server‑sidig dokumentkonvertering i .NET med Doconut

Introduktion

Server‑sidig dokumentkonvertering låter en applikation generera ett normaliserat resultat utan att automatisera Microsoft Office eller skicka källan till en separat online‑konverteringstjänst. Det kan förenkla dokumentportaler, bakgrundsjobb och kontrollerade exportarbetsflöden—men värdapplikationen behåller fortfarande åtkomstkontroll, lagring, bevarande, övervakning och leverans av resultatet.

Doconuts .NET 8 Converter‑plugin exponerar konvertering via den beroendeinjicerade DocumentConverter‑tjänsten. Denna guide fokuserar på den aktuella registreringen och API‑modellen och undviker att koppla konverteringen till en visningssession.

---

Installera matchande paket

Installera bas‑visnings- och konverteringspaketen:

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

Håll båda paketen på samma releasedatum. När reproducerbara byggen är viktiga, lås versionen i projektfilen eller skicka samma --version‑värde till båda kommandona.

Registrera Converter‑pluginet

Plugins registreras i AddDoconut‑alternativets återuppringning. Det finns ingen separat AddConverter()‑registreringsmetod:

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

Applikationen måste använda en licens som ger Converter‑funktionalitet. Lös start‑ och licensieringsfel innan konverteringsarbete accepteras; skjuta inte upp dem till en bakgrundskö där de blir svårare att diagnostisera.

Konvertera en fil från C#

Injicera DocumentConverter i den endpoint eller tjänst som äger konverteringsbegäran. Konverterarens konstruktor är intern, så applikationskod bör inte instansiera den direkt.

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

Den returnerade strömmen är sökbar och placerad i början. Anroparen äger den och bör disponera den efter kopiering eller återlämnande av innehållet.

Konvertera en uppladdad ström

Ström‑överladdningen kräver källfilens filändelse—inklusive den inledande punkten—eftersom konverteraren använder den för att identifiera källformatet:

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

Behandla filnamnet och filändelsen som opålitlig indata. Påtvinga uppladdningsgränser, validera källtypen, auktorisera den begärande användaren och undvik att använda det inskickade filnamnet som lagringssökväg.

Välj mål utifrån faktiska möjligheter

Pluginet exponerar en ConversionTarget‑enum, men inte varje källformat kan producera varje mål. Ett anpassat UI bör endast visa de mål som är tillåtna för den uppladdade källan istället för att visa varje enum‑värde.

När Doconuts valfria konverteringswidget används, innehåller dess öppna svar allowedTargets. Använd det svaret som sanningskälla för den aktuella filen.

Designa bakgrundskonvertering som ett applikationsarbetsflöde

Konverteraren kan anropas från en applikationstjänst eller en köad arbetare. Ett robust jobb innehåller normalt:

1. En autentiserad begäran som registrerar källan och önskat mål.
2. Ett kömeddelande som innehåller ett applikations‑jobb‑ID, inte råa autentiseringsuppgifter.
3. En arbetare som hämtar källan via en auktoriserad lagringsabstraktion.
4. En avgränsad konverteringsoperation med avbrott.
5. Beständig utdata‑lagring med explicita bevaranderegler.
6. En statusuppdatering som inte avslöjar interna sökvägar eller känsliga undantagsdetaljer.

Mät samtidighet med representativa dokument innan du väljer antalet arbetare. Konverteringskostnaden varierar beroende på källformat, dokumentkomplexitet, typsnitt, bilder och målformat.

Håll säkerhetsanspråk precisa

Att köra konverteraren i din .NET‑applikation innebär att konverteringsoperationen inte kräver Microsoft Office‑automation eller ett separat online‑konverterings‑API. Det garanterar inte automatiskt sekretess, efterlevnad, radering eller kryptering för hela systemet.

Dessa egenskaper beror på hur applikationen autentiserar användare, hämtar källfiler, konfigurerar lagring, skyddar loggar, distribuerar utdata och tar bort temporära eller bevarade data.

Operativ checklista

• Håll Doconut.NET8 och Doconut.NET8.Converter versioner i synk.
• Registrera ConverterPlugin under tjänstekonfiguration.
• Hämta DocumentConverter via beroendeinjicering.
• Inkludera den inledande punkten i strömmens källfiländelser.
• Disposera käll- och resultatsströmmar.
• Använd avbrott och applikationsnivå filstorleksgränser.
• Validera stöd för källa‑till‑mål istället för att anta att varje kombination fungerar.
• Testa noggrannhet och resursanvändning med representativa filer.
• Behåll beslut om lagring, auktorisation, revision och bevarande i applikationskoden.

Se den officiella Doconut Converter‑plugin‑översikten och Doconut‑dokumentation för aktuell produkt‑ och integrationsinformation.