DoconutExtensions
ثبت سرویس و میدلویر
DoconutExtensions (namespace Doconut.Middleware) کلاسی ایستاتیک است که سه فراخوانی را که هر میزبان Doconut انجام میدهد، در بر میگیرد: یک ثبت سرویس و دو ثبت میدلویر.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // قبل از UseDoconut()، UseSession() را فراخوانی کنید
app.UseDoconutResources(); // باید قبل از UseDoconut() ثبت شود
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() به هر درخواست که به آن میرسد پاسخ میدهد، بنابراین آن را در شاخهای جداگانه با app.Map سوار کنید.
AddDoconut
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)این متد DoconutOptions را میسازد، آنها را بهصورت fail‑fast اعتبارسنجی میکند (به DoconutOptions → اعتبارسنجی Startup مراجعه کنید) و گراف کامل سرویسها را ثبت میکند:
| سرویس | طول عمر | نقش |
|---|---|---|
DoconutOptions | Singleton | شیء پیکربندی |
| سرویس کش جلسه | Singleton | Token → کش جلسه (IMemoryCache نیز ثبت میشود) |
IDoconutLicenseService | Singleton | لایسنس که یکبار در زمان راهاندازی بارگذاری میشود (ترتیب اولویت: LicenseStream → LicenseContent → LicensePath → جستجوی خودکار) |
| خط لوله تصویر‑صفحه | Singleton | پردازش تصویر برای صفحات (آبنشان، چرخش، مقیاس، حاشیهنویسی) |
| امنیت سند (ذخیرهسازی دسترسی) | Singleton | اعطای بایندینگ توکن‑به‑جلسه |
Viewer | Transient | واسط عمومی باز/بسته |
DocumentConverter | Transient | واسط تبدیل — نیاز به افزونه Converter دارد |
DocumentSigner | Transient | واسط امضا — نیاز به افزونه Signer دارد (به Signer Plugin مراجعه کنید) |
DistributedDocumentPublisher | Transient | انتشار artefacts سند به ذخیرهسازی مشترک |
Health check "doconut" | — | گزارش وضعیت لایسنس/انقضا از طریق health checks ASP.NET |
در کتابخانه قبلی .NET Standard معادل این فراخوانی وجود نداشت. آن new Viewer(cache, accessor) را برای هر درخواست میساخت و گزینهها را به میدلویر میداد؛ هر دو در این ثبتنام تکتکه جایگزین شدهاند.
دو رفتار مهم:
- Converter به افزونه خود نیاز دارد. حل
DocumentConverterبدونoptions.AddPlugin<ConverterPlugin>()منجر به پرتاب استثنا میشود:
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentSigner همان قاعده را دنبال میکند: بدون options.AddPlugin<SignerPlugin>() استثنای No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(). پرتاب میشود
- اعتبارسنجی حقالامتیاز افزونه در زمان راهاندازی انجام میشود. یک لایسنس گمشده، فایل legacy
TRIAL، یا لایسنس پرداختشده بدون قابلیت افزونه ثبتشده، در زمانAddDoconut()شکست میخورند. ثبتنامهای Temporary/Demo پس از تاریخ انقضا باقی میمانند، در حالی که گیتهای زمان اجرا قابلیتهای منقضیشده را لغو میکنند.
Health check با مکانیزم استاندارد ASP.NET Core یکپارچه میشود — اگر میخواهید وضعیت لایسنس را در نقطهٔ سلامت خود داشته باشید، آن را map کنید:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)میانافزار تصویر‑صفحه Doconut را اضافه میکند. تمام درخواستهایی که پارامتر query ?token= دارند — صفحات، تصویرهای کوچک، جستجو، حاشیهنویسی، اقدامات صفحه (جدول کامل درخواست در Core Concepts → How the Viewer Works) — را سرو میکند و هر درخواست دیگر را خود با 404 (یا بنر ShowDoconutInfo) پاسخ میدهد: هرگز درخواست را به بقیهٔ خط لوله نمیسپارد. آن را در شاخهای جداگانه، همانطور که در نمونههای این صفحه نشان داده شده، سوار کنید. وقتی UnsafeMode false باشد، لایهٔ امنیت سند بهصورت خودکار پیش از آن وصل میشود.
هیچ آرگیومانی نمیگیرد. پاس دادن یک نمونهٔ DoconutOptions در اینجا شکل کتابخانهٔ قبلی بود و دیگر کامپایل نمیشود.
یک تنظیمات رایج شکل تاریخی درخواست DocImage.axd را با یک شاخهٔ MapWhen حفظ میکند (در این صورت کلاینت از BasePath: '/' استفاده میکند):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)JS، CSS، تصاویر و فونتهای توکار را در DoconutOptions.ResourcesPath (بهصورت پیشفرض /doconut-res) سرو میکند. اینها فایلهایی هستند که Viewer.ReferenceCss() / ReferenceScripts() برایشان تگ تولید میکنند.
همیشه قبل از UseDoconut() فراخوانی کنید. اگر ناحیهٔ ویور خالی بماند و کنسول مرورگر خطاهای 404 برای /doconut-res/... نشان دهد، این فراخوانی گم شده یا بهاشتباه مکانیابی شده است.
این جایگزین پشتیبانیشده برای وصل کردن میدلویر مدیریت منبع توکار بهصورت دستی است.
Serving from shared storage
دو ثبتنام دیگر برای استقرارهایی وجود دارد که گرهای که سند را رندر میکند لزوماً همان گرهای نیست که صفحات آن را سرو میکند. هر دو در Distributed Deployments بهصورت انتها‑به‑انتها پوشش داده شدهاند؛ امضاها عبارتند از:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // صف انتشار پسزمینهای به صورت opt‑in
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // ذخیرهساز پشتیبان مشترک برای بارگذاری ویجتهاسمت خواندن یک میدلویر جداگانه از اسمبلی Doconut.Clouds است که در همان بسته قرار دارد:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerUseDoconutWebFarm(...) و WebFarmOptions در این نسخه وجود ندارند. برای نگاشت تنظیم‑به‑تنظیم به راهنمای migration guide مراجعه کنید.
Ordering recap
app.UseRouting();
app.UseSession(); // قبل از UseDoconut()، UseSession() را فراخوانی کنید
app.UseDoconutResources(); // باید قبل از UseDoconut() ثبت شود
app.Map("/doconut", branch => branch.UseDoconut()); // یا یک شاخه MapWhenآیا این صفحه مفید بود؟