سیستم افزونه‌ها

گسترش نمایشگر با افزونه‌ها

هسته Doconut ساده و کم‌وزن می‌ماند؛ عملکردهای اختیاری به‌صورت افزونه‌ها — بسته‌های NuGet جداگانه‌ای که نمایشگرها یا سرویس‌ها را اضافه می‌کنند و توسط لایسنس شما فعال می‌شوند — ارائه می‌شوند. این صفحه مدل ثبت‌نام، رفتار محدودیت لایسنس در زمان اجرا، و نحوه افزودن نمایشگر خودتان را توضیح می‌دهد.

ثبت یک افزونه

هر بسته افزونه یک کلاس افزونه را افشا می‌کند. شما آن را یک‌بار، هنگام راه‌اندازی ثبت می‌کنید:

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddPlugin<TPlugin>() یک نمونه از افزونه ایجاد می‌کند و فراخوانی Register خود را در مقابل رجیستری افزونه که بر روی DoconutOptions نگهداری می‌شود، اجرا می‌کند. همه چیزهایی که یک افزونه اضافه می‌کند با قابلیت مورد نیاز افزونه برچسب‌گذاری می‌شود. AddDoconut() بلافاصله افزونه‌های ثبت‌شده را اعتبارسنجی می‌کند: لایسنس گمشده، فایل قدیمی TRIAL، یا لایسنس پولی بدون این قابلیت، راه‌اندازی را با InvalidOperationException متوقف می‌کند. یک ثبت‌نام Temporary/Demo تا پس از انقضا حفظ می‌شود، اما قابلیت‌های زمان اجرای آن پس از تاریخ انقضا لغو می‌شوند.

قرارداد

یک افزونه یک رابط به‌طور عمدی کوچک پیاده‌سازی می‌کند:

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // مثلاً "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // دروازهٔ مجوز
    void Register(IDoconutPluginBuilder builder); // مشارکت در نمایشگرها/سرویس‌ها
}

در داخل Register، سازنده دو نوع مشارکت را می‌پذیرد:

  • builder.RegisterViewer(extension, factory) — یک نمایشگر برای پسوند فایل؛ کارخانه یک IFormatViewer برمی‌گرداند (افزونه DICOM به این روش .dcm و .ima را ثبت می‌کند)،
  • builder.RegisterService<TContract>(() => …) — یک سرویس تایپ‌شده که بخش‌های دیگر خط لوله می‌توانند آن را جستجو کنند.

قابلیت‌ها و محدودیت‌ها

قابلیت‌ها واحدهای لایسنس هستند. Converter، Dicom و Signer به‌عنوان افزونه‌های اختیاری عرضه می‌شوند؛ Search و Annotation ویژگی‌های داخلی هستند که به‌همین شکل محدود می‌شوند. نمایشگر پایه یک قابلیت نیست — بلکه پیش‌نیاز است که به عنوان IsViewerLicensed در سرویس لایسنس نمایش داده می‌شود.

اعتبارسنجی هنگام راه‌اندازی به‌طور معمول مانع از ورود یک افزونه بدون لایسنس به خط لوله درخواست می‌شود. کارخانه نمایشگر همچنین دو قانون زمان اجرای دفاعی اعمال می‌کند که در صورت تغییر حق دسترسی پس از راه‌اندازی مهم هستند:

  • افزونه یک نمایشگر داخلی را بازنویسی می‌کند (یک افزونه پسوندی را ادعا می‌کند که رجیستری داخلی نیز آن را مدیریت می‌کند): با داشتن قابلیت مجاز، نمایشگر افزونه برنده می‌شود؛ بدون آن، Doconut به‌صورت ساکن به نمایشگر داخلی باز می‌گردد. کاربران همچنان سند خود را می‌بینند — فقط ویژگی افزونه را دریافت نمی‌کنند.
  • قالب فقط افزونه‌ای (.dcm و .ima — DICOM نمایشگر داخلی ندارد): بدون داشتن قابلیت، فراخوانی باز کردن به‌صورت سخت‌گیرانه شکست می‌خورد:
text
LicenseException: This document type requires the 'Dicom' plugin license.

یک لایسنس Temporary فعال همه قابلیت‌ها را اعطا می‌کند (با نمایش پایه تمیز و بدون واترمارک). این منبع کلاسیک شگفتی‌های زمان راه‌اندازی است: ثبت همان افزونه‌ها با لایسنس خریداری‌شده که یکی از قابلیت‌های آن‌ها را حذف کرده، باعث می‌شود AddDoconut() در هنگام راه‌اندازی شکست بخورد. قبل از استقرار، IsCapabilityGranted(...) را با برنامه خود مقایسه کنید. طرف دیگر: با بدون هیچ لایسنس، هیچ‌چیزی اعطا نمی‌شود — یک لایسنس گمشده لایسنس Temporary نیست.

