Mở rộng Doconut
Đăng ký dịch vụ và middleware
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.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // gọi UseSession() trước UseDoconut()
app.UseDoconutResources(); // phải được đăng ký trước UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() trả lời mọi yêu cầu đến nó, vì vậy hãy gắn nó trên một nhánh riêng với app.Map.
AddDoconut
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 → Startup validation), và đăng ký toàn bộ đồ thị dịch vụ:
| Service | Lifetime | Role |
|---|---|---|
DoconutOptions | Singleton | Đối tượng cấu hình |
| Dịch vụ bộ nhớ đệm phiên | Singleton | Token → bộ nhớ đệm 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ự động tìm kiếm) |
| Quy trình xử lý trang‑ảnh | Singleton | Thực hiện xử lý ảnh cho các trang (đánh dấu, xoay, thay đổi kích thước, chú thích) |
| Bảo mật tài liệu (kho lưu trữ truy cập) | Singleton | Cấp quyền cho việc ràng buộc token‑to‑session |
Viewer | Transient | Giao diện mở/đóng công cộng |
DocumentConverter | Transient | Giao diện chuyển đổi — yêu cầu plugin Converter |
DocumentSigner | Transient | Giao diện ký — yêu cầu plugin Signer (xem Plugin Chữ ký) |
DistributedDocumentPublisher | Transient | Phát hành các artefact của tài liệu tới bộ nhớ chia sẻ (xem Triển khai phân tán) |
Health check "doconut" | — | Báo cáo trạng thái giấy phép/hết hạn qua kiểm tra sức khỏe ASP.NET |
Hai hành vi đáng biết:
- Converter yêu cầu plugin của nó. Việc resolve
DocumentConvertermà không cóoptions.AddPlugin<ConverterPlugin>()sẽ ném lỗi:
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentSigner tuân theo quy tắc tương tự: nếu không có options.AddPlugin<SignerPlugin>() nó sẽ ném No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
- Quyền plugin được xác thực khi khởi động. Một giấy phép thiếu, tệp legacy
TRIAL, hoặc giấy phép trả phí mà không có khả năng của plugin đã đăng ký sẽ thất bại vào thời điểmAddDoconut(). Các đăng ký tạm thời/Demo tồn tại qua ngày hết hạn, trong khi các cổng runtime 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 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 mình:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)Thêm middleware page‑image của Doconut. Nó phục vụ mọi yêu cầu mang tham số truy vấn ?token= — các trang, hì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) — và trả lời bất kỳ yêu cầu nào khác bằng 404 (hoặc banner ShowDoconutInfo): nó không bao giờ chuyển tiếp yêu cầu tới phần còn lại của pipeline. Gắn nó trên một nhánh riêng, như trong các mẫu trên trang này. Khi UnsafeMode là false, lớp bảo mật tài liệu sẽ tự động được kết nối trước nó.
Một lựa chọn phổ biến giữ nguyên dạng yêu cầu lịch sử DocImage.axd với một nhánh MapWhen (client sau đó sử dụng BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
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() phát ra thẻ cho.
Luôn gọi nó trước UseDoconut(). Nếu khu vực viewer trống và console trình duyệt hiển thị lỗi 404 cho /doconut-res/..., lời gọi này bị thiếu hoặc đặt sai vị trí.
Phục vụ từ bộ nhớ chia sẻ
Hai đăng ký bổ sung tồn tại cho các triển khai mà nút thực hiện render tài liệu không nhất thiết là nút phục vụ các trang của nó. Cả hai đều được bao phủ toàn diện trong Triển khai phân tán; các chữ ký là:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // hàng đợi xuất bản nền cho phép đăng ký
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // kho lưu trữ hỗ trợ chung cho việc tải lên widgetPhần đọc là một middleware riêng biệt từ assembly Doconut.Clouds, được cung cấp trong cùng gói:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerTóm tắt thứ tự
app.UseRouting();
app.UseSession(); // gọi UseSession() trước UseDoconut()
app.UseDoconutResources(); // phải được đăng ký trước UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // hoặc một nhánh MapWhenTrang này có hữu ích không?