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

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

تسجيل إضافة

كل حزمة إضافة تُظهر فئة إضافة واحدة. تقوم بتسجيلها مرة واحدة، عند بدء التشغيل:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddPlugin<TPlugin>() تنشئ الإضافة وتستدعي رد النداء Register الخاص بها على سجل الإضافات الموجود في DoconutOptions. كل ما تُسهِم به الإضافة يُوسم بـ القدرة المطلوبة للإضافة. AddDoconut() يتحقق من الإضافات المسجلة فورًا: ترخيص مفقود، ملف TRIAL قديم، أو ترخيص مدفوع بدون القدرة يؤدي إلى فشل بدء التشغيل بـ InvalidOperationException. يُحتفظ بتسجيل مؤقت/تجريبي عبر الانتهاء، لكن تُسحب قدراته أثناء التشغيل بعد تاريخ الانتهاء.

العقد

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

public interface IDoconutPlugin
{
    string Name { get; }                          // e.g. "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // the license gate
    void Register(IDoconutPluginBuilder builder); // contribute viewers/services
}

داخل Register، يقبل الباني نوعين من المساهمات:

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

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

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

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

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

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

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

نفس التقييد يظهر على جانب العميل: Viewer.ReferenceScripts() و ReferenceCss() تُصدر حزم السكريبت/النمط للميزات المقيدة بالترخيص (search, annotation, …) فقط عندما يتيح الترخيص ذلك، وبالتالي يبقى واجهة الودجت متسقة مع ما سيقوم به الخادم فعليًا.

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

تستخدم واجهة المنتج كلمة “plugin” كعلامة ميزة شاملة، لكن تسجيل الخادم يختلف:

حزم الإضافات الصادرة

لكل منها صفحة مخصصة تحت الإضافات مع تكوينها واستخدامها.

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

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

builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // implements IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // optional default config
});

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

الخلاصات

• تُسجل الإضافات صراحةً ويتم التحقق من LicenseCapability الخاصة بها أثناء AddDoconut() — الفقدان أو عدم كفاية الاستحقاق غير المؤقت يؤدي إلى فشل سريع.
• الإضافات ذات نمط التجاوز تتدهور بشكل سلس؛ الصيغ الخاصة بالإضافة تفشل مع LicenseException.
• ترخيص مؤقت نشط يفتح كل شيء؛ الترخيص الإنتاجي يفتح ما اشتريته. تحقق باستخدام IDoconutLicenseService قبل النشر.