Plugin Konverter

Plugin Konverter mengubah Doconut menjadi layanan konversi dokumen. Ia menyediakan mesin di balik antarmuka publik DocumentConverter, dan — opsional — widget yang dapat langsung dipasang 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 Konverter stabil terbaru:

dotnet add package Doconut.NETStandard.Converter

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

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

Pertahankan paket Konverter pada versi yang sama dengan Doconut.NETStandard. ID paketnya adalah Doconut.NETStandard.Converter; .26.8.0 hanya muncul dalam nama file .nupkg yang diunduh.

Daftarkan plugin

Tidak ada metode AddConverter() — model plugin Doconut seragam. Setiap plugin, termasuk Konverter, didaftarkan dengan cara yang sama: panggil AddPlugin<TPlugin>() di dalam AddDoconut(). ConverterPlugin dikirim dalam paket NuGet-nya sendiri, Doconut.NETStandard.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 kesalahan saat startup karena lisensi yang hilang, file legacy TRIAL, atau lisensi non‑temporer yang tidak memberikan kemampuan Converter — sebuah InvalidOperationException yang diangkat dari dalam AddDoconut(), sebelum aplikasi melayani permintaan. Registrasi Demo/NFR sementara diterima; setelah masa berlakunya berakhir, konversi tetap tersedia dengan output berwatermark. Tidak ada tingkat 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 tidak memiliki status secara desain, sehingga satu instance aman untuk digunakan kembali di seluruh permintaan.

viewer.Converter.GetConverter() tidak ada di sini. Konversi tidak lagi diakses melalui instance penampil: injeksikan Doconut.DocumentConverter sebagai gantinya.

// Suntik DocumentConverter; konstruktornya internal, jadi jangan pernah `new` itu.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension mencakup titik di depannya. password bernilai null kecuali dokumen dilindungi.
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

ConversionTarget (namespace Doconut.Configs.Conversion) memiliki 45 anggota:

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

Enum ini mencakup setiap keluarga sumber. Perpustakaan sebelumnya memiliki tipe *ConfigConverter per keluarga — WordConfigConverter, ExcelConfigConverter, dan seterusnya — masing‑masing dengan enum EnTargetFormat bersarang, plus enum SourceFormatConverter untuk input. Semua itu sudah tidak ada; lihat panduan migrasi.

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 apa pun yang baru saja diunggah, dan itulah yang harus menjadi dasar pemilih.

Widget Sisip

Titik akhir ?convert=open|run|download widget bersifat opt‑in dan dinonaktifkan secara bawaan — 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 titik akhir ?convert= menjawab 404 — tetapi berkas JS itu tetap disajikan (ini adalah sumber daya statis tertanam biasa; hanya titik akhir yang diakses yang dibatasi). AddConverterWidget() masih memerlukan plugin Converter terdaftar dan lisensi yang memberikan Converter — lisensi tersebut 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 ulang onReady
conv.loadFile(file);  // memulai alur dengan objek File; no-op kecuali sedang idle
conv.destroy();       // menghapus listener, mengosongkan mount; instance tidak dapat digunakan setelah ini

Bangun antarmuka depan Anda sendiri

Widget hanyalah klien untuk kontrak HTTP ini — bangun antarmuka depan Anda sendiri langsung di atasnya untuk pengalaman pengguna 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 berada di stash yang sama — downloadToken mendapatkan jendela 30 menit baru ketika konversi selesai — sementara resultToken adalah token sesi viewer biasa yang masa berlakunya mengikuti cache sesi viewer, terlepas dari stash.

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

Mode kegagalan, dikelompokkan per rute:

Kepemilikan Sumber Daya

Konverter mengembalikan sebuah MemoryStream yang dapat dicari yang diposisikan pada nol. Pemanggil memiliki aliran tersebut dan harus membuangnya setelah menyalin atau mengembalikan isinya. Layanan DocumentConverter itu sendiri tidak memiliki status dan diambil dari dependency injection; jangan membuat atau membuang layanan secara manual.

Untuk widget web, penyimpanan unggah dan unduh memiliki TTL terpisah masing-masing 30 menit. Sebuah resultToken penampil mengikuti masa hidup sesi penampil sebagai gantinya. Menutup hasil penampil tidak menghapus penyimpanan unduhan yang masih berlaku, dan mereset widget peramban tidak memperpanjang TTL keduanya.

Pemecahan Masalah

Penandaan Air

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

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