Server‑Side převod dokumentů v .NET s Doconut

Úvod

Server‑side převod dokumentů umožňuje aplikaci vytvořit normalizovaný výstup bez automatizace Microsoft Office nebo odesílání zdroje do samostatné online konverzní služby. To může zjednodušit dokumentové portály, úlohy na pozadí a řízené exportní workflow – ale hostitelská aplikace si stále zachovává kontrolu přístupu, úložiště, archivaci, monitorování a doručení výsledku.

Doconut .NET 8 Converter Plugin vystavuje konverzi přes dependency‑injected službu DocumentConverter. Tento průvodce se soustředí na aktuální registraci a model API a vyhýbá se propojení konverze s relací prohlížeče.

---

Nainstalujte odpovídající balíčky

Nainstalujte základní balíčky pro prohlížeč a konvertor:

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

Udržujte oba balíčky ve stejné verzi vydání. Když jsou důležité reprodukovatelné sestavení, připněte verzi v souboru projektu nebo předávejte stejnou hodnotu --version oběma příkazům.

Zaregistrujte plugin konvertoru

Pluginy se registrují uvnitř callbacku AddDoconut v nastavení. Neexistuje samostatná metoda registrace AddConverter():

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

Aplikace musí používat licenci, která poskytuje schopnost konvertoru. Vyřešte chyby při spouštění a licencování dříve, než přijmete konverzní úlohu; neodkládejte je do fronty na pozadí, kde jsou obtížněji diagnostikovatelné.

Převod souboru z C#

Vložte DocumentConverter do koncového bodu nebo služby, která vlastní požadavek na konverzi. Konstruktor konvertoru je interní, takže kód aplikace by jej neměl vytvářet přímo.

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

Vrácený stream je seekable a je nastaven na začátek. Volající jej vlastní a měl by jej uvolnit po zkopírování nebo vrácení obsahu.

Převod nahraného proudu

Přetížení pro stream vyžaduje příponu zdroje – včetně úvodní tečky – protože konvertor ji používá k určení formátu zdroje:

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

Zacházejte s názvem souboru a příponou jako s nedůvěryhodným vstupem. Vynucujte limity nahrávání, ověřujte typ zdroje, autorizujte uživatele a nepoužívejte předložený název souboru jako cestu k úložišti.

Vyberte cíle podle skutečných možností

Plugin vystavuje výčet ConversionTarget, ale ne každý formát zdroje může vytvořit každý cíl. Vlastní UI by mělo zobrazovat jen cíle povolené pro nahraný zdroj místo všech hodnot výčtu.

Při použití volitelného widgetu konvertoru Doconut zahrnuje jeho otevřená odpověď allowedTargets. Použijte tuto odpověď jako pravdivý zdroj pro aktuální soubor.

Navrhněte konverzi na pozadí jako workflow aplikace

Konvertor může být volán ze služby aplikace nebo z fronty pracovníka. Robustní úloha obvykle zahrnuje:

1. Autentizovaný požadavek, který zaznamená zdroj a požadovaný cíl.
2. Zprávu ve frontě obsahující ID úlohy aplikace, ne surové přihlašovací údaje.
3. Worker, který získá zdroj přes autorizovanou abstrakci úložiště.
4. Omezenou konverzní operaci s možností zrušení.
5. Trvalé úložiště výstupu s explicitními pravidly archivace.
6. Aktualizaci stavu, která neodhaluje interní cesty ani citlivé podrobnosti výjimek.

Měřte souběžnost pomocí reprezentativních dokumentů před výběrem počtu pracovníků. Náklady na konverzi se liší podle formátu zdroje, složitosti dokumentu, fontů, obrázků a cílového výstupu.

Udržujte bezpečnostní nároky přesné

Spuštění konvertoru uvnitř vaší .NET aplikace znamená, že konverzní operace nevyžaduje automatizaci Microsoft Office ani samostatné online konverzní API. Automaticky to neznamená záruku soukromí, shody, mazání nebo šifrování pro celý systém.

Tyto vlastnosti závisí na tom, jak aplikace autentizuje uživatele, získává zdrojové soubory, konfiguruje úložiště, chrání logy, distribuuje výstup a odstraňuje dočasná či archivovaná data.

Provozní kontrolní seznam

• Udržujte verze Doconut.NET8 a Doconut.NET8.Converter v souladu.
• Zaregistrujte ConverterPlugin během konfigurace služeb.
• Získejte DocumentConverter pomocí dependency injection.
• Zahrňte úvodní tečku v příponách zdrojových proudů.
• Uvolněte zdrojové a výsledné proudy.
• Používejte zrušení a omezení velikosti souboru na úrovni aplikace.
• Ověřte podporu zdroj‑cíl místo předpokladu, že každá kombinace funguje.
• Testujte věrnost a využití zdrojů s reprezentativními soubory.
• Uchovávejte rozhodnutí o úložišti, autorizaci, auditu a archivaci v kódu aplikace.

Viz oficiální přehled Doconut konvertor plugin a Doconut dokumentace pro aktuální informace o produktu a integraci.