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>();
});

Properties

نوع	ویژگی	پیش‌فرض	توضیح
`bool`	`ShowDoconutInfo`	`false`	وقتی `true` باشد، درخواست میدلور بدون توکن بنر نسخه (`Doconut <version> is running on <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 6 از آن استفاده نمی‌کند؛ پس از تعویض لایسنس برنامه را مجدداً راه‌اندازی کنید.
`DoconutPluginRegistry`	`PluginRegistry`	—	رجیستری فقط‑خواندنی که مشارکت‌های افزونه را جمع‌آوری می‌کند؛ توسط کارخانهٔ نمایشگر مصرف می‌شود. از طریق `AddPlugin<T>()` پر کنید.

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

Methods

AddPlugin<TPlugin>()

text

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

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

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

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

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.») و برای کارخانهٔ null ArgumentNullException پرتاب می‌کند.

Startup validation

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.

Common configurations

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 تنظیم کنید.