نظام الملحقات

توسيع العارض باستخدام الملحقات

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

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

تسجيل ملحق

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

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

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

العقد

يُطبق الملحق واجهة صغيرة عمدًا:

csharp
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 و Signer تُوزَّع كملحقات اختيارية؛ Search و Annotation هي ميزات مدمجة تُتحكم بنفس الطريقة. العارض الأساسي ليس قدرة — إنه المتطلب المسبق، يُعرض كـ IsViewerLicensed على خدمة الترخيص.

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

  • الملحق يتجاوز عارضًا مدمجًا (ملحق يطالب بامتداد يتعامل معه السجل المدمج أيضًا): إذا كانت القدرة مرخصة، ينتصر عارض الملحق؛ بدونها، ينسحب Doconut بهدوء إلى العارض المدمج. لا يزال المستخدمون يرون مستنداتهم — لكنهم لا يحصلون على ميزة الملحق.
  • صيغة خاصة بالملحق (.dcm و .ima — لا يوجد عارض مدمج لـ DICOM): بدون القدرة فشل استدعاء الفتح بشكل حاد:
text
LicenseException: This document type requires the 'Dicom' plugin license.

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

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

خريطة الميزات والملحقات

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

الميزةطريقة التفعيلالقدرةالمساهمة
التعليقمدمج في العارض؛ يشمل موارد التعليقAnnotationإنشاء المتصفح، حفظ الجلسة، وتصديرات مدمجة
البحثمدمج في عارضات الصيغ القابلة للبحث؛ يشمل موارد البحث ويفعل الاستخراج حيثما يلزمSearchفهرس نصي أصلي، تمييز، وتصفح النتائج
المحولتثبيت Doconut.NETStandard.Converter وتسجيل ConverterPluginConverterخدمة تحويل C# وودجت ويب اختياري
DICOMتثبيت Doconut.NETStandard.Dicom وتسجيل DicomPluginDicomعرض الصور الطبية لـ .dcm و .ima
الموقعتثبيت Doconut.NETStandard.Signer وتسجيل SignerPluginSignerتوقيعات مرئية وأختام رقمية لـ PDF و Word: خدمة توقيع C# وودجت ويب اختياري

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

حزم الملحقات المُصدرة

الملحقالحزمةالقدرةالمساهمة
المحولDoconut.NETStandard.ConverterConverterقدرة تحويل المستند
DICOMDoconut.NETStandard.DicomDicomعرض الصور الطبية (.dcm و .ima — صيغ خاصة بالملحق)
الموقعDoconut.NETStandard.SignerSignerتوقيع PDF و Word

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

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

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

csharp
builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // تنفذ IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // إعداد افتراضي اختياري
});

// معالج الصيغة الذي تنشئه المصنع. استبدل هذه الأعضاء بالعرض الخاص بك.
public sealed class MyCustomViewer : Doconut.Core.Interfaces.IFormatViewer
{
    public ViewerType ViewerType => ViewerType.None;
    public int TotalPages => 0;
    public int DefaultWidth => 0;
    public int DefaultHeight => 0;
    public bool PreferOcr => false;

    public Task LoadAsync(Stream documentStream, BaseConfig config, CancellationToken ct = default)
        => Task.CompletedTask;

    public Task<byte[]> GetPageImageAsync(int pageNumber, CancellationToken ct = default)
        => Task.FromResult(Array.Empty<byte>());

    public void Dispose() { }
}

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

الخلاصات

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

هل كانت هذه الصفحة مفيدة؟