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

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

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

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

  • Viewer — الخدمة العامة التي تستخرجها من DoconutHost.Services. تقوم بفتح المستندات وإرجاع رموز الجلسة.
  • جلسة المستند — كائن على جانب الخادم يحتفظ بالمستند المحمّل، يُحفظ في الذاكرة تحت رمزه المميز.
  • DocImage.axd — الـ Doconut.DocImageHandler المعلن في Web.config. يرد على كل طلب يقوم به عنصر المتصفح (صفحات، صور مصغرة، بحث، تعليقات توضيحية، …)، دائمًا يُحدَّد بالرمز المميز.
  • /doconut-res/* — الـ Doconut.DoconutResourceModule، الذي يقدم سكريبتات العنصر، الأنماط، والرموز الخاصة به.

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

Viewer لا يحتفظ بحالة المستند لكل طلب ولا ينفّذ IDisposable. الجلسات تعيش بشكل مستقل عنه ويتم تنظيفها عند الانتهاء أو عبر CloseDocument(token) صريح. لا يحتوي System.Web على حقن عبر المُنشئ، لذا استخرجها حيث تحتاجها — عادةً في إجراء المتحكم:

csharp
// POST /ViewerApi/Open?fileName=Sample.pdf
[HttpPost]
public async Task<ActionResult> Open(string fileName)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    var path   = Server.MapPath("~/files/" + Path.GetFileName(fileName));

    var token = await viewer.OpenDocumentAsync(path);
    return Content(token, "text/plain");
}

ما يحدث داخل OpenDocumentAsync

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

تقبل التحميلات غير المتزامنة مسار ملف، أو مسار ملف مع تكوين لكل صيغة (PdfConfig, WordConfig, …)، أو Stream مع FileInfo الذي يحدد الصيغة بناءً على الامتداد. بالنسبة لملفات الكود الخلفية في Web Forms التي لا تستخدم الصفحات غير المتزامنة، يقدم OpenDocument نفس الثلاث مدخلات بشكل متزامن (مسار، تدفق مع اسم ملف، أو مصفوفة بايت مع اسم ملف).

كيف يحصل العنصر على الصفحات

يتصل العنصر بـ DocImage.axd مع الرمز المميز في سلسلة الاستعلام. ما يفعله المعالج يعتمد على الطلب:

الاستعلامالغرض
?token=…&page=Nصورة صفحة مُصدَّرة (PNG)
?token=…&page=N&thumb=1صورة مصغرة
?token=…&zoom=…عرض صفحة مكبرة
?token=…&search=termبحث نص كامل (محجوب بالترخيص)
?token=…&bookmarksمخطط المستند والمرجعيات
?token=…&copy / &showlinks / &fileFormatنسخ النص، الروابط التشعبية، ومعلومات الصيغة
?token=…&metaبيانات DICOM التقنية — غير متوفرة في هذه الحزمة (الإجابات 404)
?token=…&action=rotate/flip/closeإجراءات الصفحة وإغلاق صريح (POST)
?token=…&AnnSave=… / &AnnLoadحفظ وتحميل التعليقات التوضيحية

يتم فحص كل طلب أولاً:

  • بدون رمز مميز → 404، أو شريط نسخة عندما ShowDoconutInfo = true.
  • الرمز المميز غير مُمنوح لهذه جلسة ASP.NET → صورة خطأ تُظهر You Are Not Authorized To View This Page.
  • رمز مميز غير معروف أو منتهي → صورة خطأ تُظهر Document session not found. Please re-open document.

صور الخطأ هي PNG عادية تُرسل بحالة 200، بحيث يمكن للعنصر عرضها حيث تكون الصفحة. فحص المراقبة الذي ينظر فقط إلى رمز الحالة سيُبلغ عنها كصفحات مُقدمة؛ الصفحة الفعلية تكون بحجم عشرات إلى مئات الكيلوبايت، وصورة الخطأ حوالي 2 كيلوبايت.

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

csharp
viewer.CloseDocument(token);

CloseDocument يزيل الجلسة (مُحرّرًا محرك المستند وذاكرته فورًا)، يزيل إدخال secure-{token} من جلسة ASP.NET للطلب الحالي، ويُسحب الرمز المميز. هذا اختياري — الانتهاء المتزلج يقوم بنفس التنظيف — لكن للمستندات الكبيرة يحرّر الذاكرة فور انتهاء المستخدم. من المتصفح، يرسل objViewer.Close(true) طلب الإغلاق المكافئ إلى DocImage.axd.

الخلاصات

  • مستند مفتوح واحد = جلسة واحدة = رمز مميز واحد، يُمنح لجلسة ASP.NET التي فتحته.
  • ينتهي الرمز المميز بعد نافذة متزلجة؛ إذا ظل العارض غير نشط أكثر من DocOptions.TimeOut يحتاج إلى إعادة الفتح.
  • يمكن حل Viewer ومشاركته بحرية؛ الجلسات تحمل كل الحالة.

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