سیستم افزونه
گسترش نمایشگر با افزونهها
هسته Doconut ساده باقی میماند؛ عملکردهای اختیاری به صورت افزونهها عرضه میشوند — بستههای NuGet جداگانهای که نمایشگرها یا سرویسها را اضافه میکنند و توسط مجوز شما فعال میشوند. این صفحه مدل ثبت را توضیح میدهد، چه اتفاقی در زمان راهاندازی میافتد وقتی مجوز یک افزونه را پوشش نمیدهد، و چگونگی افزودن نمایشگر خودتان.
ثبت یک افزونه
هر بسته افزونه یک کلاس افزونه را افشا میکند. یک بار آن را در Application_Start ثبت کنید:
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 پرتاب میکند:
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 مراجعه کنید.
قرارداد
یک افزونه یک رابط کاربری بهطور عمدی کوچک را پیادهسازی میکند:
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 نمایشگر داخلی ندارد): بدون قابلیت، باز کردن شکست میخورد:
LicenseException: This document type requires the 'Dicom' plugin license.یک مجوز موقت فعال همهٔ قابلیتها را اعطا میکند. این یک شگفتی کلاسیک هنگام راهاندازی است: همان خطوط AddPlugin که در طول ارزیابی اجرا شدند، وقتی مجوز خریداریشده یکی از آن قابلیتها را حذف کند، سایت را متوقف میکند. IsCapabilityGranted(...) را با آنچه قبل از استقرار خریداری کردید مقایسه کنید. با هیچ مجوزی، هیچ چیزی اعطا نمیشود — یک مجوز گمشده، مجوز موقت نیست.
همان محدودسازی به مرورگر نیز میرسد: Viewer.ReferenceScripts() و ReferenceCss() فایلهای ویژگیهای محدودشده توسط مجوز (جستجو، حاشیهنویسی) را فقط زمانی که مجوز آنها را اعطا میکند، صادر میکنند، بنابراین صفحه هرگز ویژگیای را که سرور رد میکند، ارائه نمیدهد.
نقشهٔ ویژگیها و افزونهها
| ویژگی | چگونگی فعالسازی | قابلیت | مشارکتها |
|---|---|---|---|
| حاشیهنویسی | درون نمایشگر تعبیه شده؛ شامل منابع حاشیهنویسی | Annotation | نویسندگی مرورگر، حفظ نشست، خروجیهای سوزانده شده |
| جستجو | درون نمایشگرهای فرمتهای قابل جستجو تعبیه شده؛ شامل منابع جستجو | Search | فهرست متن بومی، برجستهسازیها، ناوبری نتایج |
| مبدل | نصب Doconut.NETFramework.Converter و ثبت ConverterPlugin | Converter | سرویس تبدیل C# و یک ویجت وب اختیاری |
| DICOM | نصب Doconut.NETFramework.Dicom و ثبت DicomPlugin | Dicom | نمایش تصویر پزشکی برای .dcm و .ima |
| امضا کننده | نصب Doconut.NETFramework.Signer و ثبت SignerPlugin | Signer | امضاهای قابل مشاهده و مهرهای دیجیتال برای PDF و Word: سرویس امضای C# و یک ویجت وب اختیاری |
حاشیهنویسی و جستجو از AddPlugin<TPlugin>() استفاده نمیکنند. مبدل، DICOM و امضا کننده هر کدام صفحهای تحت افزونهها دارند که شامل پیکربندی و استفاده آنها است. در این بسته، DICOM صفحات، فریمها و انیمیشنها را رندر میکند، اما متادیتای فنی را نمیخواند — به DICOM Plugin مراجعه کنید.
نمایشگرهای سفارشی — پردازشگر فرمت خودتان
میتوانید یک نمایشگر را بدون نوشتن بستهٔ افزونه، مستقیماً در Application_Start به خط لوله وصل کنید:
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بررسی کنید.
آیا این صفحه مفید بود؟