Plugin Konverter

Plugin Konverter mengubah Doconut menjadi layanan konversi dokumen. Ia menyumbangkan 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 tulis sendiri.

Instal paket

Instal plugin Konverter 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 Konverter pada versi yang sama dengan Doconut.NET6. ID paketnya adalah Doconut.NET6.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 Konverter, didaftarkan dengan cara yang sama: panggil AddPlugin<TPlugin>() di dalam AddDoconut(). ConverterPlugin dikirim dalam paket NuGet-nya sendiri, 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 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 kedaluwarsa kalendernya, konversi tetap tersedia dengan output berwatermark. Tidak ada tingkatan gratis yang diam-diam. Lihat Pengaturan Lisensi untuk cara memuat lisensi.

Konversi dari C#

Setiap konversi mengembalikan MemoryStream yang dapat dicari dan diposisikan pada 0, siap dibaca atau disalin segera. Dapatkan DocumentConverter dari DI di mana pun Anda membutuhkannya — ia bersifat tanpa status secara desain, sehingga satu instance aman untuk digunakan kembali di seluruh permintaan.

// Suntikkan DocumentConverter; konstruktornya bersifat 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

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 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, bersama 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 itu tetap disajikan terlepas dari itu (itu adalah sumber daya statis tertanam biasa; 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 diteruskan ke Doconut.convert(selector, options):

Callback:

Doconut.convert() mengembalikan instance widget itu sendiri — simpanlah 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 saat ini idle
conv.destroy();       // menghapus listeners, mengosongkan mount; instance tidak dapat digunakan setelah ini

Bangun frontend Anda sendiri

Widget hanyalah klien untuk kontrak HTTP ini — bangun frontend Anda sendiri langsung di atasnya untuk UX yang berbeda. Semua tiga 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 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 (mis. "docx") — konvensi yang berlawanan dengan parameter sourceExtension pada DocumentConverter.ConvertAsync, yang memerlukannya.

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 sendiri bersifat stateless dan diambil melalui dependency injection; jangan membuat atau membuang layanan secara manual.

Untuk widget web, penyimpanan unggah dan unduh memiliki TTL masing-masing selama 30 menit. Sebuah resultToken viewer mengikuti masa hidup sesi viewer sebagai gantinya. Menutup hasil viewer 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: facade C# DocumentConverter menurunkannya secara internal dari keadaan IsViewerLicensed dan IsTemporary pada lisensi, dan handler ?convert=run pada widget melakukan pemeriksaan setara (IsViewerLicensed && !IsTrial && !IsTemporary) untuk mengisi bidang watermarked yang dikembalikannya. Integrasi dapat dibangun dan diuji end-to-end pada lisensi evaluasi sebelum pembelian — hanya byte output yang berubah.