Viewer Nasıl Çalışır

Doconut, belgeleri ASP.NET Core ara katmanı aracılığıyla sunulan sayfalı görüntüler olarak işler. Yaşam döngüsünü — açma, belirteç, sayfa istekleri, kapama — anlamak, gözlemleyeceğiniz hemen hemen her davranışı, hata mesajları dahil, açıklar.

Üç hareketli parça

• Viewer — enjekte ettiğiniz genel hizmet. Belgeleri açar ve oturum belirteçleri döndürür.
• Belge oturumu — IMemoryCache içinde bir belirteçle anahtarlanan, yüklü belgeyi tutan sunucu tarafı nesne.
• Doconut ara katmanı — UseDoconut() ile eklenir; tarayıcı widget'ının yaptığı her isteğe yanıt verir (pages, thumbnails, search, annotations, …) ve her zaman belirteçle kimlik doğrulanır.

Viewer durum bilgisizdir — tasarım gereği

Viewer mühürlenmiştir, istek başına belge durumu tutmaz ve kasıtlı olarak IDisposable uygulamaz. Oturumlar, oturum yöneticisinde bağımsız olarak yaşar ve önbellek süresi dolması ya da açıkça CloseDocument(token) çağrılmasıyla temizlenir.

Artık onu oluşturmazsınız. AddDoconut() onu geçici bir hizmet olarak kaydeder; ihtiyacınız olduğu her yerde enjekte edin:

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

Bir MVC uygulamasında, bunu bir yapıcı parametresi olarak alın; bir Razor görünümünde @inject Doconut.Viewer Viewer kullanın. Viewer örneklerinin uygulama‑sahibi önbellekleri artık gerekli değil — ve doğru da değil, çünkü önbelleğe alınacak bir şey tutmazlar.

OpenDocumentAsync içinde neler olur

1. Lisans kontrolü. Reddedilen ya da süresi dolmuş bir lisans (kara listeye alınmış, değiştirilmiş veya lisansın güncelleme penceresi dışındaki bir derleme) bir LicenseException fırlatır, reddetme nedeni mesaj olarak verilir — geçersiz (var olmayan değil) bir lisans için açma sessizce bozulmaz. Takvim süresi dolmuş Geçici ya da abonelik lisansı istisna oluşturur: bir istisna fırlatmaz — bir filigrana bozulur.
2. Oturum oluşturma. Görüntüleyici fabrikası dosya uzantısına uygun format görüntüleyicisini seçer ve belgeyi yükler (bkz. Rendering Pipeline). Oturum, yeni bir GUID belirteciyle IMemoryCache içinde kaydırmalı süresi dolma (DocOptions.TimeOut dakikası, varsayılan 60) ile saklanır. Her sayfa isteği saati sıfırlar.
3. Güvenlik kaydı. UnsafeMode = false (varsayılan) olduğunda, belirteç çağıranın ASP.NET oturumuna bağlanır: oturuma bir secure-{token} işareti yazılır, böylece belgeyi açan tarayıcı oturumu dışındaki bir oturum sayfalarını isteyemez.
4. Belirteç döndürülür. Bu, sonrasındaki her şey için tek kimlik bilgisidir.

Ayrı bir ısınma adımı yoktur. Önceki kütüphane bu amaçla InitCache() sunuyordu; artık yok ve yerine bir şey gelmedi.

Üç aşırı yükleme yalnızca giriş açısından farklıdır: bir dosya yolu, bir dosya yolu artı format‑başına konfigürasyon (PdfConfig, WordConfig, …) veya bir Stream artı format tespiti için uzantıyı kullanan bir FileInfo.

Widget sayfaları nasıl alır

İstemci widget'ı, belirteci sorgu dizesinde taşıyarak Doconut ara katmanını çağırır. Ara katmanın yaptığı işlem isteğe bağlıdır:

Bu yolların her biri önce doğrulanır:

• Belirteç yok → ara katman 404 döner (veya ShowDoconutInfo = true olduğunda bir sürüm bannerı gösterir).
• Bilinmeyen veya süresi dolmuş belirteç → Document session not found. Please re-open document. mesajlı bir hata resmi.
• Oturum ara katmanı eksik (UnsafeMode = false ile) → Session middleware not configured. Call UseSession() before UseDoconut(). mesajlı HTTP 500.
• Farklı bir tarayıcı oturumu tarafından açılmış belirteç → You Are Not Authorized To View This Page. mesajlı bir hata resmi.

Ara katman nerede monte edilir

UseDoconut() belirteç taşıyan istekleri yanıtlar, nerede monte ettiğinize bakılmaksızın. Referans uygulama, tarihsel DocImage.axd istek şeklini bir MapWhen dalında tutar, böylece mevcut istemci her zaman aynı URL'yi çağırmaya devam eder. Ne seçerseniz seçin, istemcinin BasePath değeri bununla aynı olmalıdır — bkz. ViewerConfig.

Sayfaları, açma düğümünden farklı bir paylaşımlı depolamadan sunmak tamamen başka bir düzenlemedir; bkz. Dağıtılmış Dağıtımlar.

Bir belgeyi kapatma

viewer.CloseDocument(token);

CloseDocument, oturumu önbellekten kaldırır (bu, temel belge motorunu dispose eder ve belleğini hemen serbest bırakır), secure-{token} işaretini siler ve erişim iznini iptal eder. Çağırmak isteğe bağlıdır — kaydırmalı süresi dolma aynı temizlik işlemini otomatik yapar — ancak büyük belgeler için kullanıcı işi bitirir bitirmez belleği serbest bırakmanın nazik yolu budur.

Enjekte edilmiş Viewer üzerinde çağrılır. Önceki desen — bir using bloğunda kısa ömürlü bir Viewer oluşturup yalnızca belirteci kapatmak — artık eşdeğeri yoktur ve gerekmez.

Çıkarımlar

• Bir açık belge = bir oturum = bir belirteç. Belirteçler tarayıcı oturumuna özeldir, genel URL'ler değildir.
• Belirteç kaydırmalı bir pencere içinde süresi dolar; DocOptions.TimeOut süresini aşan bir görüntüleyici yeniden açma gerektirir.
• Viewer enjekte edilebilir ve serbestçe paylaşılabilir; oturumlar tüm durumu taşır.