همان محدودیت در سمت مشتری نیز ظاهر می‌شود: Viewer.ReferenceScripts() و ReferenceCss() بسته‌های اسکریپت/استایل مربوط به ویژگی‌های محدود شده توسط لایسنس (جستجو، حاشیه‌نویسی، …) را فقط زمانی که لایسنس آن‌ها را فعال می‌کند، تولید می‌کنند، به‌طوری که رابط کاربری ویجت با آنچه سرور واقعاً انجام می‌دهد، سازگار بماند.

نقشه ویژگی‌ها و افزونه‌ها

رابط کاربری محصول از واژه «افزونه» به‌عنوان برچسب کلی ویژگی استفاده می‌کند، اما ثبت‌نام سرور متفاوت است:

ویژگیچگونه فعال می‌شودقابلیتمشارکت می‌کند
حاشیه‌نویسیدرون نمایشگر تعبیه شده؛ شامل منابع حاشیه‌نویسیAnnotationنویسندگی مرورگر، حفظ نشست، و خروجی‌های سوزانده‌شده
جستجودرون نمایشگرهای فرمت قابل جستجو تعبیه شده؛ شامل منابع جستجو و فعال‌سازی استخراج در صورت نیازSearchفهرست متن بومی، برجسته‌سازی‌ها، و ناوبری نتایج
مبدلنصب Doconut.NET8.Converter و ثبت ConverterPluginConverterسرویس تبدیل C# و ویجت وب اختیاری
DICOMنصب Doconut.NET8.Dicom و ثبت DicomPluginDicomنمایش تصویر پزشکی برای .dcm و .ima
امضا کنندهنصب Doconut.NET8.Signer و ثبت SignerPluginSignerامضاهای قابل مشاهده و مهرهای دیجیتال برای PDF و Word: سرویس امضای C# و یک ویجت وب اختیاری

حاشیه‌نویسی و جستجوی معمولی از AddPlugin<TPlugin>() استفاده نمی‌کنند؛ بسته‌های آن‌ها فقط زمانی تولید می‌شوند که لایسنس قابلیت مربوطه را اعطا کند. مبدل، DICOM و امضا کننده پیاده‌سازی‌های IDoconutPlugin اختیاری هستند.

بسته‌های افزونه منتشر شده

افزونهبستهقابلیتمشارکت می‌کند
مبدلDoconut.NET8.ConverterConverterقابلیت تبدیل سند
DICOMDoconut.NET8.DicomDicomنمایش تصویر پزشکی (.dcm و .ima — قالب‌های فقط افزونه‌ای)
امضا کنندهDoconut.NET8.SignerSignerامضای PDF و Word

هر کدام صفحه اختصاصی خود را زیر افزونه‌ها دارند که شامل پیکربندی و نحوه استفاده است.

نمایشگرهای سفارشی — پردازشگر فرمت خودتان

می‌توانید یک نمایشگر را مستقیماً از Program.cs به خط لوله متصل کنید بدون اینکه بسته افزونه‌ای بنویسید:

csharp
builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // پیاده‌سازی IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // پیکربندی پیش‌فرض اختیاری
});

// دستگیرهٔ قالبی که کارخانه ایجاد می‌کند. این اعضا را با رندرینگ خودتان جایگزین کنید.
public sealed class MyCustomViewer : Doconut.Core.Interfaces.IFormatViewer
{
    public ViewerType ViewerType => ViewerType.None;
    public int TotalPages => 0;
    public int DefaultWidth => 0;
    public int DefaultHeight => 0;
    public bool PreferOcr => false;

    public Task LoadAsync(Stream documentStream, BaseConfig config, CancellationToken ct = default)
        => Task.CompletedTask;

    public Task<byte[]> GetPageImageAsync(int pageNumber, CancellationToken ct = default)
        => Task.FromResult(Array.Empty<byte>());

    public void Dispose() { }
}

نمایشگرهای سفارشی بر همه — داخلی‌ها و افزونه‌ها — اولویت دارند و تحت محدودیت لایسنس نیستند (کد شما هستند). کارخانه در صورت عدم ارائه پیکربندی پیش‌فرض، به یک ImageConfig باز می‌گردد.

نکات کلیدی

  • افزونه‌ها به‌صورت صریح ثبت می‌شوند و LicenseCapability آن‌ها در طول AddDoconut() اعتبارسنجی می‌شود — عدم وجود یا ناتوانی حق دسترسی غیر موقت، به‌سرعت شکست می‌خورد.
  • افزونه‌های سبک بازنویسی به‌صورت ملایم کاهش می‌یابند؛ قالب‌های فقط افزونه‌ای با یک LicenseException شکست می‌خورند.
  • یک لایسنس Temporary فعال همه چیز را باز می‌کند؛ لایسنس تولید آنچه خریداری کرده‌اید را باز می‌کند. قبل از انتشار، با IDoconutLicenseService تأیید کنید.

آیا این صفحه مفید بود؟