Cara Kerja Viewer

Doconut merender dokumen sebagai gambar berhalaman yang disajikan melalui middleware ASP.NET Core. Memahami siklus hidup — buka, token, permintaan halaman, tutup — menjelaskan hampir semua perilaku yang akan Anda amati, termasuk pesan kesalahan.

Tiga Bagian yang Bergerak

• Viewer — layanan publik yang Anda injeksikan. Ia membuka dokumen dan mengembalikan token sesi.
• Sesi dokumen — objek sisi server yang menyimpan dokumen yang dimuat, diindeks oleh token dalam IMemoryCache.
• Middleware Doconut — ditambahkan oleh UseDoconut(); menjawab setiap permintaan yang dibuat widget browser (pages, thumbnails, search, annotations, …), selalu diautentikasi oleh token.

Viewer bersifat stateless — secara desain

Viewer disegel, tidak menyimpan keadaan dokumen per-permintaan, dan dengan sengaja tidak mengimplementasikan IDisposable. Sesi hidup secara independen di manajer sesi dan dibersihkan oleh kedaluwarsa cache atau secara eksplisit dengan CloseDocument(token).

Injeksi di mana pun Anda membutuhkannya:

app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

Apa yang terjadi di dalam OpenDocumentAsync

1. Gerbang lisensi. Lisensi yang ditolak atau kedaluwarsa versi (terdaftar hitam, diubah, atau build di luar jendela pembaruan lisensi) langsung melempar LicenseException, dengan alasan penolakan sebagai pesan — pembukaan tidak pernah secara diam-diam menurun untuk lisensi yang tidak valid (berlawanan dengan tidak ada). Lisensi Sementara atau berlangganan yang kedaluwarsa secara kalender adalah pengecualian: tidak melempar — menurunkan menjadi watermark.
2. Pembuatan sesi. Pabrik viewer memilih viewer format yang tepat untuk ekstensi file dan memuat dokumen (lihat Rendering Pipeline). Sesi disimpan dalam IMemoryCache dengan token GUID baru dan kedaluwarsa bergulir — DocOptions.TimeOut menit, default 60. Setiap permintaan halaman mengatur ulang timer.
3. Registrasi keamanan. Dengan UnsafeMode = false (default), token diikat ke sesi ASP.NET pemanggil: penanda secure-{token} ditulis ke dalam sesi, sehingga hanya sesi browser yang membuka dokumen yang dapat meminta halamannya.
4. Token dikembalikan. Itu adalah kredensial tunggal untuk semua yang berikutnya.

Tiga overload hanya berbeda pada input: jalur file, jalur file plus konfigurasi per-format (PdfConfig, WordConfig, …), atau Stream plus FileInfo yang ekstensi filenya menentukan deteksi format.

Bagaimana widget mendapatkan halaman

Widget klien memanggil middleware Doconut dengan token di string kueri. Apa yang dilakukan middleware tergantung pada permintaan:

Setiap jalur ini divalidasi terlebih dahulu:

• Tidak ada token → middleware mengembalikan 404 (atau banner versi ketika ShowDoconutInfo = true).
• Token tidak dikenal atau kedaluwarsa → gambar error dengan Document session not found. Please re-open document.
• Middleware sesi tidak ada (dengan UnsafeMode = false) → HTTP 500 dengan Session middleware not configured. Call UseSession() before UseDoconut().
• Token dibuka oleh sesi browser yang berbeda → gambar error dengan You Are Not Authorized To View This Page.

Menutup dokumen

viewer.CloseDocument(token);

CloseDocument menghapus sesi dari cache (yang membuang mesin dokumen yang mendasarinya dan membebaskan memorinya segera), menghapus penanda secure-{token}, dan mencabut hak akses. Memanggilnya bersifat opsional — kedaluwarsa bergulir melakukan pembersihan yang sama secara otomatis — tetapi untuk dokumen besar ini adalah cara yang sopan untuk melepaskan memori begitu pengguna selesai.

Poin-poin Penting

• Satu dokumen terbuka = satu sesi = satu token. Token bersifat per sesi browser, bukan URL global.
• Token kedaluwarsa pada jendela bergulir; viewer yang dibiarkan idle melewati DocOptions.TimeOut memerlukan pembukaan ulang.
• Viewer dapat diinjeksikan dan dibagikan secara bebas; sesi membawa semua keadaan.