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

توسيع عارض المستندات بالإضافات

نواة 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.NET8.Converter وتسجيل ConverterPluginConverterخدمة تحويل C# وودجت ويب اختياري
DICOMتثبيت Doconut.NET8.Dicom وتسجيل DicomPluginDicomعرض الصور الطبية لـ .dcm و.ima
الموقعتثبيت Doconut.NET8.Signer وتسجيل SignerPluginSignerتوقيعات مرئية وأختام رقمية لـ PDF وWord: خدمة توقيع C# وودجت ويب اختياري

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

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

الإضافةالحزمةالقدرةالمساهمات
المحولDoconut.NET8.ConverterConverterقدرة تحويل المستندات
DICOMDoconut.NET8.DicomDicomعرض الصور الطبية (.dcm و.ima — صيغ خاصة بالإضافة فقط)
الموقعDoconut.NET8.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 قبل الإرسال.

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