DoconutOptions – مستندات Doconut

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

این تغییر هم در مکان و هم در شکل است. در کتابخانه قبلی .NET Standard، یک نمونه DoconutOptions در زمان لوله‌سازی ساخته می‌شد و به UseDoconut(new DoconutOptions { … }) تحویل داده می‌شد. در اینجا میدلور هیچ گزینه‌ای دریافت نمی‌کند — همه چیز در زمان ثبت سرویس تنظیم می‌شود.

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`، درخواست میدلور بدون توکن یک بنر نسخه به جای 404 برمی‌گرداند. برای بررسی سریع مفید است؛ در محیط تولید `false` را نگه دارید.
`bool`	`UnsafeMode`	`false`	زمانی که `true`، بررسی امنیتی ASP.NET‑session را در درخواست‌های صفحه نادیده می‌گیرد. در محیط تولید روی یک گره واحد `false` را نگه دارید (به Core Concepts → Sessions & Security مراجعه کنید). پیش از این به صورت `UnSafeMode` نوشته می‌شد.
`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`	پرچم سازگاری رزرو شده. پیاده‌سازی فعلی از آن استفاده نمی‌کند؛ پس از جایگزینی لایسنس، برنامه را مجدداً راه‌اندازی کنید.
`DoconutPluginRegistry`	`PluginRegistry`	—	ثبت‌نام فقط‑خواندنی که مشارکت‌های پلاگین را جمع‌آوری می‌کند؛ توسط کارخانه نمایشگر مصرف می‌شود. از طریق `AddPlugin<T>()` پر کنید.

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

متدها

AddPlugin<TPlugin>()

text

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

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

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

ویجت Converter که به‌صورت opt‑in فعال است با 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

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