Server-Side konverze dokumentů v .NET s Doconut

Úvod

Server-side konverze dokumentů umožňuje aplikaci vytvořit normalizovaný výstup bez automatizace Microsoft Office nebo odesílání zdroje na samostatnou online konverzní službu. 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.

Plugin .NET 8 Converter od Doconutu zpřístupňuje konverzi prostřednictvím dependency‑injected služby DocumentConverter. Tento průvodce se zaměřuje na aktuální registraci a model API a vyhýbá se propojení konverze se seancí prohlížeče.

---

Instalace odpovídajících balíčků

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 na 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.

Registrace pluginu Converter

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

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

Aplikace musí používat licenci, která poskytuje schopnost Converter. Vyřešte chyby při spouštění a licencování před přijetím konverzní práce; neodkládejte je do fronty na pozadí, kde se obtížněji diagnostikují.

Konverze souboru z C#

Injektujte DocumentConverter do koncového bodu nebo služby, která vlastní požadavek na konverzi. Konstruktor konvertoru je interní, takže aplikační kód 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.

Konverze nahraného streamu

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

Považujte název souboru a příponu za nedůvěryhodný vstup. Vynucujte limity nahrávání, ověřujte typ zdroje, autorizujte požadujícího uživatele a vyhněte se používání odeslaného názvu souboru jako cesty úložiště.

Výběr cílů podle skutečných možností

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

Při používání volitelného widgetu konvertoru od Doconutu obsahuje jeho otevřená odpověď allowedTargets. Použijte tuto odpověď jako pravdivý zdroj pro aktuální soubor.

Návrh konverze na pozadí jako aplikační workflow

Konvertor může být volán z aplikační služby 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 aplikační úlohy, nikoli surové přihlašovací údaje.
3. Pracovníka, který získá zdroj prostřednictvím autorizované abstrakce ú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.

Změř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 výstupního cíle.

Udržujte bezpečnostní tvrzení přesná

Spuštění konvertoru uvnitř vaší .NET aplikace znamená, že konverzní operace nevyžaduje automatizaci Microsoft Office ani samostatné online API pro konverzi. Automaticky nezaručuje soukromí, soulad, mazání ani š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á nebo archivovaná data.

Provozní kontrolní seznam

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

Viz oficiální Plugin Doconut Converter přehled a Dokumentace Doconut pro aktuální informace o produktu a integraci.