نحوه کار Viewer
دورهٔ درخواست سند
Doconut اسناد را به صورت تصاویر صفحهبندیشده که از طریق میدلویر ASP.NET Core سرو میشوند، رندر میکند. درک چرخهٔ حیات — باز کردن، توکن، درخواستهای صفحه، بستن — تقریباً تمام رفتارهایی را که مشاهده خواهید کرد، از جمله پیامهای خطا، توضیح میدهد.
سه بخش متحرک
Viewer— سرویس عمومیای که تزریق میکنید. اسناد را باز میکند و توکنهای جلسه را برمیگرداند.- جلسهٔ سند — یک شیء سمت سرور که سند بارگذاریشده را نگه میدارد، با کلید توکن در
IMemoryCache. - میانافزار Doconut — توسط
UseDoconut()اضافه میشود؛ به هر درخواست که ویجت مرورگر میفرستد (pages،thumbnails،search،annotations، …) پاسخ میدهد و همیشه توسط توکن احراز هویت میشود.
Viewer بیحالت است — بهصورت پیشفرض
Viewer مهر و موم شده است، هیچ وضعیت سندی بر پایه درخواست نگه نمیدارد و عمداً نه پیادهسازی IDisposable را انجام میدهد. جلسات بهصورت مستقل در مدیر جلسه زندگی میکنند و توسط انقضای کش یا یک CloseDocument(token) صریح پاکسازی میشوند.
دیگر نیازی به ساختن آن ندارید. AddDoconut() آن را بهعنوان سرویس موقت ثبت میکند؛ هرجا که نیاز دارید آن را تزریق کنید:
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync($"files/{fileName}");
return Results.Content(token, "text/plain");
});در یک برنامه MVC، آن را بهعنوان پارامتر سازنده بگیرید؛ در یک نمای Razor، از @inject Doconut.Viewer Viewer استفاده کنید. کشهای متعلق به برنامه از نمونههای Viewer دیگر لازم نیستند — و دیگر صحیح نیستند، زیرا هیچ چیزی برای کش کردن ندارند.
چه اتفاقی داخل OpenDocumentAsync میافتد
- دروازهٔ مجوز. یک مجوز رد شده یا منقضیشده (سیاهلیست شده، دستکاری شده، یا ساختی خارج از بازهٔ بهروزرسانی مجوز) بلافاصله یک
LicenseExceptionپرتاب میکند، با دلیل رد بهعنوان پیام — باز کردن هرگز بهصورت خاموش برای یک مجوز نامعتبر (در مقابل غیاب) کاهش کیفیت نمییابد. یک مجوز موقت یا اشتراکی که تاریختقویم آن منقضی شده است استثنا است: آن پرتاب نمیکند — به یک واترمارک کاهش مییابد. - ایجاد جلسه. کارخانهٔ نمایشگر فرمت مناسب را بر اساس پسوند فایل انتخاب میکند و سند را بارگذاری مینماید (به مسیر رندرینگ مراجعه کنید). جلسه در
IMemoryCacheتحت یک توکن GUID تازه با انقضای لغزان —DocOptions.TimeOutدقیقه، پیشفرض ۶۰ — ذخیره میشود. هر درخواست صفحه ساعت را بازنشانی میکند. - ثبت امنیتی. با استفاده از
UnsafeMode = false(پیشفرض)، توکن به جلسهٔ ASP.NET فراخواننده متصل میشود: یک نشانگرsecure-{token}در جلسه نوشته میشود، بهطوری که فقط جلسهٔ مرورگری که سند را باز کرده میتواند صفحات آن را درخواست کند. - توکن برگردانده میشود. این یک اعتبار واحد برای تمام موارد بعدی است.
هیچ گام گرمکردن جداگانهای وجود ندارد. کتابخانهٔ قبلی برای این منظور InitCache() را ارائه میداد؛ دیگر وجود ندارد و هیچچیز جایگزین آن نمیشود.
سه overload فقط در ورودی متفاوت هستند: یک مسیر فایل، مسیر فایل بهاضافه یک پیکربندی برای هر فرمت (PdfConfig، WordConfig، …)، یا یک Stream بهاضافه یک FileInfo که پسوند آن تشخیص فرمت را هدایت میکند.
نحوه دریافت صفحات توسط ویجت
ویجت مشتری با توکن در رشتهٔ پرسوجو، به میدلویر Doconut فراخوانی میکند. کاری که میدلویر انجام میدهد بسته به درخواست متفاوت است:
| پرسوجو | هدف |
|---|---|
?token=…&page=N | تصویر صفحهٔ رندر شده (PNG) |
?token=…&page=N&thumb=1 | تصویر بندانگشتی |
?token=…&zoom=… | رندر صفحهٔ بزرگنماییشده |
?token=…&search=term | جستجوی تمام متن (محدود به مجوز) |
?token=…&bookmarks | طرح کلی سند/نشانکها |
?token=…© / &showlinks / &fileFormat | کپی متن، پیوندها، و اطلاعات فرمت |
?token=…&meta | متادیتای فنی DICOM؛ 501 را برای یک جلسه 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.
جایی که میدلویر نصب میشود
UseDoconut() درخواستهایی که توکن دارند را پاسخ میدهد، هرجا که آن را نصب کنید. یک تنظیم رایج شکل درخواست تاریخی DocImage.axd را بر روی شاخهٔ MapWhen حفظ میکند، بنابراین یک مشتری موجود همچنان URL را که همیشه صدا میزد، فراخوانی میکند. هرچه انتخاب کنید، BasePath مشتری باید با آن مطابقت داشته باشد — ببینید پیکربندینمایشگر.
سرو کردن صفحات از ذخیرهسازی مشترک بهجای گرهٔ بازکننده یک ترتیب کاملاً متفاوت است؛ ببینید استقرارهای توزیعشده.
بستن یک سند
viewer.CloseDocument(token);CloseDocument جلسه را از کش حذف میکند (که موتور سند زیرین را از بین میبرد و حافظهٔ آن را بلافاصله آزاد میکند)، نشانگر secure-{token} را پاک میکند و دسترسی اعطا شده را باطل میسازد. فراخوانی آن اختیاری است — انقضای لغزان همان پاکسازی را بهصورت خودکار انجام میدهد — اما برای اسناد بزرگ این روش مودبانه برای آزاد کردن حافظه در همان لحظهای است که کاربر کارش را تمام میکند.
این روی Viewer تزریقشده فراخوانی میشود. الگوی قبلی — ساختن یک Viewer کوتاهمدت در یک بلوک using صرفاً برای بستن یک توکن — معادل ندارد و نیازی به آن نیست.
نکات کلیدی
- یک سند باز = یک جلسه = یک توکن. توکنها به ازای هر جلسه مرورگر هستند، نه URLهای سراسری.
- توکن در یک بازهٔ لغزان منقضی میشود؛ یک نمایشگر که بیش از
DocOptions.TimeOutبیکار بماند نیاز به بازگشایی مجدد دارد. Viewerمیتواند تزریق و بهصورت آزاد به اشتراک گذاشته شود؛ جلسات تمام وضعیت را حمل میکنند.
آیا این صفحه مفید بود؟