Plugin Konverter

Plugin Converter mengubah Doconut menjadi layanan konversi dokumen. Ia menyediakan mesin di balik fasad publik DocumentConverter, dan — opsional — widget drop-in dengan kontrak HTTP‑nya sendiri, sehingga Anda dapat mengonversi dokumen dari C#, dari widget, atau dari frontend yang Anda buat sendiri.

Instal paket

Instal plugin Converter stabil terbaru:

dotnet add package Doconut.NET6.Converter

Untuk mengunci plugin ke rilis 26.7.0 saat ini, berikan versi secara terpisah:

dotnet add package Doconut.NET6.Converter --version 26.7.0

Pertahankan paket Converter pada versi yang sama dengan Doconut.NET6. ID paketnya adalah Doconut.NET6.Converter; .26.7.0 muncul hanya di nama berkas .nupkg yang diunduh.

Daftarkan plugin

Tidak ada metode AddConverter() — model plugin Doconut seragam. Setiap plugin, termasuk Converter, didaftarkan dengan cara yang sama: panggil AddPlugin<TPlugin>() di dalam AddDoconut(). ConverterPlugin dikirim dalam paket NuGet terpisah, Doconut.NET6.Converter, yang dipasang bersamaan dengan paket penampil dasar.

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

Panggilan ini melempar pengecualian saat startup bila lisensi tidak ada, berkas legacy TRIAL, atau lisensi non‑sementara yang tidak memberikan kemampuan Converter — sebuah InvalidOperationException yang dihasilkan dari dalam AddDoconut(), sebelum aplikasi melayani permintaan. Registrasi Demo/NFR sementara diterima; setelah masa berlakunya berakhir, konversi tetap tersedia dengan output berwatermark. Tidak ada tingkatan gratis yang diam. Lihat Pengaturan Lisensi untuk cara memuat lisensi.

Konversi dari C#

Setiap konversi mengembalikan MemoryStream yang dapat dicari, diposisikan pada 0, siap dibaca atau disalin segera. Resolusi DocumentConverter dari DI di mana pun Anda membutuhkannya — layanan ini tidak menyimpan keadaan, sehingga satu instance aman dipakai kembali di seluruh permintaan.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Dua detail yang mudah keliru: sourceExtension pada overload stream harus menyertakan titik di depan (".xlsx", bukan "xlsx" ) — konverter mencocokkannya dengan katalog format dan ekstensi tanpa titik tidak akan terpecahkan. Dan meskipun namanya, WordToHtmlAsync mengembalikan Task<Stream>, bukan Task<string> — Anda mendapatkan dokumen HTML (gambar tersemat sebagai Base64) sebagai stream, sama seperti setiap hasil konversi lainnya.

Format target

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Tidak setiap sumber dapat dikonversi ke setiap target — plugin memetakan keluarga format sumber (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, web document) ke sekumpulan target yang diizinkan. Jangan meng‑hardcode enum ini sebagai daftar target UI Anda: ?convert=open mengembalikan allowedTargets yang sebenarnya untuk berkas yang baru saja diunggah, dan itulah yang harus menggerakkan pemilih.

Widget drop-in

Endpoint widget ?convert=open|run|download bersifat opsional dan dinonaktifkan secara default — aman secara bawaan. Aktifkan di sisi server, bersamaan dengan pendaftaran plugin:

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

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Tanpa AddConverterWidget(), ketiga endpoint ?convert= menjawab 404 — namun berkas JS tetap disajikan (itu adalah sumber daya statis tersemat; hanya endpoint yang dibicarakannya yang dibatasi). AddConverterWidget() tetap memerlukan plugin Converter terdaftar dan lisensi yang memberikan Converter — lisensi tersebut tidak secara otomatis memberikan hak konversi.

Sesuaikan widget

Inisialisasi opsi yang diteruskan ke Doconut.convert(selector, options):

Callback:

Doconut.convert() mengembalikan instance widget itu sendiri — simpan untuk mengendalikan widget secara programatik:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // kembali ke layar idle/drop; tidak memicu onReady lagi
conv.loadFile(file);  // memulai alur dengan objek File; tidak melakukan apa‑apa kecuali sedang idle
conv.destroy();       // menghapus listener, mengosongkan mount; instance tidak dapat dipakai lagi setelah ini

Bangun frontend Anda sendiri

Widget hanyalah klien untuk kontrak HTTP ini — bangun frontend Anda sendiri langsung melawannya untuk UX yang berbeda. Ketiga rute berada di bawah cabang ASP.NET tempat UseDoconut() dipasang (biasanya /doconut):

Byte sumber yang diunggah disimpan di sisi server dengan TTL 30 menit; setelah jendela itu berakhir, run menjawab 404 dan berkas harus dibuka kembali. Hasil konversi hidup di penyimpanan yang sama — downloadToken mendapatkan jendela 30 menit baru saat konversi selesai — sementara resultToken adalah token sesi penampil biasa yang masa berlakunya mengikuti cache sesi penampil, terlepas dari penyimpanan.

sourceExt dalam respons open tidak memiliki titik di depan (mis. "docx") — kebalikan dari konvensi parameter sourceExtension pada DocumentConverter.ConvertAsync, yang memerlukannya.

Mode kegagalan, dikelompokkan per rute

Kepemilikan sumber daya

Konverter mengembalikan MemoryStream yang dapat dicari, diposisikan pada nol. Pemanggil memiliki stream tersebut dan harus membuangnya setelah menyalin atau mengembalikan isinya. Layanan DocumentConverter sendiri tidak menyimpan keadaan dan di‑resolve dari dependency injection; jangan membuat atau membuang layanan secara manual.

Untuk widget web, penyimpanan unggahan dan unduhan memiliki TTL 30 menit yang independen. Token resultToken penampil mengikuti masa hidup sesi penampil. Menutup hasil penampil tidak menghapus penyimpanan unduhan yang masih berlaku, dan mereset widget di browser tidak memperpanjang TTL mana pun.

Pemecahan Masalah

Penandaan Air

Dengan ConverterPlugin terdaftar, lisensi host berada dalam salah satu dari tiga keadaan:

Kedua jalur panggilan menghitung flag dari aturan yang sama: fasad C# DocumentConverter menurunkannya secara internal dari status IsViewerLicensed dan IsTemporary pada lisensi, dan handler widget ?convert=run melakukan pemeriksaan setara (IsViewerLicensed && !IsTrial && !IsTemporary) untuk mengisi bidang watermarked yang dikembalikannya. Integrasi dapat dibangun dan diuji end‑to‑end dengan lisensi evaluasi sebelum pembelian — hanya byte output yang berubah.