DoconutOptions – Doconut الوثائق

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

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`، يُعيد طلب الوسيط دون رمز مميز شريط نسخة (`Doconut <version> is running on <host>`) بدلاً من 404. مفيد كفحص سريع؛ اتركه `false` في بيئة الإنتاج.
`bool`	`UnsafeMode`	`false`	عند `true`، يتخطى فحص أمان جلسة ASP.NET في طلبات الصفحات. اتركه `false` في بيئة الإنتاج (انظر المفاهيم الأساسية → الجلسات والأمان).
`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`	علامة توافق محجوزة. لا يستخدمها تنفيذ .NET 6 الحالي؛ أعد تشغيل التطبيق بعد استبدال الترخيص.
`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" — leading dot optional
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

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

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

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

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.