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 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 tidak memiliki status — 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 CloseDocument(token) eksplisit.

Anda tidak lagi membuatnya. AddDoconut() mendaftarkannya sebagai layanan transien; injeksikan di mana pun Anda membutuhkannya:

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

Dalam aplikasi MVC, ambil sebagai parameter konstruktor; dalam tampilan Razor, gunakan @inject Doconut.Viewer Viewer. Cache milik aplikasi untuk instance Viewer tidak lagi diperlukan — dan tidak lagi tepat, karena mereka tidak menyimpan apa pun yang layak di‑cache.

Apa yang terjadi di dalam OpenDocumentAsync

  1. Gerbang lisensi. Lisensi yang ditolak atau kedaluwarsa versi (terdaftar hitam, dimanipulasi, 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 (berbeda dengan yang tidak ada). Lisensi Sementara atau berlangganan yang kedaluwarsa secara kalender adalah pengecualian: tidak melempar — menurun menjadi watermark.
  2. Pembuatan sesi. Pabrik viewer memilih viewer format yang tepat untuk ekstensi file dan memuat dokumen (lihat Rendering Pipeline). Sesi disimpan di 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.

Tidak ada langkah pemanasan terpisah. Perpustakaan sebelumnya mengekspos InitCache() untuk tujuan itu; kini tidak lagi ada, dan tidak ada yang menggantikannya.

Tiga overload hanya berbeda pada input: jalur file, jalur file plus konfigurasi per‑format (PdfConfig, WordConfig, …), atau Stream plus 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:

KueriTujuan
?token=…&page=NGambar halaman yang dirender (PNG)
?token=…&page=N&thumb=1Gambar mini
?token=…&zoom=…Render halaman yang diperbesar
?token=…&search=termPencarian teks penuh (dibatasi lisensi)
?token=…&bookmarksGaris besar dokumen/buku tanda
?token=…&copy / &showlinks / &fileFormatSalin teks, tautan, dan info format
?token=…&metaMetadata teknis DICOM; mengembalikan 501 untuk sesi DICOM pada paket ini
?token=…&action=rotate/flip/closeAksi halaman dan penutupan eksplisit
?token=…&AnnSave=… / &AnnLoadSimpan/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 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.

Di mana middleware dipasang

UseDoconut() menjawab permintaan yang membawa token, di mana pun Anda memasangnya. Sebuah pengaturan umum mempertahankan bentuk permintaan historis DocImage.axd pada cabang MapWhen, sehingga klien yang ada terus memanggil URL yang selalu dipakai. Apa pun yang Anda pilih, BasePath klien harus sesuai dengannya — lihat ViewerConfig.

Menyajikan halaman dari penyimpanan bersama alih‑alih node pembuka adalah pengaturan yang sepenuhnya berbeda; lihat Distributed Deployments.

csharp
viewer.CloseDocument(token);

CloseDocument menghapus sesi dari cache (yang membuang mesin dokumen yang mendasarinya dan membebaskan memori secara langsung), 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 sesegera mungkin setelah pengguna selesai.

Dipanggil pada Viewer yang diinjeksikan. Pola sebelumnya — membuat Viewer yang berumur pendek dalam blok using semata‑mata untuk menutup token — tidak memiliki padanan dan tidak diperlukan.

Kesimpulan

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

Apakah halaman ini membantu?