DoconutOptions

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

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

builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

ویژگی‌ها

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

متدها

افزودن‌افزونه()

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

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

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

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

ثبت‌نمایشگر(extension, factory, defaultConfig?)

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های گیج‌کنندهٔ زمان درخواست:

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.

پیکربندی‌های رایج

// 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 تنظیم کنید. برنامهٔ مرجع به‌جای آن شکل درخواست تاریخی DocImage.axd را بر شاخهٔ MapWhen با BasePath: '/' حفظ می‌کند.