DoconutExtensions

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

builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseDoconutResources(); // BEFORE UseDoconut()
app.UseDoconut();

افزودن AddDoconut

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

DoconutOptions را می‌سازد، به‌سرعت آن‌ها را اعتبارسنجی می‌کند (به DoconutOptions → اعتبارسنجی زمان راه‌اندازی مراجعه کنید) و گراف کامل سرویس‌ها را ثبت می‌کند:

در کتابخانهٔ قبلی .NET Standard معادلی برای این فراخوانی وجود نداشت. آن کتابخانه برای هر درخواست new Viewer(cache, accessor) می‌ساخت و گزینه‌ها را به میدلور می‌داد؛ هر دو اکنون توسط این ثبت تک‌تکه جایگزین شده‌اند.

دو رفتار مهم که باید بدانید:

• مبدل به افزونهٔ خود نیاز دارد. حل 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= دارد پاسخ می‌دهد — صفحات، تصویرهای بندانگشتی، جستجو، حاشیه‌نویسی، اقدامات صفحه (جدول کامل درخواست در Core Concepts → How the Viewer Works موجود است). وقتی 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() فراخوانی کنید. اگر ناحیهٔ ویور خالی بماند و کنسول مرورگر خطاهای 404 برای /doconut-res/... نشان دهد، این فراخوانی یا گم شده یا در مکان نادرست قرار گرفته است.

این جایگزین پشتیبانی‌شده برای وصل کردن میدلور منبع توکار به‌صورت دستی با app.UseMiddleware<EmbeddedResourceMiddleware>() است.

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

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

IServiceCollection AddDoconutDistributedAsyncPublish(...)   // opt-in background publish queue
IServiceCollection AddDoconutDistributedWidgets(...)        // shared backing store for widget uploads

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

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

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

خلاصهٔ ترتیب فراخوانی‌ها

app.UseRouting();
app.UseSession();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1st Doconut call
app.UseDoconut();          // 2nd Doconut call (or via a MapWhen branch)