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

سه overload فقط در ورودی متفاوت هستند: یک مسیر فایل، یک مسیر فایل به‌اضافه یک پیکربندی برای هر فرمت (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کپی متن، پیوندها، و اطلاعات فرمت
?token=…&metaمتادیتای فنی DICOM؛ برای یک جلسه DICOM در .NET 6، 501 را برمی‌گرداند
?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 می‌تواند تزریق و به‌صورت آزاد به اشتراک گذاشته شود؛ جلسات تمام وضعیت را حمل می‌کنند.

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