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<TPlugin>()

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" — النقطة في البداية اختيارية
    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

// الإنتاج: ترخيص صريح، كل شيء مقفل (جميع إعدادات الأمان الافتراضية)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// مسارات مخصصة (مثلاً لتجنب تعارض المسار)
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: '/'.