سیستم افزونه

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

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

ثبت یک افزونه

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

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// یک افزونه ثبت‌شده که مجوز آن موجود نیست در اینجا، در Application_Start، پرتاب می‌شود و
// سایت سپس به هر درخواست با یک خطای 500 خالی پاسخ می‌دهد. دلیل آن در لاگ رویدادهای ویندوز است.

AddPlugin<TPlugin>() افزونه را ایجاد می‌کند و اجازه می‌دهد مشارکت‌های خود را با DoconutOptions ثبت کند. همهٔ آنچه یک افزونه اضافه می‌کند با قابلیت مورد نیاز افزونه برچسب‌گذاری می‌شود، و DoconutHost.Initialize هر افزونهٔ ثبت‌شده را نسبت به مجوز قبل از اینکه سایت اولین درخواست را سرو کند، بررسی می‌کند.

یک مجوز افزونهٔ گمشده سایت را متوقف می‌کند

وقتی هیچ مجوز فعال قابلیت افزونهٔ ثبت‌شده‌ای را اعطا نمی‌کند — هیچ مجوزی وجود ندارد، یک فایل TRIAL قدیمی، یا یک مجوز پرداخت‌شده بدون آن قابلیت — DoconutHost.Initialize استثنایی از InvalidOperationException در Application_Start پرتاب می‌کند:

text
The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

در System.Web، استثنایی در Application_Start صفحهٔ خطایی تولید نمی‌کند. هر درخواست پاسخی خالی از نوع 500 می‌دهد، لاگ IIS هیچ اطلاعات مفیدی نشان نمی‌دهد، و پیام فقط در لاگ رویداد ویندوز (لاگ برنامه، منبع ASP.NET) ظاهر می‌شود. وقتی سایتی بلافاصله پس از افزودن یک خط AddPlugin پاسخ نمی‌دهد، ابتدا فایل‌های مجوز را در wwwroot بررسی کنید — به License Setup مراجعه کنید.

قرارداد

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

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.

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

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

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

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

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

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

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

csharp
Doconut.DoconutHost.Initialize(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 استفاده می‌کند.

نکات کلیدی

  • افزونه‌ها به‌صورت صریح در DoconutHost.Initialize ثبت می‌شوند و قابلیت‌هایشان در آنجا اعتبارسنجی می‌شود؛ یک حق دسترسی گمشده سایت را با یک 500 خالی که دلیل آن در لاگ رویداد ویندوز است، متوقف می‌کند.
  • افزونه‌های سبک بازنویسی به‌صورت ملایم کاهش می‌یابند؛ فرمت‌های فقط افزونه‌ای با یک LicenseException شکست می‌خورند.
  • یک مجوز موقت فعال همه چیز را باز می‌کند؛ محیط تولید آنچه خریداری کرده‌اید را باز می‌کند. قبل از انتشار با IDoconutLicenseService بررسی کنید.

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