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, bên trong AddDoconut(), và nó được đăng ký như một 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 sản xuất.
`bool`	`UnsafeMode`	`false`	Khi `true`, bỏ qua kiểm tra bảo mật ASP.NET-session trên các yêu cầu trang. Để `false` trong môi trường sản xuất (xem Core Concepts → Sessions & Security).
`string`	`MiddlewarePath`	`"/doconut"`	Giá trị phối hợp 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ạ `UseDoconut()` thực tế và client `BasePath`.
`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á; 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ự trữ. Implementations .NET 6 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 nhà máy trình xem. Đ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<TPlugin>()

text

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

Sử dụng phương pháp này cho các gói Converter và DICOM đã phát hành theo tùy chọn. Annotation và tìm kiếm bình thường là các tính năng có giấy phép tích hợp 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 legacy TRIAL, 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 tùy 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 trên trang Converter Plugin (Plugins → Converter Plugin).

RegisterViewer(extension, factory, defaultConfig?)

text

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — dấu chấm đầu tiên là tùy chọn
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

Đăng ký một trình xem tùy chỉnh cho một phần mở rộng tệp. Trình xem tùy chỉnh có ưu tiên hơn các trình xem tích hợp và plugin và không bị giới hạn 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.) cho phần mở rộng trống và ArgumentNullException cho factory null.

Xác thực khởi động

AddDoconut() xác thực các tùy chọn fail-fast, vì vậy một 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: giấy phép rõ ràng, mọi thứ được khóa chặt (tất cả các mặc định bảo mật)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Đường dẫn tùy chỉnh (ví dụ để tránh xung đột tuyến đường)
builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});

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

MiddlewarePath không phải là một bộ định tuyến ASP.NET Core tự động. Nếu Doconut chỉ nên 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 client BasePath thành cùng một URL.