DoconutOptions – Doconut الوثائق

DoconutOptions (المساحة Doconut) هو كائن التكوين الوحيد لكامل SDK. تقوم بتكوينه مرة واحدة داخل AddDoconut()، ويتم تسجيله ككائن مفرد.

هذا يمثل تغييرًا في الموقع بقدر ما هو تغيير في الشكل. في مكتبة .NET Standard السابقة، تم إنشاء مثيل DoconutOptions في وقت خط الأنابيب وتم تمريره إلى UseDoconut(new DoconutOptions { … }). هنا لا يأخذ middleware أي خيارات على الإطلاق — كل شيء يتم ضبطه أثناء تسجيل الخدمة.

csharp

builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

الخصائص

النوع	الخاصية	القيمة الافتراضية	الوصف
`bool`	`ShowDoconutInfo`	`false`	عند `true`، يُعيد طلب middleware بدون رمز مميز شريط نسخة بدلاً من 404. مفيد كفحص سريع؛ اتركه `false` في بيئة الإنتاج.
`bool`	`UnsafeMode`	`false`	عند `true`، يتخطى فحص أمان جلسة ASP.NET على طلبات الصفحات. اتركه `false` في بيئة الإنتاج على عقدة واحدة (انظر المفاهيم الأساسية → الجلسات والأمان). كان يُكتب سابقًا `UnSafeMode`.
`string`	`MiddlewarePath`	`"/doconut"`	قيمة التنسيق لنقطة النهاية page-image. يتم التحقق منها، لكنها لا تُنشئ فرعًا في خط الأنابيب؛ حافظ على توافقها مع تعيين `UseDoconut()` الفعلي ومسار العميل `BasePath`.
`string`	`ResourcesPath`	`"/doconut-res"`	بادئة مسار URL للموارد المدمجة من نوع JS/CSS/صورة/خط.
`string`	`LicensePath`	`""`	مسار ملف الترخيص. إذا كان فارغًا → المصدر التالي للترخيص، ثم الاكتشاف التلقائي؛ إذا لم يُعثر على شيء → حالة تقييم مائية العلامة بدون أي قدرات.
`string`	`LicenseContent`	`""`	محتوى الترخيص XML الخام (قاعدة بيانات، متغير بيئة، مدير أسرار). له أولوية أعلى من `LicensePath`.
`Stream?`	`LicenseStream`	`null`	الترخيص كتيار، يُقرأ مرة واحدة عند بدء التشغيل. له أولوية أعلى من كلا المصدرين الآخرين.
`bool`	`ResetLicense`	`false`	علامة توافق محجوزة. التنفيذ الحالي لا يستخدمها؛ أعد تشغيل التطبيق بعد استبدال الترخيص.
`DoconutPluginRegistry`	`PluginRegistry`	—	سجل للقراءة فقط يجمع مساهمات الإضافات؛ يُستهلك بواسطة مصنع العارض. يُملأ عبر `AddPlugin<T>()`.

أولوية الترخيص (تُفرض عند تسجيل الخدمة): LicenseStream → LicenseContent → LicensePath → الاكتشاف التلقائي (انظر البدء → إعداد الترخيص).

الأساليب

AddPlugin()

text

DoconutOptions AddPlugin<TPlugin>() where TPlugin : IDoconutPlugin, new()

استخدم هذه الطريقة للحزم المُصدرة من Converter و DICOM التي تتطلب اختيارًا. التعليقات والبحث العادي هي ميزات مرخصة مدمجة ولا تستخدم AddPlugin<TPlugin>().

يسجل إضافة أولية (Converter، DICOM). طريقة سلسة — تُعيد مثيل الخيارات. AddDoconut() يرمي InvalidOperationException في حالة عدم وجود ترخيص، ملف TRIAL قديم، أو ترخيص مدفوع لا يمنح قدرة الإضافة. تُحفظ التسجيلات المؤقتة/التجريبية بعد انتهاء الصلاحية وتصبح خاضعة للبوابة الزمنية (انظر المفاهيم الأساسية → نظام الإضافات).

يتم تمكين عنصر واجهة Converter الاختياري عبر AddConverterWidget() ويظهر من خلال الخاصية للقراءة فقط ConverterWidget؛ خياراته موثقة في صفحة إضافة Converter (الإضافات → إضافة Converter).

RegisterViewer(extension, factory, defaultConfig?)

text

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — leading dot optional
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

يسجل عارضًا مخصصًا لامتداد ملف. العارضات المخصصة لها أولوية أعلى من العارضات المدمجة وإضافات العارض ولا تخضع لقيود الترخيص. عندما يُحذف defaultConfig ويفتح مستند بدون تكوين صريح، يُستخدم ImageConfig.

يرمي ArgumentException (Extension must be a non-empty file extension.) إذا كان الامتداد فارغًا، وArgumentNullException إذا كان المصنع null.

التحقق من بدء التشغيل

AddDoconut() يتحقق من الخيارات بسرعة الفشل، لذا تُظهر الأخطاء في التكوين كاستثناء واضح عند بدء التشغيل بدلاً من 404 المربكة وقت الطلب:

text

DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

التكوينات الشائعة

csharp

// Production: explicit license, everything locked down (all security defaults)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Custom paths (e.g. to avoid a route conflict)
builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});

عند تغيير ResourcesPath، حافظ على توافق ResPath في عنصر واجهة العميل (انظر ViewerConfig). هذا أحد إعدادين للعميل يسبب فشلًا دون رسالة خطأ.

MiddlewarePath ليس مكوّن مسارات ASP.NET Core تلقائيًا. إذا كان يجب على Doconut الرد فقط تحت بادئة مخصصة، قم بتركيب UseDoconut() على ذلك الفرع (مثلاً باستخدام app.Map("/docs-engine", branch => branch.UseDoconut())) واضبط BasePath للعميل على نفس عنوان URL. تطبيق المرجع بدلاً من ذلك يحافظ على شكل طلب DocImage.axd التاريخي على فرع MapWhen مع BasePath: '/'.