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

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

تسجيل إضافة

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

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

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

العقد

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

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 نوعين من المساهمات:

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

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

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

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

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

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

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

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

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

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

Annotation و Search العادي لا يستخدمان AddPlugin<TPlugin>()؛ تُصدر حزمهم فقط عندما تُمنح الرخصة القدرة المقابلة. Converter و DICOM هما تنفيذات IDoconutPlugin الاختيارية المُصدرة لهذه المجموعة من الوثائق.

القطع المعتمدة لـ .NET 6 تحتوي على Doconut.NET6.Converter و Doconut.NET6.Dicom بنفس نسخة الحزمة الأساسية.

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

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

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

يمكنك توصيل عارض إلى خط الأنابيب دون كتابة حزمة 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 قبل الإطلاق.