Cara Kerja Viewer

Doconut merender dokumen sebagai gambar berhalaman, disajikan oleh handler HTTP yang didaftarkan di Web.config Anda. Memahami siklus hidup — membuka, token, permintaan halaman, menutup — menjelaskan hampir semua perilaku yang akan Anda amati, termasuk pesan kesalahan.

Komponen yang bergerak

• Viewer — layanan publik yang Anda dapatkan dari DoconutHost.Services. Ia membuka dokumen dan mengembalikan token sesi.
• Sesi dokumen — objek sisi server yang menyimpan dokumen yang dimuat, disimpan dalam memori di bawah tokennya.
• DocImage.axd — Doconut.DocImageHandler yang dideklarasikan di Web.config. Ia menjawab setiap permintaan yang dibuat widget browser (halaman, thumbnail, pencarian, anotasi, …), selalu diidentifikasi oleh token.
• /doconut-res/* — Doconut.DoconutResourceModule, yang menyajikan skrip, gaya, dan ikon milik widget.

Viewer bersifat stateless — menurut desain

Viewer tidak menyimpan keadaan dokumen per-permintaan dan tidak mengimplementasikan IDisposable. Sesi hidup secara independen darinya dan dibersihkan oleh kedaluwarsa atau CloseDocument(token) secara eksplisit. System.Web tidak memiliki injeksi konstruktor, jadi dapatkan di tempat Anda membutuhkannya — biasanya dalam aksi controller:

// POST /ViewerApi/Open?fileName=Sample.pdf
[HttpPost]
public async Task<ActionResult> Open(string fileName)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    var path   = Server.MapPath("~/files/" + Path.GetFileName(fileName));

    var token = await viewer.OpenDocumentAsync(path);
    return Content(token, "text/plain");
}

Apa yang terjadi di dalam OpenDocumentAsync

1. Gerbang lisensi. Lisensi yang ditolak (dimodifikasi, diblacklist, atau build di luar jendela pembaruan lisensi) langsung melempar LicenseException, dengan alasan sebagai pesan. Membuka tidak pernah secara diam-diam menurun untuk lisensi tidak valid; lisensi hilang hanya menambahkan watermark.
2. Pembuatan sesi. Factory viewer memilih viewer format berdasarkan ekstensi file dan memuat dokumen (lihat Pipeline Rendering). Sesi disimpan dalam memori di bawah token acak baru dengan kedaluwarsa bergulir selama DocOptions.TimeOut menit (default 60). Setiap permintaan halaman mengatur ulang timer.
3. Pemberian akses. Dengan UnsafeMode = false (default), token terikat pada sesi ASP.NET dari permintaan yang membukanya: entri secure-{token} ditulis ke dalam sesi tersebut. Oleh karena itu, pembukaan harus dijalankan dalam permintaan dengan status sesi — lihat Sesi & Keamanan.
4. Token dikembalikan. Itu adalah satu-satunya pengenal yang dibutuhkan browser untuk semua hal selanjutnya.

Overload asynchronous menerima jalur file, jalur file plus konfigurasi per-format (PdfConfig, WordConfig, …), atau Stream plus FileInfo yang ekstensi filenya menentukan format. Untuk kode-behind Web Forms yang tidak menggunakan halaman asynchronous, OpenDocument menawarkan tiga masukan yang sama secara sinkron (jalur, aliran dengan nama file, atau array byte dengan nama file).

Bagaimana widget mendapatkan halaman

Widget memanggil DocImage.axd dengan token di string kueri. Apa yang dilakukan handler tergantung pada permintaan:

Setiap permintaan pertama-tama diperiksa:

• Tidak ada token → 404, atau banner versi ketika ShowDoconutInfo = true.
• Token tidak diberikan ke sesi ASP.NET ini → gambar error dengan teks You Are Not Authorized To View This Page.
• Token tidak dikenal atau kedaluwarsa → gambar error dengan teks Document session not found. Please re-open document.

Gambar error adalah PNG biasa yang dikirim dengan status 200, sehingga widget dapat menampilkannya di tempat halaman seharusnya. Pemeriksaan pemantauan yang hanya melihat kode status akan melaporkan mereka sebagai halaman yang disajikan; halaman nyata berukuran puluhan hingga ratusan kilobyte, sedangkan gambar error sekitar 2 KB.

Menutup dokumen

viewer.CloseDocument(token);

CloseDocument menghapus sesi (melepaskan mesin dokumen dan memorinya secara langsung), menghapus entri secure-{token} dari sesi ASP.NET permintaan saat ini, dan mencabut token. Ini opsional — kedaluwarsa bergulir melakukan pembersihan yang sama — tetapi untuk dokumen besar ini melepaskan memori begitu pengguna selesai. Dari browser, objViewer.Close(true) mengirim permintaan tutup yang setara ke DocImage.axd.

Poin Penting

• Satu dokumen terbuka = satu sesi = satu token, diberikan ke sesi ASP.NET yang membukanya.
• Token kedaluwarsa pada jendela bergulir; viewer yang dibiarkan idle melewati DocOptions.TimeOut memerlukan pembukaan kembali.
• Viewer dapat di‑resolve dan dibagikan secara bebas; sesi menyimpan semua keadaan.