Mengimplementasikan Manajemen Dokumen dengan Doconut

Sebuah alur kerja manajemen dokumen dalam portal .NET biasanya membutuhkan tiga hal:

1. Cara untuk memuat PDF, file Office, gambar CAD, atau gambar tanpa menulis penampil dari awal.
2. Token aman yang mengaitkan dokumen yang dimuat dengan sesi peramban saat ini.
3. Langkah pembersihan yang membebaskan memori segera setelah pengguna selesai.

Doconut menyediakan ketiganya melalui layanan Viewer tunggal, sesi IMemoryCache yang ringan, dan panggilan CloseDocument eksplisit.

---

1. Daftarkan penampil di kontainer DI

Selama startup aplikasi, tambahkan layanan Doconut ke kontainer DI dengan memanggil metode pendaftaran Doconut yang dijelaskan dalam dokumentasi resmi. Langkah ini mendaftarkan penampil, penanganan lisensi, dan cache dalam memori yang akan menyimpan sesi dokumen.

Pendaftaran memvalidasi lisensi saat startup, sehingga lisensi yang hilang atau tidak valid akan gagal dengan cepat dan Anda mengetahui masalahnya sebelum permintaan pertama mencapai server.

---

2. Sisipkan middleware yang menyajikan gambar halaman, thumbnail, dan data anotasi

Konfigurasikan middleware Doconut dalam pipeline permintaan sehingga setiap permintaan yang berisi string kueri ?token= ditangani oleh Doconut. Middleware menegakkan penanda keamanan default (secure-{token}) ketika UnsafeMode bernilai false (default) dan menyajikan gambar halaman, thumbnail, serta data anotasi.

Menempatkan middleware pada cabang khusus menjaga sisa pipeline Anda tetap tidak tersentuh dan memungkinkan penskalaan horizontal tanpa sesi sticky.

---

3. Buka dokumen dan dapatkan token sesi opak

Buat satu endpoint yang menerima jalur file (atau aliran) dan mengembalikan token. Token adalah satu-satunya kredensial yang pernah dilihat oleh widget klien.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Token bersifat opak — serahkan ke widget, jangan pernah mencatat atau menyimpannya.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Contract.pdf");
    return Results.Ok(new { token });
});

Apa yang terjadi di dalam OpenDocumentAsync

1. Gerbang lisensi – lisensi tidak valid melempar LicenseException secara langsung.
2. Pembuatan sesi – Doconut memilih penampil format yang tepat (PDF, Word, DWG, …) dan menyimpan mesin di IMemoryCache di bawah token GUID.
3. Pendaftaran keamanan – dengan UnsafeMode = false token diikat ke sesi ASP.NET pemanggil melalui penanda secure-{token}. Hanya sesi peramban itu yang dapat meminta halaman.
4. Pengembalian token – klien menerima token dan menggunakannya untuk setiap permintaan berikutnya (/DocImage.axd?token=…).

Kadaluarsa geser default adalah 60 menit (dapat dikonfigurasi melalui DocOptions.TimeOut). Setiap permintaan halaman mengatur ulang timer, sehingga sesi yang menganggur menghilang secara otomatis.

---

4. Render dokumen di sisi klien

Dari peramban Anda memanggil endpoint, mengambil token, dan memberikannya ke widget Doconut:

fetch('/api/open', { method: 'POST' })
    .then(r => r.json())
    .then(d => {
        const token = d.token;
        objViewer.View(token);   // Widget JavaScript yang disediakan oleh Doconut
    });

Widget secara internal mengirimkan permintaan halaman, thumbnail, pencarian, dan anotasi yang semuanya menyertakan token yang sama. Karena token terikat pada sesi sisi server, pengguna jahat tidak dapat mengambil alih dokumen pengguna lain.

---

5. Tutup dokumen segera setelah pengguna meninggalkan penampil

Untuk PDF atau file CAD yang besar, Anda harus melepaskan mesin rendering segera. Panggil CloseDocument dari endpoint sisi server atau dari acara “unload” widget.

// Endpoint sisi‑server
app.MapPost("/api/close", (Viewer viewer, string token) =>
{
    viewer.CloseDocument(token);
    return Results.Ok();
});

// Pemanggilan langsung dari widget (jika Anda mengekspos token ke backend)
viewer.CloseDocument(token);

CloseDocument menghapus sesi dari cache, membuang mesin dokumen yang mendasarinya, menghapus penanda secure-{token}, dan mencabut hak akses. Kadaluarsa geser pada akhirnya akan melakukan hal yang sama, tetapi penutupan eksplisit menjamin memori direbut kembali sesegera pengguna selesai.

---

6. Opsional: Mengonversi dokumen di server

Jika alur kerja Anda memerlukan ekspor PDF dari file Word yang diunggah, aktifkan plugin Converter dalam konfigurasi Doconut (lihat dokumentasi). Setelah plugin terdaftar Anda dapat menyuntikkan DocumentConverter dan memanggil metode ConvertAsync. Konversi berjalan di server, sehingga Anda tidak pernah perlu menginstal Office di server web.

---

7. Pertimbangan penskalaan untuk manajemen dokumen tingkat perusahaan

• Front‑end tanpa status – Widget penampil tidak pernah menyimpan data dokumen; semua pemrosesan berat tetap di server.
• Cache terdistribusi – Ganti cache dalam memori default dengan penyedia terdistribusi (Redis, NCache) jika Anda menjalankan beberapa node web‑farm. Pemetaan token‑ke‑sesi tetap berfungsi karena middleware membaca dari IMemoryCache yang dikonfigurasi.
• Pekerjaan latar belakang – Anda dapat membuka dokumen sebelumnya di pekerja latar belakang, menyimpan token dalam cache, dan memberikannya ke UI nanti. Ingat bahwa setiap token hanya dapat digunakan sekali per sesi; penggunaan kembali memerlukan panggilan OpenDocumentAsync baru.

Pola-pola ini memungkinkan Anda membangun platform manajemen dokumen yang dapat diskalakan dari portal intranet server tunggal ke layanan cloud multi‑region tanpa menulis ulang logika penampil.

---

8. Daftar periksa cepat untuk implementasi siap produksi

Langkah	Tindakan
1	Daftarkan layanan Doconut di Program.cs (validasi lisensi).
2	Tambahkan middleware Doconut pada cabang khusus.
3	Ekspos endpoint /api/open yang memanggil OpenDocumentAsync.
4	Berikan token yang dikembalikan ke objViewer.View(token) di klien.
5	Panggil CloseDocument(token) ketika penampil disembunyikan atau halaman dibongkar.
6	(Opsional) Aktifkan ConverterPlugin jika Anda memerlukan konversi sisi server.
7	(Opsional) Ganti IMemoryCache dengan cache terdistribusi untuk penskalaan horizontal.

Ikuti daftar tersebut, dan Anda akan memiliki alur manajemen dokumen yang lengkap, aman, dan berkinerja tinggi yang dibangun di atas penampil .NET asli Doconut.