DoconutOptions – Doconut เอกสาร

DoconutOptions (namespace Doconut) คืออ็อบเจ็กต์การกำหนดค่าหนึ่งเดียวสำหรับ SDK ทั้งหมด คุณกำหนดค่าเพียงครั้งเดียวภายใน AddDoconut() และมันถูกลงทะเบียนเป็น singleton.

นี่เป็นการเปลี่ยนแปลงตำแหน่งเช่นเดียวกับรูปแบบ ในไลบรารี .NET Standard ก่อนหน้า DoconutOptions อินสแตนซ์ถูกสร้างขึ้นในช่วง pipeline แล้วส่งต่อให้ UseDoconut(new DoconutOptions { … }). ที่นี่ middleware ไม่รับตัวเลือกใด ๆ — ทุกอย่างถูกตั้งค่าในระหว่างการลงทะเบียนบริการ.

csharp

builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

คุณสมบัติ

ประเภท	คุณสมบัติ	ค่าเริ่มต้น	คำอธิบาย
`bool`	`ShowDoconutInfo`	`false`	เมื่อ `true`, คำขอ middleware ที่ไม่มี token จะส่งคืนแบนเนอร์เวอร์ชันแทน 404 มีประโยชน์เป็นการตรวจสอบเบื้องต้น; ปล่อย `false` ในการผลิต.
`bool`	`UnsafeMode`	`false`	เมื่อ `true`, ข้ามการตรวจสอบความปลอดภัยของ ASP.NET‑session ในคำขอหน้า ปล่อย `false` ในการผลิตบนโหนดเดียว (ดู แนวคิดหลัก → เซสชันและความปลอดภัย). ก่อนหน้านี้สะกดเป็น `UnSafeMode`.
`string`	`MiddlewarePath`	`"/doconut"`	ค่าการประสานงานสำหรับ endpoint ของหน้า‑image มันได้รับการตรวจสอบ แต่ไม่ทำการเมานท์สาขา pipeline; รักษาให้สอดคล้องกับการแมป `UseDoconut()` จริงและ client `BasePath`.
`string`	`ResourcesPath`	`"/doconut-res"`	คำนำหน้าพาธ URL สำหรับทรัพยากร JS/CSS/image/font ที่ฝังอยู่.
`string`	`LicensePath`	`""`	พาธไปยังไฟล์ใบอนุญาต ว่าง → แหล่งใบอนุญาตถัดไป, จากนั้นค้นหาอัตโนมัติ; ไม่พบ → สถานะการประเมินที่มีลายน้ำโดยไม่มีความสามารถ.
`string`	`LicenseContent`	`""`	เนื้อหา XML ใบอนุญาตดิบ (ฐานข้อมูล, ตัวแปรสภาพแวดล้อม, secret manager) มีลำดับความสำคัญเหนือ `LicensePath`.
`Stream?`	`LicenseStream`	`null`	ใบอนุญาตเป็นสตรีม, อ่านครั้งเดียวที่เริ่มต้น มีลำดับความสำคัญเหนือแหล่งอื่นทั้งสอง.
`bool`	`ResetLicense`	`false`	แฟล็กความเข้ากันได้ที่สงวนไว้ การทำงานปัจจุบันไม่ได้ใช้มัน; รีสตาร์ทแอปพลิเคชันหลังจากเปลี่ยนใบอนุญาต.
`DoconutPluginRegistry`	`PluginRegistry`	—	รีจิสทรีแบบอ่าน‑อย่างเดียวที่รวบรวมการสนับสนุนของปลั๊กอิน; ถูกใช้โดย factory ของ viewer. เติมข้อมูลผ่าน `AddPlugin<T>()`.

License precedence (enforced at service registration): LicenseStream → LicenseContent → LicensePath → การค้นหาอัตโนมัติ (ดู เริ่มต้น → การตั้งค่าใบอนุญาต).

วิธีการ

AddPlugin<TPlugin>()

