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

نواة 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(".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() تُصدر حزم السكريبت/النمط للميزات المقيدة بالرخصة (البحث، التعليق، …) فقط عندما تُفعل الرخصة تلك الميزات، لذا يظل واجهة الودجت متسقة مع ما سيقوم به الخادم فعليًا.

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

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

التعليق والبحث العادي لا يستخدمان 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 قبل الإرسال.