DoconutOptions – Doconut مستندات

DoconutOptions (فضای‌نام Doconut) یک شیء پیکربندی تک برای کل SDK است. شما آن را یک بار، داخل AddDoconut()، پیکربندی می‌کنید و به‌عنوان یک تک‌نمونه (singleton) ثبت می‌شود.

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> در حال اجرا بر روی <host>`) را به‌جای 404 برمی‌گرداند. برای بررسی سریع مفید است؛ در محیط تولید مقدار `false` را نگه دارید.
`bool`	`UnsafeMode`	`false`	وقتی `true` باشد، بررسی امنیتی نشست ASP.NET را در درخواست‌های صفحه نادیده می‌گیرد. در محیط تولید مقدار `false` را نگه دارید (به مفاهیم اصلی → نشست‌ها و امنیت مراجعه کنید).
`string`	`MiddlewarePath`	`"/doconut"`	مقدار هماهنگی برای نقطه انتهایی صفحه‑تصویر. اعتبارسنجی می‌شود، اما شاخه‌ای از خط لوله را سوار نمی‌کند؛ آن را با نگاشت واقعی `UseDoconut()` و `BasePath` مشتری هم‌راستا نگه دارید.
`string`	`ResourcesPath`	`"/doconut-res"`	پیشوند مسیر URL برای منابع جاسازی‌شده JS/CSS/تصویر/فونت.
`string`	`LicensePath`	`""`	مسیر فایل لایسنس. خالی → منبع لایسنس بعدی، سپس کشف خودکار؛ اگر چیزی یافت نشود → حالت ارزیابی با واترمارک و بدون قابلیت‌ها.
`string`	`LicenseContent`	`""`	محتوای خام XML لایسنس (پایگاه داده، متغیر محیطی، مدیر راز). بر `LicensePath` اولویت دارد.
`Stream?`	`LicenseStream`	`null`	لایسنس به‌صورت جریان، یک‌بار در زمان راه‌اندازی خوانده می‌شود. بر هر دو منبع دیگر اولویت دارد.
`bool`	`ResetLicense`	`false`	پرچم سازگاری رزرو شده. پیاده‌سازی فعلی .NET 8 از آن استفاده نمی‌کند؛ پس از تعویض لایسنس برنامه را مجدداً راه‌اندازی کنید.
`DoconutPluginRegistry`	`PluginRegistry`	—	رجیستری فقط‑خواندنی که مشارکت‌های افزونه را جمع‌آوری می‌کند؛ توسط کارخانه نمایشگر مصرف می‌شود. از طریق `AddPlugin<T>()` پر کنید.

اولویت لایسنس (در زمان ثبت سرویس اعمال می‌شود): LicenseStream → LicenseContent → LicensePath → کشف خودکار (به شروع کار → تنظیم لایسنس مراجعه کنید).

متدها

AddPlugin()()

این متد برای بسته‌های Converter و DICOM که به‌صورت opt‑in منتشر شده‌اند، استفاده می‌شود. حاشیه‌نویسی و جستجوی معمولی ویژگی‌های لایسنس‌دار داخلی هستند و نیازی به AddPlugin<TPlugin>() ندارند.

یک افزونه داخلی (Converter، DICOM) را ثبت می‌کند. به‑صورت fluent — نمونه گزینه‌ها را برمی‌گرداند. AddDoconut() در صورت عدم وجود لایسنس، فایل قدیمی TRIAL یا لایسنس پرداختی که قابلیت افزونه را ندهد، InvalidOperationException پرتاب می‌کند. ثبت‌نام‌های موقت/دموی پس از انقضا حفظ می‌شوند و تحت دروازه زمان اجرا قرار می‌گیرند (به مفاهیم اصلی → سیستم افزونه‌ها مراجعه کنید).

ویجت Converter که به‌صورت opt‑in فعال می‌شود با AddConverterWidget() فعال می‌گردد و از طریق ویژگی فقط‑خواندنی ConverterWidget در دسترس است؛ گزینه‌های آن در صفحه افزونه Converter مستند شده‌اند (افزونه‌ها → افزونه Converter).

RegisterViewer(extension, factory, defaultConfig?)

یک نمایشگر سفارشی برای پسوند فایل ثبت می‌کند. نمایشگرهای سفارشی بر نمایشگرهای داخلی و افزونه‌ها اولویت دارند و تحت محدودیت لایسنس نیستند. وقتی 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 تنظیم کنید.