نحوه کار Viewer

دورهٔ درخواست سند

Doconut اسناد را به‌صورت تصاویر صفحه‌بندی‌شده که از طریق میدل‌ویر ASP.NET Core سرو می‌شوند، رندر می‌کند. درک چرخهٔ حیات — باز کردن، توکن، درخواست‌های صفحه، بستن — تقریباً تمام رفتارهایی که مشاهده می‌کنید، از جمله پیام‌های خطا، را توضیح می‌دهد.

سه بخش متحرک

  • Viewer — سرویس عمومی که تزریق می‌کنید. اسناد را باز می‌کند و توکن‌های جلسه را برمی‌گرداند.
  • جلسهٔ سند — شیء سمت‑سرور که سند بارگذاری‌شده را نگه می‌دارد، با کلید توکن در IMemoryCache.
  • میان‌افزار Doconut — توسط UseDoconut() اضافه شده؛ به هر درخواست که ویجت مرورگر می‌فرستد (pages، thumbnails، search، annotations، …) پاسخ می‌دهد و همیشه توسط توکن احراز می‌شود.

Viewer بدون حالت است — به‌صورت پیش‌فرض

Viewer مهر و موم شده است، هیچ وضعیت سندی برای هر درخواست نگه نمی‌دارد و عمداً پیاده‌سازی IDisposable نمی‌کند. جلسات به‌صورت مستقل در مدیر جلسه زندگی می‌کنند و با انقضای کش یا یک CloseDocument(token) صریح پاک‌سازی می‌شوند.

آن را در هر جایی که نیاز دارید تزریق کنید:

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

چه اتفاقی داخل OpenDocumentAsync می‌افتد

  1. دروازهٔ مجوز. یک مجوز رد شده یا منقضی‌شدهٔ نسخه (سیاه‌لیست شده، دست‌کاری‌شده، یا ساختی خارج از بازهٔ به‌روزرسانی مجوز) بلافاصله یک LicenseException پرتاب می‌کند، با دلیل رد به‌عنوان پیام — باز کردن هرگز به‌صورت خاموش برای یک مجوز نامعتبر (در مقابل غیاب) کم‌کیفیت نمی‌شود. یک مجوز موقت یا اشتراکی که تاریخ‌تقویم آن منقضی شده است استثنا است: آن پرتاب نمی‌کند — به یک واترمارک تبدیل می‌شود.
  2. ایجاد جلسه. کارخانهٔ ویور، ویور فرمت مناسب را بر اساس پسوند فایل انتخاب می‌کند و سند را بارگذاری می‌نماید (به «خط لولهٔ رندر» مراجعه کنید). جلسه در IMemoryCache تحت یک توکن GUID جدید با انقضای لغزان ذخیره می‌شود — DocOptions.TimeOut دقیقه، پیش‌فرض ۶۰. هر درخواست صفحه ساعت را بازنشانی می‌کند.
  3. ثبت امنیتی. با استفاده از UnsafeMode = false (پیش‌فرض)، توکن به جلسهٔ ASP.NET فراخواننده متصل می‌شود: یک علامت secure-{token} در جلسه نوشته می‌شود، به‌طوری که فقط جلسهٔ مرورگری که سند را باز کرده می‌تواند صفحات آن را درخواست کند.
  4. توکن برگردانده می‌شود. این یک اعتبار واحد برای تمام موارد بعدی است.

سه روش بارگذاری فقط در ورودی متفاوت هستند: یک مسیر فایل، مسیر فایل به‌همراه یک پیکربندی برای هر فرمت (PdfConfig، WordConfig، …)، یا یک Stream به‌همراه یک FileInfo که پسوند آن تشخیص فرمت را هدایت می‌کند.

ویجت چگونه صفحات را دریافت می‌کند

ویجت کلاینت با توکن در رشتهٔ پرس‌وجو، میدل‌ویر Doconut را فراخوانی می‌کند. کاری که میدل‌ویر انجام می‌دهد به درخواست بستگی دارد:

پرس‌وجوهدف
?token=…&page=Nتصویر صفحهٔ رندر شده (PNG)
?token=…&page=N&thumb=1تصویر بندانگشتی
?token=…&zoom=…رندر صفحهٔ بزرگ‌نمایی‌شده
?token=…&search=termجستجوی تمام متن (محدود به مجوز)
?token=…&bookmarksطرح کلی سند/نشانک‌ها
?token=…&copy / &showlinks / &fileFormat / &metaکپی متن، پیوندها، اطلاعات فرمت، فرادادهٔ فنی DICOM
?token=…&action=rotate/flip/closeعملیات صفحه و بستن صریح
?token=…&AnnSave=… / &AnnLoadذخیره/بارگذاری حاشیه‌نویسی‌ها

هر یک از این مسیرها ابتدا اعتبارسنجی می‌شوند:

  • بدون توکن → میدل‌ویر 404 برمی‌گرداند (یا بنر نسخه زمانی که ShowDoconutInfo = true).
  • توکن ناشناخته یا منقضی‌شده → تصویر خطا با Document session not found. Please re-open document.
  • میدل‌ویر جلسه موجود نیست (با UnsafeMode = false) → HTTP 500 با Session middleware not configured. Call UseSession() before UseDoconut().
  • توکن توسط جلسهٔ مرورگر متفاوتی باز شده → تصویر خطا با You Are Not Authorized To View This Page.

سرو کردن صفحات از ذخیره‌سازی مشترک به‌جای گرهٔ بازکننده یک تنظیم کاملاً متفاوت است؛ ببینید استقرارهای توزیع‌شده.

بستن یک سند

csharp
viewer.CloseDocument(token);

CloseDocument جلسه را از کش حذف می‌کند (که موتور سند زیرین را از بین می‌برد و حافظهٔ آن را بلافاصله آزاد می‌کند)، علامت secure-{token} را پاک می‌سازد و دسترسی اعطا شده را باطل می‌کند. فراخوانی آن اختیاری است — انقضای لغزان همان پاک‌سازی را به‌صورت خودکار انجام می‌دهد — اما برای اسناد بزرگ این روش مودبانه برای آزادسازی حافظه در همان لحظه‌ای است که کاربر کارش را تمام می‌کند.

نکات کلیدی

  • یک سند باز = یک جلسه = یک توکن. توکن‌ها به‌ازای هر جلسهٔ مرورگر هستند، نه URLهای سراسری.
  • توکن در یک بازهٔ لغزان منقضی می‌شود؛ یک ویور که بیش از DocOptions.TimeOut بیکار بماند نیاز به بازگشایی دارد.
  • Viewer می‌تواند به‌صورت آزاد تزریق و به اشتراک گذاشته شود؛ جلسات تمام وضعیت را حمل می‌کنند.

آیا این صفحه مفید بود؟