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

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

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 دقيقة، الافتراضي 60. كل طلب صفحة يعيد ضبط المؤقت.
  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 ومشاركته بحرية؛ الجلسات تحمل كل الحالة.

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