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

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

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

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

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

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

قم بحقنه أينما احتجت إليه:

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 مع الرمز في سلسلة الاستعلام. ما يفعله الوسيط يعتمد على الطلب:

كل واحد من هذه المسارات يتحقق أولاً:

• بدون رمز → يُعيد الوسيط 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.

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

viewer.CloseDocument(token);

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

النقاط الرئيسية

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