نظام الإضافات
توسيع عارض المستندات باستخدام الإضافات
نواة Doconut تظل خفيفة؛ الوظائف الاختيارية تُوزَّع كـ إضافات — حزم NuGet منفصلة تُضيف عارضات أو خدمات وتُفعَّل بواسطة رخصتك. تشرح هذه الصفحة نموذج التسجيل، ما يحدث عند بدء التشغيل عندما لا تغطي الرخصة إضافةً ما، وكيفية توصيل عارضك الخاص.
تسجيل إضافة
كل حزمة إضافة تُظهر فئة إضافة واحدة. سجِّلها مرة واحدة في Application_Start:
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:
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 — انظر إعداد الرخصة.
العقد
تُنفّذ الإضافة واجهة صغيرة عن عمد:
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): بدون القدرة، يفشل الفتح:
LicenseException: This document type requires the 'Dicom' plugin license.رخصة مؤقتة نشطة تمنح كل القدرة. هذه مفاجأة شائعة عند الإطلاق: نفس سطور AddPlugin التي تم تشغيلها أثناء التقييم تُوقف الموقع عندما تُغفل الرخصة المشتراة إحدى تلك القدرات. قارن IsCapabilityGranted(...) بما اشتريت قبل النشر. مع عدم وجود رخصة على الإطلاق، لا شيء يُمنح — الرخصة المفقودة ليست رخصة مؤقتة.
نفس القيد يصل إلى المتصفح: Viewer.ReferenceScripts() وReferenceCss() تُصدر الملفات للميزات المقيدة بالرخصة (البحث، التعليق) فقط عندما تمنح الرخصة إياها، لذا لا تعرض الصفحة أي ميزة سيرفضها الخادم.
خريطة الميزات والإضافات
| الميزة | طريقة التفعيل | القدرة | المساهمة |
|---|---|---|---|
| التعليق | مدمج في العارض؛ يشمل موارد التعليق | Annotation | إنشاء التعليقات في المتصفح، حفظ الجلسة، تصدير مدمج |
| البحث | مدمج في عارضات الصيغ القابلة للبحث؛ يشمل موارد البحث | Search | فهرس نصي أصلي، تمييز، تنقل بين النتائج |
| المحول | ثبّت Doconut.NETFramework.Converter وسجِّل ConverterPlugin | Converter | خدمة تحويل C# وودجت ويب اختياري |
| DICOM | ثبّت Doconut.NETFramework.Dicom وسجِّل DicomPlugin | Dicom | عرض صور طبية لـ .dcm و.ima |
| الموقّع | ثبّت Doconut.NETFramework.Signer وسجِّل SignerPlugin | Signer | توقيعات مرئية وأختام رقمية لـ PDF وWord: خدمة توقيع C# وودجت ويب اختياري |
لا تستخدم كل من التعليق والبحث AddPlugin<TPlugin>(). لكل من المحول وDICOM والموقّع صفحة تحت الإضافات مع إعداداتها واستخدامها. في هذه الحزمة، يُظهر DICOM الصفحات والإطارات والرسوم المتحركة، لكنه لا يقرأ البيانات الوصفية التقنية — انظر إضافة DICOM.
عارضات مخصصة — معالج تنسيقك الخاص
يمكنك توصيل عارض إلى خط الأنابيب دون كتابة حزمة إضافة، مباشرةً في Application_Start:
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قبل النشر.
هل كانت هذه الصفحة مفيدة؟