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 → اعتبارسنجی راه‌اندازی مراجعه کنید)، و گراف کامل سرویس‌ها را ثبت می‌کند:

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

دو رفتار که ارزش دانستن دارند:

  • 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>().

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

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

csharp
app.MapHealthChecks("/health");

UseDoconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

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

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

Serving from shared storage

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

text
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null)   // صف انتشار پس‌زمینه به صورت انتخابی
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

Ordering recap

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

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