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

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

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. License gate. ترخيص مرفوض أو منتهي الصلاحية (محظور، مُتلاعب، أو بناء خارج نافذة تحديث الترخيص) يرمي 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نسخ النص، الروابط التشعبية، ومعلومات التنسيق
?token=…&metaبيانات DICOM التقنية؛ تُعيد 501 لجلسة DICOM على .NET 6
?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 ومشاركته بحرية؛ الجلسات تحمل كل الحالة.

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