Plugin Konverter

Plugin Converter mengubah Doconut menjadi layanan konversi dokumen. Ia menyumbangkan mesin di balik antarmuka 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 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

Pertahankan 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 dikirim dalam paket NuGet-nya sendiri, Doconut.NET8.Converter, diinstal 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 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 untuk 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.

// Suntikkan 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 adalah 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

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 apa pun yang baru saja diunggah, dan itulah yang seharusnya menggerakkan pemilih.

Widget yang dapat disisipkan

Endpoint ?convert=open|run|download widget bersifat opt‑in dan dinonaktifkan secara default — aman secara bawaan. 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 — namun file JS itu tetap disajikan (itu adalah sumber daya statis yang disematkan; hanya endpoint yang diakses yang dibatasi). AddConverterWidget() masih memerlukan plugin Converter untuk didaftarkan dan lisensi yang memberikan Converter — lisensi tersebut tidak memberikan hak konversi secara mandiri.

Sesuaikan widget

Opsi inisialisasi yang diberikan 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 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 frontend Anda sendiri

Widget ini hanyalah klien untuk kontrak HTTP ini — bangun frontend Anda sendiri secara langsung di atasnya untuk pengalaman pengguna (UX) yang berbeda. Ketiga rute tersebut 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 dalam stash yang sama — downloadToken mendapatkan jendela 30 menit baru ketika 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 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 diresolusikan dari dependency injection; jangan membangun atau membuang layanan secara manual.

Untuk widget web, stash unggah dan unduh memiliki TTL independen selama 30 menit. Sebuah resultToken viewer mengikuti masa hidup sesi viewer sebagai gantinya. Menutup hasil viewer tidak menghapus stash unduhan yang masih valid, 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 lisensi, dan penangan ?convert=run widget melakukan pemeriksaan setara (IsViewerLicensed && !IsTrial && !IsTemporary) untuk mengisi bidang watermarked yang dikembalikannya. Integrasi dapat dibangun dan diuji secara end-to-end pada lisensi evaluasi sebelum pembelian — hanya byte output yang berubah.