Daftarkan dan aktifkan widget konverter drop‑in Doconut di .NET 8

Widget drop‑in adalah UI siap pakai Doconut untuk mengunggah file, menjalankan konversi, dan mengunduh hasil.
Secara default tiga endpoint ?convert= widget mengembalikan 404; mereka menjadi aktif hanya ketika Anda mendaftarkan plugin Konverter dan memanggil AddConverterWidget() pada DoconutOptions.

Berikut adalah konfigurasi startup lengkap yang siap disalin dan memenuhi kedua persyaratan.

---

1. Prasyarat – lisensi dan dukungan sesi

• Lisensi – Plugin Konverter memerlukan lisensi yang memberikan kemampuan Converter. Letakkan file (misalnya, Doconut.Viewer.lic) di lokasi yang dapat dijangkau oleh aplikasi dan arahkan DoconutOptions.LicensePath ke sana.
• Status sesi – Model keamanan Doconut menyimpan token sesi dokumen di sesi ASP.NET Core. Tambahkan cache terdistribusi dan AddSession() sebelum middleware dihubungkan.

builder.Services.AddDistributedMemoryCache();   // diperlukan untuk sesi
builder.Services.AddSession();                  // mengaktifkan sesi berbasis IDistributedCache

---

2. Daftarkan layanan inti Doconut

AddDoconut() adalah titik masuk tunggal yang menyuntikkan penampil, layanan lisensi, dan registri plugin.

builder.Services.AddDoconut(options =>
{
    // Beritahu Doconut di mana menemukan file lisensi.
    options.LicensePath = "Doconut.Viewer.lic";

    // Daftarkan plugin Converter – ini juga memvalidasi kemampuan lisensi.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Jika lisensi tidak mencakup kemampuan Converter, panggilan di atas akan melempar InvalidOperationException dan aplikasi tidak akan berjalan. Perilaku gagal cepat ini mencegah Anda menyebarkan build yang tidak berlisensi dengan benar.

---

3. Aktifkan widget dengan AddConverterWidget

Widget bersifat opt‑in. Memanggil AddConverterWidget() mendaftarkan tiga endpoint konversi (?convert=open, ?convert=run, ?convert=download) dan menghubungkan sejumlah kecil konfigurasi sisi klien (ukuran unggah maksimum, jalur dasar, dll.).

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

    // Aktifkan UI drop‑in dan atur batas unggah sisi klien.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // prapemeriksaan klien; server menegakkan batasnya sendiri
    });
});

Hanya panggilan AddConverterWidget yang membuat endpoint; file JavaScript statis (doconutConverter.js) selalu disajikan sebagai sumber daya tersemat, tetapi akan gagal menghubungi server jika endpoint tidak ada.

---

4. Hubungkan middleware dalam urutan yang tepat

Middleware yang menyajikan aset statis (UseDoconutResources) harus dijalankan sebelum middleware penampil terminal (UseDoconut). Middleware sesi juga perlu ditempatkan lebih awal karena Doconut memvalidasi sesi pada setiap permintaan.

app.UseSession();           // harus mendahului UseDoconut()
app.UseDoconutResources();  // menyajikan JS, CSS, gambar
app.UseDoconut();           // menangani ?convert= dan permintaan halaman dokumen

Dengan pipeline ini, permintaan ke /doconut-res/doconutConverter.js berhasil, dan widget dapat memanggil /doconut?convert=open, /doconut?convert=run, dan /doconut?convert=download.

---

5. Apa yang sebenarnya dilakukan widget

Tahap	Endpoint server	Respons tipikal
Buka	?convert=open	Mengembalikan payload JSON yang berisi token, jumlah halaman, ekstensi sumber, dan daftar format target yang diizinkan.
Jalankan	?convert=run	Memulai konversi dan mengembalikan downloadToken, jumlah halaman hasil, nama file yang disarankan, serta flag yang menunjukkan apakah output memiliki watermark.
Unduh	?convert=download	Menyampaikan file yang telah dikonversi ketika klien mengikuti URL unduhan yang disediakan.

Di sisi klien, widget melakukan pemeriksaan ukuran pra‑unggah terhadap widget.MaxUploadMb. Jika file melebihi batas tersebut, widget membatalkan unggahan dan memicu callback onError dengan phase = "open" serta pesan yang ramah. Server menegakkan batasnya sendiri dan akan menjawab 413 Payload Too Large jika permintaan melewati pemeriksaan klien.

---

6. Menyambungkan ke acara widget (sisi C# tidak diperlukan)

Semua callback (onReady, onSourceLoaded, onConverted, onError, dll.) adalah fungsi JavaScript yang disediakan oleh halaman yang menampung widget. Karena pertanyaan berfokus pada sisi pendaftaran, Anda tidak perlu menulis kode C# tambahan untuk menangani callback tersebut—widget akan memanggilnya secara otomatis setelah endpoint aktif.

---

7. Kesalahan umum dan cara menghindarinya

Gejala	Penyebab kemungkinan	Perbaikan
404 pada /doconut?convert=open	AddConverterWidget() tidak disertakan.	Tambahkan panggilan seperti yang ditunjukkan pada bagian 3.
Aplikasi gagal memulai dengan InvalidOperationException tentang kemampuan yang hilang	File lisensi tidak memberikan Converter.	Dapatkan lisensi yang mencakup kemampuan Converter.
Kesalahan 500 terkait sesi	UseSession() ditempatkan setelah UseDoconut() atau pendaftaran cache hilang.	Pastikan app.UseSession() dijalankan sebelum app.UseDoconut() dan layanan cache terdaftar.

---

8. Jalankan aplikasi dan lihat widget beraksi

1. Bangun dan jalankan proyek ASP.NET Core.
2. Buka halaman yang berisi elemen <div id="doconut-convert"></div> dan menyertakan skrip konverter Doconut (skrip disajikan secara otomatis dari /doconut-res/doconutConverter.js).
3. Seret file yang didukung (PDF, DOCX, DWG, dll.) ke area drop.
4. Widget akan memanggil ?convert=open, kemudian ?convert=run, dan akhirnya menampilkan tautan Unduh yang mengarah ke ?convert=download.

Jika ketiga endpoint merespons dengan JSON alih-alih 404, widget telah terdaftar dengan benar dan siap digunakan dalam produksi.

---

Langkah berikutnya: Tambahkan potongan kode di atas ke Program.cs Anda (atau Startup.cs), pastikan file lisensi ada, dan luncurkan aplikasi. Widget konverter drop‑in akan aktif tanpa perubahan sisi server lebih lanjut.