Cara Kerja Viewer
Siklus Hidup Permintaan Dokumen
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 Komponen 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 dengan token di
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 bersifat sealed, tidak menyimpan keadaan dokumen per-permintaan, dan sengaja tidak mengimplementasikan IDisposable. Sesi hidup secara independen di manajer sesi dan dibersihkan oleh kedaluwarsa cache atau CloseDocument(token) yang eksplisit.
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
- Gerbang lisensi. Lisensi yang ditolak atau kedaluwarsa versi (terdaftar hitam, dimanipulasi, atau build di luar jendela pembaruan lisensi) langsung melemparkan
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 — menurun menjadi watermark. - Pembuatan sesi. Pabrik penampil memilih penampil format yang tepat untuk ekstensi file dan memuat dokumen (lihat Pipeline Rendering). Sesi disimpan di
IMemoryCachedengan token GUID baru dan kedaluwarsa bergulir —DocOptions.TimeOutmenit, default 60. Setiap permintaan halaman mengatur ulang pengatur waktu. - Registrasi keamanan. Dengan
UnsafeMode = false(default), token diikat ke sesi ASP.NET pemanggil: penandasecure-{token}ditulis ke dalam sesi, sehingga hanya sesi browser yang membuka dokumen yang dapat meminta halamannya. - Token dikembalikan. Itu adalah kredensial tunggal untuk semua yang berikutnya.
Ketiga overload hanya berbeda pada input: jalur file, jalur file ditambah konfigurasi per‑format (PdfConfig, WordConfig, …), atau Stream ditambah FileInfo yang ekstensi‑nya menentukan deteksi format.
Bagaimana widget mendapatkan halaman
Widget klien memanggil middleware Doconut dengan token di string kueri. Apa yang dilakukan middleware tergantung pada permintaan:
| Kueri | Tujuan |
|---|---|
?token=…&page=N | Gambar halaman yang dirender (PNG) |
?token=…&page=N&thumb=1 | Thumbnail |
?token=…&zoom=… | Render halaman yang diperbesar |
?token=…&search=term | Pencarian teks penuh (berlisensi) |
?token=…&bookmarks | Garis besar dokumen/buku tanda |
?token=…© / &showlinks / &fileFormat / &meta | Penyalinan teks, tautan, info format, metadata teknis DICOM |
?token=…&action=rotate/flip/close | Aksi halaman dan penutupan eksplisit |
?token=…&AnnSave=… / &AnnLoad | Simpan/muat anotasi |
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 hilang (dengan
UnsafeMode = false) → HTTP 500 denganSession 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.
Menyajikan halaman dari penyimpanan bersama alih-alih node pembuka adalah pengaturan yang berbeda sepenuhnya; lihat Penyebaran Terdistribusi.
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 Penting
- Satu dokumen terbuka = satu sesi = satu token. Token bersifat per sesi browser, bukan URL global.
- Token kedaluwarsa pada jendela bergulir; penampil yang dibiarkan menganggur melewati
DocOptions.TimeOutmembutuhkan pembukaan ulang. Viewerdapat diinjeksikan dan dibagikan secara bebas; sesi membawa semua keadaan.
Apakah halaman ini membantu?