ส่วนขยาย Doconut

การลงทะเบียนบริการและมิดเดิลแวร์

DoconutExtensions (namespace Doconut.Middleware) คือคลาสสแตติกที่มีสามการเรียกใช้ที่โฮสต์ Doconut ทุกตัวทำ: การลงทะเบียนบริการหนึ่งรายการและการลงทะเบียนมิดเดิลแวร์สองรายการ.

csharp
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession();          // เรียก UseSession() ก่อน UseDoconut()
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), และลงทะเบียนกราฟบริการทั้งหมด:

ServiceLifetimeRole
DoconutOptionsSingletonอ็อบเจ็กต์การกำหนดค่า
Session cache serviceSingletonToken → แคชเซสชัน (IMemoryCache ได้รับการลงทะเบียนด้วย)
IDoconutLicenseServiceSingletonใบอนุญาตโหลดครั้งเดียวที่การเริ่มต้น (ลำดับความสำคัญ: LicenseStream → LicenseContent → LicensePath → auto-search)
Page-image pipelineSingletonทำการประมวลผลภาพสำหรับหน้า (ลายน้ำ, หมุน, ปรับขนาด, คำอธิบาย)
Document security (access store)Singletonมอบสิทธิ์สำหรับการผูก token กับเซสชัน
ViewerTransientส่วนหน้าสาธารณะสำหรับเปิด/ปิด
DocumentConverterTransientConversion facade — ต้องการปลั๊กอิน Converter
DocumentSignerTransientSigning facade — ต้องการปลั๊กอิน Signer (ดู ปลั๊กอิน Signer)
DistributedDocumentPublisherTransientเผยแพร่ศิลปะของเอกสารไปยังที่เก็บข้อมูลร่วม (ดู การปรับใช้แบบกระจาย)
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 — ทำการแมปหากคุณต้องการแสดงสถานะใบอนุญาตบน endpoint สุขภาพของคุณ:

csharp
app.MapHealthChecks("/health");

UseDoconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

เพิ่มมิดเดิลแวร์ภาพหน้า Doconut. มันให้บริการทุกคำขอที่มีพารามิเตอร์ query ?token= — หน้า, รูปย่อ, การค้นหา, คำอธิบาย, การกระทำบนหน้า (ตารางคำขอเต็มอยู่ใน Core Concepts → How the Viewer Works) — และตอบสนองคำขออื่นใดด้วย 404 (หรือแบนเนอร์ ShowDoconutInfo): มันจะไม่ส่งต่อคำขอไปยังส่วนที่เหลือของ pipeline. เมานท์บนสาขาแยกของมันเอง, เช่นในตัวอย่างบนหน้านี้. เมื่อ 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() เสมอ. หากพื้นที่ตัวดูว่างเปล่าและคอนโซลของเบราว์เซอร์แสดง 404 สำหรับ /doconut-res/..., การเรียกนี้หายไปหรืออยู่ในตำแหน่งผิด.

ให้บริการจากที่เก็บข้อมูลร่วม

มีการลงทะเบียนเพิ่มเติมอีกสองรายการสำหรับการปรับใช้ที่โหนดที่เรนเดอร์เอกสารไม่ได้เป็นโหนดที่ให้บริการหน้าของมันเสมอ. ทั้งสองถูกครอบคลุมตั้งแต่ต้นจนจบใน การปรับใช้แบบกระจาย; ลายเซ็นคือ:

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

สรุปการเรียงลำดับ

csharp
app.UseRouting();
app.UseSession();          // เรียก UseSession() ก่อน UseDoconut()
app.UseDoconutResources(); // ต้องลงทะเบียนก่อน UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // หรือสาขา MapWhen

หน้านี้เป็นประโยชน์หรือไม่?