نظام الإضافات

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

تسجيل إضافة

كل حزمة إضافة تُظهر فئة إضافة واحدة. سجِّلها مرة واحدة، في Application_Start:

Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// ملحق مسجل لا توجد له رخصة يثير استثناءً هنا، في Application_Start، و الـ
// الموقع بعد ذلك يرد على كل طلب بخطأ 500 فارغ. السبب موجود في سجل أحداث Windows.

AddPlugin<TPlugin>() ينشئ الإضافة ويسمح لها بتسجيل مساهماتها مع DoconutOptions. كل ما تُضيفه الإضافة يُوسم بـ القدرة المطلوبة للإضافة، وDoconutHost.Initialize يتحقق من كل إضافة مسجلة مقابل الرخصة قبل أن يخدم الموقع طلبه الأول.

رخصة الإضافة المفقودة توقف الموقع

عندما لا تمنح أي رخصة نشطة قدرة الإضافة المسجلة — لا رخصة على الإطلاق، ملف TRIAL قديم، أو رخصة مدفوعة بدون تلك القدرة — DoconutHost.Initialize يرمي InvalidOperationException من Application_Start:

The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

في System.Web، الاستثناء في Application_Start لا ينتج صفحة خطأ. كل طلب يرد بـ 500 فارغ، سجل IIS لا يُظهر شيئًا مفيدًا، والرسالة تظهر فقط في سجل أحداث Windows (سجل التطبيقات، المصدر ASP.NET). عندما يتوقف الموقع عن الاستجابة مباشرة بعد إضافة سطر AddPlugin، تحقق أولاً من ملفات الرخصة في wwwroot — راجع إعداد الرخصة.

العقد

تُنفّذ الإضافة واجهة صغيرة عمدًا:

public interface IDoconutPlugin
{
    string Name { get; }                          // مثلاً "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // بوابة الترخيص
    void Register(IDoconutPluginBuilder builder); // المساهمة في المشاهدين/الخدمات
}

داخل Register، يقبل المُنشئ نوعين من المساهمة:

• builder.RegisterViewer(".dcm", () => new DicomViewer()) — عارض لامتداد ملف،
• builder.RegisterService<TContract>(() => …) — خدمة مكتوبة يمكن لأجزاء أخرى من خط الأنابيب البحث عنها.

القدرات والقيود

القدرات هي وحدات الرخصة. Converter وDicom تُرسل كإضافات اختيارية؛ Search وAnnotation هي ميزات مدمجة تُقيد بنفس الطريقة. العارض الأساسي ليس قدرة — إنه المتطلب المسبق، يُعرَض كـ IsViewerLicensed على خدمة الرخصة.

عادةً ما تُبقي عملية التحقق عند بدء التشغيل إضافة غير مرخصة خارج خط أنابيب الطلبات. كما يطبق مصنع العارض قاعدتين دفاعيتين، وهما مهمتان إذا تغيرت الحقوق أثناء تشغيل الموقع:

• إضافة تتجاوز عارضًا مدمجًا (تطالب بامتداد يتعامل معه عارض مدمج أيضًا): إذا كانت القدرة مرخصة، ينتصر عارض الإضافة؛ بدونها، يعود Doconut إلى العارض المدمج. لا يزال المستخدمون يرون مستنداتهم؛ لكنهم لا يحصلون على سلوك الإضافة.
• صيغة خاصة بالإضافات فقط (.dcm و.ima — لا يوجد عارض مدمج لـ DICOM): بدون القدرة، يفشل الفتح:

LicenseException: This document type requires the 'Dicom' plugin license.

رخصة مؤقتة نشطة تمنح كل قدرة. هذا مفاجأة شائعة عند الانتقال إلى الإنتاج: نفس أسطر AddPlugin التي تم تشغيلها أثناء التقييم توقف الموقع عندما تحذف الرخصة المشتراة إحدى تلك القدرات. قارن IsCapabilityGranted(...) بما اشتريت قبل النشر. مع عدم وجود رخصة على الإطلاق، لا شيء يُمنح — الرخصة المفقودة ليست رخصة مؤقتة.

نفس القيد يصل إلى المتصفح: Viewer.ReferenceScripts() وReferenceCss() تُصدر الملفات للميزات المقيدة بالرخصة (البحث، التعليق) فقط عندما تمنحها الرخصة، لذا لا تعرض الصفحة ميزة يرفضها الخادم.

خريطة الميزات والإضافات

التعليق والبحث لا يستخدمان AddPlugin<TPlugin>(). للمحوّل وDICOM كل منهما صفحة تحت الإضافات مع تكوينهما واستخدامهما. في هذه الحزمة، يُظهر DICOM الصفحات والإطارات والرسوم المتحركة، لكنه لا يقرأ البيانات الوصفية التقنية — راجع إضافة DICOM.

عارضات مخصصة — معالج الصيغة الخاص بك

يمكنك توصيل عارض إلى خط الأنابيب دون كتابة حزمة إضافة، مباشرةً في Application_Start:

Doconut.DoconutHost.Initialize(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),                        // يطبق IFormatViewer
        () => new ImageConfig { ImageResolution = 150 });  // إعداد افتراضي اختياري
});

تأخذ العارضات المخصصة أولوية على كل شيء — المدمجات والإضافات على حد سواء — ولا تُقيد بالرخصة: فهي شفرتك. عندما لا تزود تكوينًا افتراضيًا، يستخدم المصنع ImageConfig.

الخلاصات

• تُسجَّل الإضافات صراحةً في DoconutHost.Initialize، وتُتحقق قدراتها هناك؛ إذ تُوقف الحقوق المفقودة الموقع بـ 500 فارغ، والسبب في سجل أحداث Windows.
• الإضافات ذات النمط المتجاوز تتدهور بشكل سلس؛ الصيغ الخاصة بالإضافات فقط تفشل بـ LicenseException.
• رخصة مؤقتة نشطة تفتح كل شيء؛ الإنتاج يفتح ما اشتريت. تحقق مع IDoconutLicenseService قبل النشر.