Server‑sidig dokumentkonvertering i .NET med Doconut

Introduktion

Server‑sidig dokumentkonvertering låter en applikation generera en normaliserad utdata utan att automatisera Microsoft Office eller skicka källan till en separat on‑line konverteringstjänst. Det kan förenkla dokumentportaler, bakgrundsjobb och kontrollerade exportarbetsflöden – men värdapplikationen äger 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 konvertering 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 konverterings‑pluginet

Plugins registreras i AddDoconut‑alternativ‑callbacken. Det finns ingen separat AddConverter()‑registreringsmetod:

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

Applikationen måste använda en licens som ger konverteringskapacitet. Lös uppstart‑ och licensieringsfel innan du accepterar konverteringsarbete; 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 avyttra den efter kopiering eller återgivning av innehållet.

Konvertera en uppladdad ström

Ströms‑overloaden kräver källfilens filändelse – inklusive den inledande punkten – eftersom konverteraren använder den för att avgöra 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 lagringsvä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 bara visa de mål som är tillåtna för den uppladdade källan istället för att lista varje enum‑värde.

När du använder Doconuts valfria konverteringswidget, 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 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‑job‑ID, inte råa referenser.
3. En arbetare som hämtar källan via en auktoriserad lagringsabstraktion.
4. En avgränsad konverteringsoperation med avbrytning.
5. Hållbar lagring av utdata med explicita bevaranderegler.
6. En statusuppdatering som inte exponerar interna sökvägar eller känsliga undantagsdetaljer.

Mät samtidighet med representativa dokument innan du bestämmer 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 betyder att konverteringsoperationen inte kräver Microsoft Office‑automation eller ett separat on‑line konverterings‑API. Det garanterar inte automatiskt sekretess, regelefterlevnad, 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‑versionerna i linje.
• Registrera ConverterPlugin under service‑konfigurationen.
• Hämta DocumentConverter via beroendeinjektion.
• Inkludera den inledande punkten i strömmens källfiländelser.
• Avyttra käll‑ och resultatströmmar.
• Använd avbrytning och applikations‑nivå fil‑storleksgrä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 lagring, auktorisation, revision och bevarandebeslut i applikationskoden.

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