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

قم بتمديد العارض باستخدام الإضافات

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

تسجيل إضافة

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

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

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

العقد

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

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.

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

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

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

تستخدم واجهة المنتج مصطلح “إضافة” كعلامة ميزة عامة، لكن تسجيل الخادم يختلف:

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

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

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

الإضافةالحزمةالقدرةالمساهمات
المحوّلDoconut.NET6.ConverterConverterقدرة تحويل المستندات
DICOMDoconut.NET6.DicomDicomعرض الصور الطبية (.dcm و.ima — صيغ خاصة بالإضافة)
الموقّعDoconut.NET6.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.
  • ترخيص مؤقت نشط يفتح كل شيء؛ الترخيص الإنتاجي يفتح ما اشتريت. تحقق من IDoconutLicenseService قبل النشر.

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