DoconutOptions – مستندات Doconut

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

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

متدها

AddPlugin<TPlugin>()

text

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

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

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

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

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

اعتبارسنجی هنگام راه‌اندازی

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: مجوز صریح، همه چیز قفل شده (تمام پیش‌فرض‌های امنیتی)
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 تنظیم کنید.