Plugin Konverter

Plugin Converter mengubah Doconut menjadi layanan konversi dokumen. Ia menyediakan mesin di balik fasad publik DocumentConverter, dan — opsional — widget siap pakai 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 terbaru yang stabil:

dotnet add package Doconut.NET8.Converter

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

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

Jaga paket Converter pada versi yang sama dengan Doconut.NET8. ID paketnya adalah Doconut.NET8.Converter; .26.7.0 hanya muncul dalam nama file .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 tersedia dalam paket NuGet terpisah, Doconut.NET8.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 hilang, file TRIAL lama, atau lisensi non-temporer 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 dengan posisi 0, siap dibaca atau disalin segera. Dapatkan DocumentConverter dari DI di mana pun Anda membutuhkannya — ia bersifat stateless secara desain, sehingga satu instance aman untuk digunakan 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 depannya (".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 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 setiap keluarga format sumber (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, dokumen web) ke set target yang diizinkan secara tetap. Jangan menghardcode enum ini sebagai daftar target UI Anda: ?convert=open mengembalikan allowedTargets yang sebenarnya untuk file yang baru diunggah, dan itulah yang harus menjadi dasar pemilih.

Widget siap pakai

Endpoint ?convert=open|run|download pada widget bersifat opsional dan dinonaktifkan secara default — aman secara default. Aktifkan mereka 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(), tiga endpoint ?convert= menjawab 404 — tetapi file JS tetap disajikan (itu adalah sumber daya statis yang disematkan; hanya endpoint yang diakses yang dibatasi). AddConverterWidget() tetap memerlukan plugin Converter terdaftar dan lisensi yang memberikan Converter — ia tidak memberikan hak konversi secara mandiri.

Sesuaikan widget

Opsi inisialisasi yang diteruskan ke Doconut.convert(selector, options):

Panggilan balik:

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 terhadapnya 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 file harus dibuka kembali. Hasil konversi berada di stash 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 stash.

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

Mode kegagalan, dikelompokkan per rute:

Kepemilikan sumber daya

Konverter mengembalikan MemoryStream yang dapat dicari dengan posisi nol. Pemanggil memiliki stream tersebut dan harus membuangnya setelah menyalin atau mengembalikan isinya. Layanan DocumentConverter sendiri bersifat stateless dan diperoleh dari dependency injection; jangan membuat atau membuang layanan secara manual.

Untuk widget web, stash unggahan dan unduhan memiliki TTL 30 menit yang independen. resultToken penampil mengikuti masa hidup sesi penampil. Menutup hasil penampil tidak menghapus stash unduhan yang masih valid, dan mereset widget browser tidak memperpanjang TTL keduanya.

Pemecahan Masalah

Penandaan Watermark

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 lisensi IsViewerLicensed dan IsTemporary, dan handler widget ?convert=run melakukan pemeriksaan setara (IsViewerLicensed && !IsTrial && !IsTemporary) untuk mengisi field watermarked yang dikembalikannya. Integrasi dapat dibangun dan diuji end‑to‑end dengan lisensi evaluasi sebelum pembelian — hanya byte output yang berubah.