ส่วนขยาย Doconut
การลงทะเบียนบริการและมิดเดิลแวร์
DoconutExtensions (namespace Doconut.Middleware) คือคลาสสแตติกที่มีสามการเรียกใช้ที่โฮสต์ Doconut ทุกตัวทำ: การลงทะเบียนบริการหนึ่งรายการและการลงทะเบียนมิดเดิลแวร์สองรายการ.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // เรียก UseSession() ก่อน UseDoconut()
app.UseDoconutResources(); // ต้องลงทะเบียนก่อน UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() ตอบสนองทุกคำขอที่มาถึงมัน ดังนั้นให้เมานท์บนสาขาแยกของมันพร้อมกับ app.Map.
AddDoconut
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)สร้าง DoconutOptions, ตรวจสอบความถูกต้องแบบ fail-fast (ดู DoconutOptions → การตรวจสอบ Startup), และลงทะเบียนกราฟบริการทั้งหมด:
| Service | Lifetime | Role |
|---|---|---|
DoconutOptions | Singleton | อ็อบเจ็กต์การกำหนดค่า |
| Session cache service | Singleton | Token → แคชเซสชัน (IMemoryCache ได้รับการลงทะเบียนด้วย) |
IDoconutLicenseService | Singleton | ใบอนุญาตโหลดครั้งเดียวที่การเริ่มต้น (ลำดับความสำคัญ: LicenseStream → LicenseContent → LicensePath → auto-search) |
| Page-image pipeline | Singleton | ทำการประมวลผลภาพสำหรับหน้า (ลายน้ำ, หมุน, ปรับขนาด, คำอธิบาย) |
| Document security (access store) | Singleton | มอบสิทธิ์สำหรับการผูก token กับเซสชัน |
Viewer | Transient | ส่วนหน้าสาธารณะสำหรับเปิด/ปิด |
DocumentConverter | Transient | Conversion facade — ต้องการปลั๊กอิน Converter |
DocumentSigner | Transient | Signing facade — ต้องการปลั๊กอิน Signer (ดู ปลั๊กอิน Signer) |
DistributedDocumentPublisher | Transient | เผยแพร่ศิลปะของเอกสารไปยังที่เก็บข้อมูลร่วม (ดู การปรับใช้แบบกระจาย) |
Health check "doconut" | — | รายงานสถานะใบอนุญาต/หมดอายุผ่านการตรวจสอบสุขภาพของ ASP.NET |
พฤติกรรมสองอย่างที่ควรรู้:
- Converter ต้องการปลั๊กอินของมัน. การแก้ไข
DocumentConverterโดยไม่มีoptions.AddPlugin<ConverterPlugin>()จะทำให้เกิดข้อผิดพลาด:
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 สุขภาพของคุณ:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)เพิ่มมิดเดิลแวร์ภาพหน้า Doconut. มันให้บริการทุกคำขอที่มีพารามิเตอร์ query ?token= — หน้า, รูปย่อ, การค้นหา, คำอธิบาย, การกระทำบนหน้า (ตารางคำขอเต็มอยู่ใน Core Concepts → How the Viewer Works) — และตอบสนองคำขออื่นใดด้วย 404 (หรือแบนเนอร์ ShowDoconutInfo): มันจะไม่ส่งต่อคำขอไปยังส่วนที่เหลือของ pipeline. เมานท์บนสาขาแยกของมันเอง, เช่นในตัวอย่างบนหน้านี้. เมื่อ UnsafeMode เป็น false, ชั้นความปลอดภัยของเอกสารจะถูกเชื่อมอัตโนมัติก่อนมัน.
ทางเลือกที่พบบ่อยจะรักษารูปแบบคำขอ DocImage.axd แบบเก่าไว้ด้วยสาขา MapWhen (จากนั้นไคลเอนต์จะใช้ BasePath: '/'):
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/..., การเรียกนี้หายไปหรืออยู่ในตำแหน่งผิด.
ให้บริการจากที่เก็บข้อมูลร่วม
มีการลงทะเบียนเพิ่มเติมอีกสองรายการสำหรับการปรับใช้ที่โหนดที่เรนเดอร์เอกสารไม่ได้เป็นโหนดที่ให้บริการหน้าของมันเสมอ. ทั้งสองถูกครอบคลุมตั้งแต่ต้นจนจบใน การปรับใช้แบบกระจาย; ลายเซ็นคือ:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // คิวเผยแพร่พื้นหลังแบบ opt‑in
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // ที่เก็บข้อมูลสนับสนุนที่ใช้ร่วมกันสำหรับการอัปโหลดวิดเจ็ตด้านการอ่านเป็นมิดเดิลแวร์แยกจากชุดประกอบ Doconut.Clouds, ซึ่งมาพร้อมในแพ็คเกจเดียวกัน:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerสรุปการเรียงลำดับ
app.UseRouting();
app.UseSession(); // เรียก UseSession() ก่อน UseDoconut()
app.UseDoconutResources(); // ต้องลงทะเบียนก่อน UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // หรือสาขา MapWhenหน้านี้เป็นประโยชน์หรือไม่?