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, token, sayfa istekleri, kapatma — anlamak, gözlemleyeceğiniz hemen hemen tüm davranışları, hata mesajları dahil, açıklar.

Üç Hareketli Parça

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

İhtiyacınız olduğu her yere enjekte edin:

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

OpenDocumentAsync içinde neler olur

1. Lisans kapısı. Reddedilen veya sürümü süresi dolmuş bir lisans (kara listeye alınmış, değiştirilmiş veya lisansın güncelleme penceresi dışındaki bir derleme) hemen bir LicenseException fırlatır, reddetme nedeni mesaj olarak verilir — geçersiz (var olmayan değil) bir lisans için açma asla sessizce bozulmaz. Takvim süresi dolmuş Geçici veya abonelik lisansı istisna oluşturur: fırlatmaz — bir filigrana düşer.
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 token ile 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, token çağıranın ASP.NET oturumuna bağlanır: oturuma secure-{token} işareti yazılır, böylece sadece belgeyi açan tarayıcı oturumu sayfalarını isteyebilir.
4. Token döndürülür. Bu, sonraki tüm işlemler için tek kimlik bilgidir.

Üç aşırı yükleme yalnızca girişte farklılık gösterir: bir dosya yolu, bir dosya yolu artı format başına yapılandırma (PdfConfig, WordConfig, …) veya uzantısı format tespitini yönlendiren bir Stream ve FileInfo.

Widget Sayfaları Nasıl Alır

İstemci widget'ı, token'ı sorgu dizesinde göndererek Doconut ara katmanını çağırır. Ara katmanın yaptığı, isteğe göre değişir:

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

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

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ğrılması 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ının işi bittiğinde belleği serbest bırakmanın nazik yolu budur.

Çıkarımlar

• Açık bir belge = bir oturum = bir token. Token'lar tarayıcı oturumu başına olup, küresel URL'ler değildir.
• Token, kaydırmalı bir pencere içinde süresi dolar; DocOptions.TimeOut süresini aşan bir viewer yeniden açılmalıdır.
• Viewer enjekte edilebilir ve serbestçe paylaşılabilir; oturumlar tüm durumu taşır.