DoconutOptions – Doconut เอกสาร

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

csharp

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

Properties

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

ลำดับความสำคัญของลิขสิทธิ์ (บังคับที่การลงทะเบียนบริการ): LicenseStream → LicenseContent → LicensePath → การค้นหาอัตโนมัติ (ดู Getting Started → License Setup).

Methods

AddPlugin<TPlugin>()

text

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

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

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

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

RegisterViewer(extension, factory, defaultConfig?)

text

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — leading dot optional
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

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

จะโยน ArgumentException (Extension must be a non-empty file extension.) หากนามสกุลว่างเปล่าและ ArgumentNullException หาก factory เป็น null.

Startup validation

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.

Common configurations

csharp

// Production: explicit license, everything locked down (all security defaults)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Custom paths (e.g. to avoid a route conflict)
builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});

เมื่อคุณเปลี่ยน ResourcesPath ให้ทำให้ ResPath ของวิดเจ็ตไคลเอนต์สอดคล้องกัน (ดู ViewerConfig).

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