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

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

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

تسجيل إضافة

كل حزمة إضافة تُظهر فئة إضافة واحدة. سجِّلها مرة واحدة في Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// ملحق مسجل لا توجد رخصته يُرمى هنا، في Application_Start، و الـ
// الموقع بعد ذلك يرد على كل طلب بخطأ 500 فارغ. السبب موجود في سجل أحداث Windows.

AddPlugin<TPlugin>() ينشئ الإضافة ويسمح لها بتسجيل مساهماتها مع DoconutOptions. كل ما تُضيفه الإضافة يُوسم بـ القدرة المطلوبة للإضافة، وDoconutHost.Initialize يتحقق من كل إضافة مسجلة مقابل الرخصة قبل أن يخدم الموقع طلبه الأول.

رخصة إضافة مفقودة تُوقف الموقع

عندما لا تمنح أي رخصة نشطة قدرة الإضافة المسجلة — لا رخصة على الإطلاق، ملف TRIAL قديم، أو رخصة مدفوعة بدون تلك القدرة — DoconutHost.Initialize يطرح InvalidOperationException من Application_Start:

text
The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

في System.Web، الاستثناء في Application_Start لا ينتج صفحة خطأ. كل طلب يرد بـ 500 فارغ، سجل IIS لا يُظهر شيئًا مفيدًا، وتظهر الرسالة فقط في سجل أحداث Windows (سجل التطبيقات، المصدر ASP.NET). عندما يتوقف الموقع عن الاستجابة مباشرةً بعد إضافة سطر AddPlugin، تحقق أولاً من ملفات الرخصة في wwwroot — انظر إعداد الرخصة.

العقد

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

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.

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

نفس القيد يصل إلى المتصفح: Viewer.ReferenceScripts() وReferenceCss() تُصدر الملفات للميزات المقيدة بالرخصة (البحث، التعليق) فقط عندما تمنح الرخصة إياها، لذا لا تعرض الصفحة أي ميزة سيرفضها الخادم.

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

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

لا تستخدم كل من التعليق والبحث AddPlugin<TPlugin>(). لكل من المحول وDICOM والموقّع صفحة تحت الإضافات مع إعداداتها واستخدامها. في هذه الحزمة، يُظهر DICOM الصفحات والإطارات والرسوم المتحركة، لكنه لا يقرأ البيانات الوصفية التقنية — انظر إضافة DICOM.

عارضات مخصصة — معالج تنسيقك الخاص

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

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),                        // يطبق IFormatViewer
        () => new ImageConfig { ImageResolution = 150 });  // إعداد افتراضي اختياري
});

// معالج الصيغة الذي تنشئه factory. استبدل هذه الأعضاء بعملية العرض الخاصة بك.
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.

الخلاصات

  • تُسجَّل الإضافات صراحةً في DoconutHost.Initialize، وتُتحقق قدراتها هناك؛ فعدم وجود حق يوقف الموقع بـ 500 فارغ يُوضح السبب في سجل أحداث Windows.
  • الإضافات ذات النمط المتجاوز تتدهور بسلاسة؛ تنسيقات الإضافة فقط تفشل مع LicenseException.
  • رخصة مؤقتة نشطة تفتح كل شيء؛ الإنتاج يفتح ما اشتريت. تحقق مع IDoconutLicenseService قبل النشر.

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