افزونه‌های Doconut

DoconutExtensions (namespace Doconut.Middleware) یک کلاس استاتیک است که سه فراخوانی را که هر میزبان Doconut انجام می‌دهد شامل می‌شود: یک ثبت سرویس و دو ثبت میدلور.

builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseDoconutResources(); // قبل از UseDoconut()
app.UseDoconut();

AddDoconut

IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)

یک DoconutOptions می‌سازد، آن‌ها را به‌صورت سریع‌خطا (fail‑fast) اعتبارسنجی می‌کند (به DoconutOptions → اعتبارسنجی Startup مراجعه کنید) و گراف کامل سرویس‌ها را ثبت می‌کند:

در کتابخانه .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>().

• اعتبار افزونه در زمان راه‌اندازی اعتبارسنجی می‌شود. یک مجوز مفقود، فایل TRIAL قدیمی، یا مجوز پولی بدون قابلیت افزونه ثبت‌شده در زمان AddDoconut() شکست می‌خورد. ثبت‌های موقت/دمویی تا تاریخ انقضای خود باقی می‌مانند، در حالی که دروازه‌های زمان اجرا قابلیت‌های منقضی‌شده را لغو می‌کنند.

بررسی سلامت با سازوکار استاندارد ASP.NET Core یکپارچه می‌شود — اگر می‌خواهید وضعیت مجوز را در نقطهٔ سلامت خود داشته باشید، آن را نقشه‌گذاری کنید:

app.MapHealthChecks("/health");

UseDoconut

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

میانه‌افزار صفحه‑تصویر Doconut را اضافه می‌کند. به هر درخواستی که پارامتر پرس‌وجوی ?token= را دارد پاسخ می‌دهد — صفحات، تصویرهای بندانگشتی، جستجو، حاشیه‌نویسی‌ها، اقدامات صفحه (جدول کامل درخواست در مفاهیم اصلی → نحوهٔ کار Viewer موجود است). وقتی UnsafeMode برابر با false باشد، لایهٔ امنیت سند به‌صورت خودکار قبل از آن وصل می‌شود.

هیچ آرگیومانی نمی‌گیرد. پاس دادن یک نمونهٔ DoconutOptions در اینجا شکل کتابخانهٔ قبلی بود و دیگر کامپایل نمی‌شود.

نمونهٔ مرجع درخواست‌های ویجت را از طریق یک شاخهٔ مسیر هدایت می‌کند و شکل تاریخی درخواست را حفظ می‌کند:

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() فراخوانی کنید. اگر ناحیهٔ Viewer خالی بماند و کنسول مرورگر 404هایی برای /doconut-res/... نشان دهد، این فراخوانی گم شده یا در مکان نادرست قرار گرفته است.

این جایگزین پشتیبانی‌شده برای اتصال دستی میدلور پردازش منابع توکار است.

سرویس‌دهی از ذخیره‌سازی مشترک

دو ثبت دیگر برای استقرارهایی وجود دارد که در آن گره‌ای که سند را رندر می‌کند لزوماً گره‌ای که صفحات آن را سرو می‌کند نیست. هر دو به‌صورت کامل در استقرارهای توزیع‌شده پوشش داده شده‌اند؛ امضاها عبارتند از:

IServiceCollection AddDoconutDistributedAsyncPublish(...)   // صف انتشار پس‌زمینه به صورت opt‑in
IServiceCollection AddDoconutDistributedWidgets(...)        // ذخیره‌ساز پشتیبان مشترک برای بارگذاری ویجت‌ها

بخش خواندن یک میدلور جداگانه از بستهٔ Doconut.Clouds است:

IApplicationBuilder UseDoconutCloud<THandler>(
    this IApplicationBuilder app,
    Action<CloudOptions>? configure = null,
    string pathPrefix = "/doconut-cloud")
    where THandler : BaseCloudHandler

UseDoconutWebFarm(...) و WebFarmOptions در این نسخه وجود ندارند. برای نگاشت تنظیم‑به‑تنظیم، راهنمای مهاجرت را ببینید.

خلاصهٔ ترتیب

app.UseRouting();
app.UseSession();          // الزامی وقتی UnsafeMode = false
app.UseDoconutResources(); // اولین فراخوانی Doconut
app.UseDoconut();          // دومین فراخوانی Doconut (یا از طریق یک شاخه MapWhen)