Konversi Dokumen Sisi Server di .NET dengan Doconut

Pendahuluan

Konversi dokumen sisi server memungkinkan sebuah aplikasi menghasilkan output yang terstandardisasi tanpa mengotomatisasi Microsoft Office atau mengirim sumber ke layanan konversi online terpisah. Hal ini dapat menyederhanakan portal dokumen, pekerjaan latar belakang, dan alur kerja ekspor yang terkontrol—tetapi aplikasi host tetap mengendalikan kontrol akses, penyimpanan, retensi, pemantauan, dan pengiriman hasil.

Plugin .NET 8 Converter milik Doconut menyediakan konversi melalui layanan DocumentConverter yang di‑dependency‑injected. Panduan ini berfokus pada pendaftaran dan model API saat ini serta menghindari penggabungan konversi dengan sesi penampil.

---

Pasang paket yang cocok

Pasang paket penampil dasar dan konverter:

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

Pastikan kedua paket berada pada versi rilis yang sama. Ketika build yang dapat direproduksi penting, kunci versi di file proyek atau berikan nilai --version yang sama pada kedua perintah.

Daftarkan Plugin Converter

Plugin didaftarkan di dalam callback opsi AddDoconut. Tidak ada metode pendaftaran terpisah AddConverter():

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

Aplikasi harus menggunakan lisensi yang memberikan kemampuan Converter. Selesaikan kesalahan startup dan lisensi sebelum menerima pekerjaan konversi; jangan menunda mereka ke antrian latar belakang yang membuatnya lebih sulit didiagnosis.

Konversi file dari C#

Suntikkan DocumentConverter ke dalam endpoint atau layanan yang menangani permintaan konversi. Konstruktor converter bersifat internal, sehingga kode aplikasi tidak boleh menginstansiasinya secara langsung.

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

Stream yang dikembalikan dapat di‑seek dan berada pada posisi awal. Pemanggil memiliki stream tersebut dan harus membuangnya setelah menyalin atau mengembalikan kontennya.

Konversi aliran yang diunggah

Overload stream memerlukan ekstensi sumber—termasuk titik di depannya—karena converter menggunakannya untuk menentukan format sumber:

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

Anggap nama file dan ekstensi sebagai input yang tidak dipercaya. Terapkan batas unggahan, validasi tipe sumber, otorisasi pengguna yang meminta, dan hindari penggunaan nama file yang dikirim sebagai jalur penyimpanan.

Pilih target berdasarkan kemampuan sebenarnya

Plugin menampilkan enum ConversionTarget, namun tidak setiap format sumber dapat menghasilkan setiap target. UI kustom sebaiknya hanya menampilkan target yang diizinkan untuk sumber yang diunggah, bukan semua nilai enum.

Saat menggunakan widget converter opsional Doconut, respons terbukanya mencakup allowedTargets. Gunakan respons tersebut sebagai sumber kebenaran untuk file saat ini.

Rancang konversi latar belakang sebagai alur kerja aplikasi

Converter dapat dipanggil dari layanan aplikasi atau pekerja yang di‑queue. Pekerjaan yang kuat biasanya mencakup:

1. Permintaan yang terautentikasi yang mencatat sumber dan target yang diinginkan.
2. Pesan antrian yang berisi ID pekerjaan aplikasi, bukan kredensial mentah.
3. Pekerja yang mengambil sumber melalui abstraksi penyimpanan yang berotorisasi.
4. Operasi konversi terbatas dengan pembatalan.
5. Penyimpanan output yang tahan lama dengan aturan retensi yang eksplisit.
6. Pembaruan status yang tidak mengungkap jalur internal atau detail pengecualian sensitif.

Ukur tingkat konkruensi dengan dokumen representatif sebelum memilih jumlah pekerja. Biaya konversi bervariasi tergantung format sumber, kompleksitas dokumen, font, gambar, dan target output.

Jaga klaim keamanan tetap tepat

Menjalankan converter di dalam aplikasi .NET Anda berarti operasi konversi tidak memerlukan otomasi Microsoft Office atau API konversi online terpisah. Hal ini tidak secara otomatis menjamin privasi, kepatuhan, penghapusan, atau enkripsi untuk seluruh sistem.

Properti tersebut bergantung pada cara aplikasi mengautentikasi pengguna, mengambil file sumber, mengonfigurasi penyimpanan, melindungi log, mendistribusikan output, dan menghapus data sementara atau yang disimpan.

Daftar periksa operasional

• Pastikan versi Doconut.NET8 dan Doconut.NET8.Converter selaras.
• Daftarkan ConverterPlugin selama konfigurasi layanan.
• Dapatkan DocumentConverter melalui dependency injection.
• Sertakan titik di depan pada ekstensi sumber aliran.
• Buang aliran sumber dan hasil.
• Gunakan pembatalan dan batas ukuran file tingkat aplikasi.
• Validasi dukungan sumber‑ke‑target alih‑alih mengasumsikan setiap pasangan berfungsi.
• Uji kesetiaan dan penggunaan sumber daya dengan file representatif.
• Simpan keputusan penyimpanan, otorisasi, audit, dan retensi dalam kode aplikasi.

Lihat ikhtisar resmi Plugin Converter Doconut dan dokumentasi Doconut untuk informasi produk dan integrasi terkini.