DoconutOptions

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.

Đây là một sự thay đổi về vị trí cũng như hình dạng. Trong thư viện .NET Standard trước đây, một instance của DoconutOptions được tạo ra vào thời điểm pipeline và được truyền cho UseDoconut(new DoconutOptions { … }). Ở đây middleware không nhận bất kỳ tùy chọn nào — tất cả được thiết lập trong quá trình đăng ký dịch vụ.

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

Thứ 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()

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

Sử dụng phương thức này cho các gói Converter và DICOM được phát hành dạng opt‑in. Annotation và Search bình 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 dạng opt‑in được kích hoạt bằng AddConverterWidget() và được 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 Plugin Converter (Plugins → Converter Plugin).

RegisterViewer(extension, factory, defaultConfig?)

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — leading dot optional
    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 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.) cho phần mở rộng trống và ArgumentNullException cho factory null.

Xác thực khi 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:

DoconutOptions.MiddlewarePath phải là một đường dẫn không rỗng bắt đầu bằng '/'.
DoconutOptions.ResourcesPath phải là một đường dẫn không rỗng bắt đầu bằng '/'.
DoconutOptions.MiddlewarePath và ResourcesPath phải là các đường dẫn khác nhau.

Cấu hình thường dùng

// 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, hãy đồng bộ ResPath của widget client (xem ViewerConfig). Đây là một trong hai cài đặt phía client sẽ thất bại mà không có thông báo lỗi.

MiddlewarePath không phải là một bộ định tuyến 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. Ứng dụng tham chiếu thay vào đó giữ dạng yêu cầu lịch sử DocImage.axd trên một nhánh MapWhen với BasePath: '/'.