text

DoconutOptions AddPlugin<TPlugin>() where TPlugin : IDoconutPlugin, new()

ใช้เมธอดนี้สำหรับแพ็กเกจ Converter และ DICOM ที่เปิดให้เลือกใช้แล้ว Annotation และการค้นหาแบบปกติเป็นฟีเจอร์ที่มีใบอนุญาตในตัวและไม่ใช้ AddPlugin<TPlugin>().

ลงทะเบียนปลั๊กอินของฝ่ายแรก (Converter, DICOM) แบบ fluent — คืนค่าอินสแตนซ์ของ options. AddDoconut() จะโยน InvalidOperationException สำหรับใบอนุญาตที่หายไป, ไฟล์ legacy TRIAL, หรือใบอนุญาตแบบชำระเงินที่ไม่ให้ความสามารถของปลั๊กอิน การลงทะเบียนแบบชั่วคราว/เดโมจะคงอยู่หลังจากหมดอายุและจะอยู่ภายใต้ประตู runtime (ดู แนวคิดหลัก → ระบบปลั๊กอิน).

วิดเจ็ต Converter ที่เปิดให้เลือกใช้จะเปิดด้วย AddConverterWidget() และปรากฏผ่าน property อ่าน‑อย่างเดียว ConverterWidget; ตัวเลือกของมันถูกอธิบายในหน้า Converter Plugin (Plugins → Converter Plugin).

RegisterViewer(extension, factory, defaultConfig?)

text

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — จุดนำ (dot) ไม่จำเป็น
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

ลงทะเบียน ตัวแสดงผลแบบกำหนดเอง สำหรับส่วนขยายไฟล์ ตัวแสดงผลแบบกำหนดเองจะมีลำดับความสำคัญเหนือ viewer ที่มีในตัวและปลั๊กอินและไม่ได้ถูกจำกัดโดยใบอนุญาต เมื่อ defaultConfig ถูกละเว้นและเอกสารเปิดโดยไม่มีการกำหนดค่าอย่างชัดเจน จะใช้ ImageConfig.

โยน ArgumentException (Extension must be a non-empty file extension.) สำหรับส่วนขยายว่างและ ArgumentNullException สำหรับ factory ที่เป็น null.

การตรวจสอบการเริ่มต้น

AddDoconut() ตรวจสอบ options fail‑fast, ดังนั้นการกำหนดค่าที่ผิดพลาดจะปรากฏเป็นข้อยกเว้นที่ชัดเจนในขณะเริ่มต้นแทนการเกิด 404 ที่สับสนในเวลาคำขอ:

text

DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

การกำหนดค่าทั่วไป

csharp

// Production: ใบอนุญาตชัดเจน, ทุกอย่างถูกล็อก (ค่าเริ่มต้นด้านความปลอดภัยทั้งหมด)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// เส้นทางที่กำหนดเอง (e.g. เพื่อหลีกเลี่ยงความขัดแย้งของเส้นทาง)
builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});

เมื่อคุณเปลี่ยน ResourcesPath, ให้รักษา ResPath ของวิดเจ็ต client ให้สอดคล้องกัน (ดู ViewerConfig). นี่เป็นหนึ่งในสองการตั้งค่าด้าน client ที่ล้มเหลวโดยไม่มีข้อความแสดงข้อผิดพลาด.

MiddlewarePath ไม่ใช่ตัวแมปเส้นทาง ASP.NET Core อัตโนมัติ หาก Doconut ควรตอบเฉพาะภายใต้คำนำหน้าที่กำหนดเอง, ให้เมานท์ UseDoconut() บนสาขานั้น (เช่นกับ app.Map("/docs-engine", branch => branch.UseDoconut())) และตั้งค่า client BasePath ให้เป็น URL เดียวกัน แอปอ้างอิงกลับคงรูปแบบคำขอ DocImage.axd เก่าไว้บนสาขา MapWhen พร้อมกับ BasePath: '/'.