كيف يعمل العارض

دورة حياة طلب المستند

يقوم Doconut بعرض المستندات كصور مقسمة إلى صفحات تُقدَّم عبر وسيلة وسط ASP.NET Core. فهم دورة الحياة — الفتح، الرمز، طلبات الصفحات، الإغلاق — يشرح تقريبًا كل سلوك ستلاحظه، بما في ذلك رسائل الأخطاء.

الأجزاء الثلاثة المتحركة

  • Viewer — الخدمة العامة التي تقوم بحقنها. تفتح المستندات وتُعيد رموز الجلسة.
  • جلسة المستند — كائن على جانب الخادم يحتفظ بالمستند المحمَّل، يُعرَّف بواسطة رمز في IMemoryCache.
  • الوسيط Doconut — يُضاف بواسطة UseDoconut()؛ يرد على كل طلب يُجريه عنصر المتصفح (pages، thumbnails، search، annotations، …)، دائمًا مُصادَقًا بالرمز.

Viewer غير حالة — حسب التصميم

Viewer مغلق، لا يحتفظ بحالة المستند لكل طلب، ويتعمد عدم تنفيذ IDisposable. الجلسات تعيش بشكل مستقل في مدير الجلسات وتُنظَّف بانتهاء صلاحية الذاكرة المؤقتة أو عبر CloseDocument(token) صريح.

لم تعد تُنشئه. AddDoconut() يسجّله كخدمة مؤقتة؛ حقّنه أينما احتجت إليه:

csharp
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

  1. بوابة الترخيص. ترخيص مرفوض أو منتهي الصلاحية (مُدرج في القائمة السوداء، مُتلاعب به، أو بناء خارج نافذة تحديث الترخيص) يُطلق LicenseException فورًا، مع سبب الرفض كرسالة — لا يتدهور الفتح بصمت عند ترخيص غير صالح (على عكس الغياب). الترخيص المؤقت أو الاشتراكي المنتهي وفقًا للتقويم هو الاستثناء: لا يُطلق — يتدهور إلى علامة مائية.
  2. إنشاء الجلسة. يختار مصنع العارض العارض المناسب للامتداد ويحمِّل المستند (انظر خط أنابيب العرض). تُخزن الجلسة في IMemoryCache تحت رمز GUID جديد مع انتهاء زمني متحرك — DocOptions.TimeOut دقيقة، الافتراضي 60. كل طلب صفحة يُعيد ضبط المؤقت.
  3. تسجيل الأمان. باستخدام UnsafeMode = false (الإعداد الافتراضي)، يُربط الرمز بجلسة ASP.NET للمتصل: تُكتب علامة secure-{token} في الجلسة، بحيث لا يمكن إلا جلسة المتصفح التي فتحت المستند طلب صفحاته.
  4. يُعاد الرمز. هو الاعتماد الوحيد لكل ما يلي.

لا توجد خطوة إحماء منفصلة. المكتبة السابقة كانت تُظهر InitCache() لهذا الغرض؛ لم تعد موجودة، ولا شيء يستبدلها.

تختلف الثلاثة إصدارات فقط في الإدخال: مسار ملف، مسار ملف مع تكوين لكل صيغة (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؛ تُعيد 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 الخاص بالعميل معه — انظر إعدادات العارض.

تقديم الصفحات من تخزين مشترك بدلاً من العقدة التي فتحت المستند هو ترتيب مختلف تمامًا؛ انظر النشر الموزع.

إغلاق المستند

csharp
viewer.CloseDocument(token);

CloseDocument يزيل الجلسة من الذاكرة المؤقتة (التي تُفرغ محرك المستند الأساسي وتحرّر ذاكرته فورًا)، يحذف علامة secure-{token}، ويُسحب صلاحية الوصول. استدعاؤه اختياري — انتهاء الصلاحية المتحرك يقوم بنفس التنظيف تلقائيًا — لكن للمستندات الكبيرة هو الطريقة المهذبة لتحرير الذاكرة فور انتهاء المستخدم.

يُستدعى على Viewer المُحقن. النمط السابق — إنشاء Viewer قصير العمر داخل كتلة using فقط لإغلاق رمز — لا يوجد له مكافئ ولا حاجة إليه.

الخلاصات

  • مستند مفتوح واحد = جلسة واحدة = رمز واحد. الرموز تخص كل جلسة متصفح، ليست عناوين URL عامة.
  • ينتهي صلاحية الرمز في نافذة متحركة؛ إذا ظل العارض غير نشط بعد DocOptions.TimeOut يحتاج إلى إعادة فتح.
  • يمكن حقن Viewer ومشاركته بحرية؛ الجلسات تحمل كل الحالة.

هل كانت هذه الصفحة مفيدة؟