DoconutExtensions

ثبت سرویس و میدل‌ویر

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

csharp
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession();          // قبل از UseDoconut()، UseSession() را فراخوانی کنید
app.UseDoconutResources(); // باید قبل از UseDoconut() ثبت شود
app.Map("/doconut", branch => branch.UseDoconut());

UseDoconut() به هر درخواست که به آن می‌رسد پاسخ می‌دهد، بنابراین آن را در شاخه‌ای جداگانه با app.Map سوار کنید.

AddDoconut

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

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

سرویسطول عمرنقش
DoconutOptionsSingletonشیء پیکربندی
سرویس کش جلسهSingletonToken → کش جلسه (IMemoryCache نیز ثبت می‌شود)
IDoconutLicenseServiceSingletonلایسنس که یک‌بار در زمان راه‌اندازی بارگذاری می‌شود (ترتیب اولویت: LicenseStream → LicenseContent → LicensePath → جستجوی خودکار)
خط لوله تصویر‑صفحهSingletonپردازش تصویر برای صفحات (آب‌نشان، چرخش، مقیاس، حاشیه‌نویسی)
امنیت سند (ذخیره‌سازی دسترسی)Singletonاعطای بایندینگ توکن‑به‑جلسه
ViewerTransientواسط عمومی باز/بسته
DocumentConverterTransientواسط تبدیل — نیاز به افزونه Converter دارد
DocumentSignerTransientواسط امضا — نیاز به افزونه Signer دارد (به Signer Plugin مراجعه کنید)
DistributedDocumentPublisherTransientانتشار artefacts سند به ذخیره‌سازی مشترک
Health check "doconut"—گزارش وضعیت لایسنس/انقضا از طریق health checks ASP.NET

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

دو رفتار مهم:

  • Converter به افزونه خود نیاز دارد. حل DocumentConverter بدون options.AddPlugin<ConverterPlugin>() منجر به پرتاب استثنا می‌شود:
text
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 کنید:

csharp
app.MapHealthChecks("/health");

UseDoconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

میان‌افزار تصویر‑صفحه Doconut را اضافه می‌کند. تمام درخواست‌هایی که پارامتر query ?token= دارند — صفحات، تصویرهای کوچک، جستجو، حاشیه‌نویسی، اقدامات صفحه (جدول کامل درخواست در Core Concepts → How the Viewer Works) — را سرو می‌کند و هر درخواست دیگر را خود با 404 (یا بنر ShowDoconutInfo) پاسخ می‌دهد: هرگز درخواست را به بقیهٔ خط لوله نمی‌سپارد. آن را در شاخه‌ای جداگانه، همان‌طور که در نمونه‌های این صفحه نشان داده شده، سوار کنید. وقتی UnsafeMode false باشد، لایهٔ امنیت سند به‌صورت خودکار پیش از آن وصل می‌شود.

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

یک تنظیمات رایج شکل تاریخی درخواست DocImage.axd را با یک شاخهٔ MapWhen حفظ می‌کند (در این صورت کلاینت از BasePath: '/' استفاده می‌کند):

csharp
app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconutResources

text
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

JS، CSS، تصاویر و فونت‌های توکار را در DoconutOptions.ResourcesPath (به‌صورت پیش‌فرض /doconut-res) سرو می‌کند. این‌ها فایل‌هایی هستند که Viewer.ReferenceCss() / ReferenceScripts() برایشان تگ تولید می‌کنند.

همیشه قبل از UseDoconut() فراخوانی کنید. اگر ناحیهٔ ویور خالی بماند و کنسول مرورگر خطاهای 404 برای /doconut-res/... نشان دهد، این فراخوانی گم شده یا به‌اشتباه مکان‌یابی شده است.

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

Serving from shared storage

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

text
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null)   // صف انتشار پس‌زمینه‌ای به صورت opt‑in
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure)                     // ذخیره‌ساز پشتیبان مشترک برای بارگذاری ویجت‌ها

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

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

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

Ordering recap

csharp
app.UseRouting();
app.UseSession();          // قبل از UseDoconut()، UseSession() را فراخوانی کنید
app.UseDoconutResources(); // باید قبل از UseDoconut() ثبت شود
app.Map("/doconut", branch => branch.UseDoconut()); // یا یک شاخه MapWhen

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