Mở rộng Doconut – Tài liệu Doconut

DoconutExtensions (namespace Doconut.Middleware) là lớp tĩnh với ba lời gọi mà mọi máy chủ Doconut thực hiện: một đăng ký dịch vụ và hai đăng ký middleware.

csharp

builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseDoconutResources(); // BEFORE UseDoconut()
app.UseDoconut();

AddDoconut

text

IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)

Xây dựng DoconutOptions, xác thực chúng nhanh chóng (xem DoconutOptions → Kiểm tra khởi động), và đăng ký toàn bộ đồ thị dịch vụ:

Dịch vụ	Thời gian tồn tại	Vai trò
`DoconutOptions`	Singleton	Đối tượng cấu hình
`IViewerFactory`	Singleton	Ánh xạ các phần mở rộng tới trình xem định dạng
`IDocumentSessionManager`	Singleton	Token → bộ nhớ cache phiên (`IMemoryCache` cũng được đăng ký)
`IDoconutLicenseService`	Singleton	Giấy phép được tải một lần khi khởi động (ưu tiên: `LicenseStream` → `LicenseContent` → `LicensePath` → tìm kiếm tự động)
`PageImageService`	Singleton	Pipeline ảnh trang (đánh dấu/ xoay/ thu phóng/ chú thích)
Document security (access store)	Singleton	Cấp quyền cho việc ràng buộc token‑to‑session
`Viewer`	Transient	Giao diện công khai mở/đóng
`DocumentConverter`	Transient	Giao diện chuyển đổi — yêu cầu plugin Converter
Health check `"doconut"`	—	Báo cáo trạng thái giấy phép/hết hạn thông qua kiểm tra sức khỏe ASP.NET

Hai hành vi đáng chú ý:

Converter yêu cầu plugin của nó. Việc giải quyết DocumentConverter mà không có options.AddPlugin<ConverterPlugin>() sẽ ném lỗi:

text

InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Quyền plugin được xác thực khi khởi động. Một giấy phép thiếu, tệp TRIAL cũ, hoặc giấy phép trả phí mà không có khả năng plugin đã đăng ký sẽ thất bại tại thời điểm AddDoconut(). Các đăng ký tạm thời/Demo tồn tại sau ngày hết hạn, trong khi các cổng thời gian chạy sẽ thu hồi các khả năng đã hết hạn.

Kiểm tra sức khỏe tích hợp với cơ chế chuẩn của ASP.NET Core — ánh xạ nó nếu bạn muốn trạng thái giấy phép trên endpoint sức khỏe của bạn:

csharp

app.MapHealthChecks("/health");

UseDoconut

text

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Thêm middleware ảnh trang của Doconut. Nó trả lời mọi yêu cầu có tham số truy vấn ?token= — các trang, ảnh thu nhỏ, tìm kiếm, chú thích, hành động trang (bảng yêu cầu đầy đủ nằm trong Core Concepts → How the Viewer Works). Khi UnsafeMode là false, lớp bảo mật tài liệu được kết nối tự động trước middleware này.

Mẫu tham chiếu định tuyến các yêu cầu của widget qua một nhánh đường dẫn:

csharp

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconutResources

text

IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

Phục vụ các tệp JS, CSS, hình ảnh và phông chữ nhúng tại DoconutOptions.ResourcesPath (mặc định /doconut-res). Đây là các tệp mà Viewer.ReferenceCss() / ReferenceScripts() tạo thẻ cho.

Luôn gọi nó trước UseDoconut(). Nếu khu vực Viewer vẫn trống và console trình duyệt hiển thị lỗi 404 cho /doconut-res/..., thì lời gọi này bị thiếu hoặc đặt sai vị trí.

Ordering recap

csharp

app.UseRouting();
app.UseSession();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1st Doconut call
app.UseDoconut();          // 2nd Doconut call (or via a MapWhen branch)