DoconutOptions – Tài liệu Doconut

DoconutOptions (namespace Doconut) là đối tượng cấu hình duy nhất cho toàn bộ SDK. Bạn cấu hình nó một lần, trong AddDoconut(), và nó được đăng ký dưới dạng singleton.

csharp

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

Thuộc tính

Kiểu	Thuộc tính	Mặc định	Mô tả
`bool`	`ShowDoconutInfo`	`false`	Khi `true`, một yêu cầu middleware không có token sẽ trả về một biểu ngữ phiên bản (`Doconut <version> is running on <host>`) thay vì 404. Hữu ích như một kiểm tra nhanh; để `false` trong môi trường production.
`bool`	`UnsafeMode`	`false`	Khi `true`, bỏ qua kiểm tra bảo mật phiên ASP.NET trên các yêu cầu trang. Để `false` trong môi trường production (xem Core Concepts → Sessions & Security).
`string`	`MiddlewarePath`	`"/doconut"`	Giá trị điều phối cho endpoint page-image. Nó được xác thực, nhưng không gắn một nhánh pipeline; giữ nó đồng nhất với ánh xạ thực tế của `UseDoconut()` và `BasePath` của client.
`string`	`ResourcesPath`	`"/doconut-res"`	Tiền tố đường dẫn URL cho các tài nguyên JS/CSS/hình ảnh/phông chữ được nhúng.
`string`	`LicensePath`	`""`	Đường dẫn tới tệp giấy phép. Trống → nguồn giấy phép tiếp theo, sau đó tự động khám phá; nếu không tìm thấy → trạng thái đánh dấu nước đánh giá không có khả năng.
`string`	`LicenseContent`	`""`	Nội dung XML giấy phép thô (cơ sở dữ liệu, biến môi trường, trình quản lý bí mật). Có ưu tiên hơn `LicensePath`.
`Stream?`	`LicenseStream`	`null`	Giấy phép dưới dạng stream, đọc một lần khi khởi động. Có ưu tiên hơn cả hai nguồn khác.
`bool`	`ResetLicense`	`false`	Cờ tương thích dự phòng. Implementations .NET 8 hiện tại không sử dụng nó; khởi động lại ứng dụng sau khi thay thế giấy phép.
`DoconutPluginRegistry`	`PluginRegistry`	—	Registry chỉ đọc thu thập các đóng góp plugin; được sử dụng bởi factory của viewer. Điền qua `AddPlugin<T>()`.

Ưu tiên giấy phép (được thực thi khi đăng ký dịch vụ): LicenseStream → LicenseContent → LicensePath → tự động khám phá (xem Getting Started → License Setup).

Phương thức

AddPlugin()

text

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

Sử dụng phương thức này cho các gói Converter và DICOM đã phát hành theo lựa chọn. Annotation và Search thông thường là các tính năng có giấy phép tích hợp sẵn và không sử dụng AddPlugin<TPlugin>().

Đăng ký một plugin nội bộ (Converter, DICOM). Fluent — trả về instance của options. AddDoconut() ném InvalidOperationException khi thiếu giấy phép, tệp TRIAL cũ, hoặc giấy phép trả phí không cấp quyền cho plugin. Các đăng ký tạm thời/Demo được giữ lại sau khi hết hạn và sẽ chịu rào cản thời gian chạy (xem Core Concepts → Plugin System).

Widget Converter theo lựa chọn được bật bằng AddConverterWidget() và hiển thị qua thuộc tính chỉ đọc ConverterWidget; các tùy chọn của nó được tài liệu hoá trên trang 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)

Đăng ký một custom viewer cho một phần mở rộng tệp. Custom viewer có ưu tiên hơn các viewer tích hợp sẵn và plugin và không bị giới hạn bởi giấy phép. Khi defaultConfig bị bỏ qua và một tài liệu mở mà không có cấu hình rõ ràng, một ImageConfig sẽ được sử dụng.

Ném ArgumentException (Extension must be a non-empty file extension.) khi phần mở rộng rỗng và ArgumentNullException khi factory null.

Kiểm tra khởi động

AddDoconut() kiểm tra các tùy chọn fail-fast, vì vậy cấu hình sai sẽ xuất hiện dưới dạng ngoại lệ rõ ràng khi khởi động thay vì các lỗi 404 gây nhầm lẫn khi yêu cầu:

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.

Cấu hình chung

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";
});

Khi bạn thay đổi ResourcesPath, giữ cho ResPath của widget client đồng bộ (xem ViewerConfig).

MiddlewarePath không phải là một bộ ánh xạ route tự động của ASP.NET Core. Nếu Doconut chỉ trả lời dưới một tiền tố tùy chỉnh, gắn UseDoconut() vào nhánh đó (ví dụ với app.Map("/docs-engine", branch => branch.UseDoconut())) và đặt BasePath của client thành cùng URL.