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, bên trong AddDoconut(), và nó được đăng ký như một singleton.

Đây là một sự thay đổi về vị trí cũng như về hình dạng. Trong thư viện .NET Standard trước đây, một DoconutOptions instance được tạo ra vào thời điểm pipeline và được chuyển cho UseDoconut(new DoconutOptions { … }). Ở đây middleware không nhận bất kỳ tùy chọn nào — mọi thứ đượ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 Bắt đầu → Cài đặt Giấy phép).

Phương thức

AddPlugin<TPlugin>()

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 tùy chọn. Annotation và Search 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ề đối tượng 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 Khái niệm Cốt lõi → Hệ thống Plugin).

Widget Converter tùy chọn được bậ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 trên trang Converter Plugin (Plugin → Converter Plugin).

RegisterViewer(extension, factory, defaultConfig?)

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 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 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 trống và ném ArgumentNullException khi factory null.

Kiểm tra khởi động

AddDoconut() xác thực các options ngay khi khởi động, 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 vào thời điểm yêu cầu:

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

// 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). Đây là một trong hai thiết lập 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 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 client BasePath 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: '/'.