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

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

هذا النموذج جديد في هذا الإصدار. مكتبة .NET Standard السابقة لم يكن لديها سجل إضافات: كان التحويل موجودًا في العارض نفسه وتم تثبيت تراخيص الإضافات عبر استدعاءات ثابتة Viewer.SetLicensePlugin(...). لا يُعد أي منهما آلية تسجيل هنا.

تسجيل إضافة

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

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; }                          // مثلاً "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // بوابة الترخيص
    void Register(IDoconutPluginBuilder builder); // ساهم في عارضات/خدمات
}

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

• builder.RegisterViewer(extension, factory) — عارض لامتداد ملف؛ تُعيد المصنع IFormatViewer (تُسجل إضافة DICOM .dcm و.ima بهذه الطريقة)،
• 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() تُصدر حزم السكريبت/النمط للميزات المقيدة بالرخصة (البحث، التعليق، …) فقط عندما تُفعل الرخصة هذه الميزات، لذا يظل واجهة الودجت متسقة مع ما سيقوم به الخادم فعليًا.

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

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

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

التحف .NET Standard المعتمدة تحتوي على Doconut.NETStandard.Converter وDoconut.NETStandard.Dicom بنفس نسخة الحزمة الأساسية.

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

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

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

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

builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // يطبق IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // تهيئة افتراضية اختيارية
});

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

الخلاصات

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