DoconutExtensions
Đă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ó vào 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ụ:
| Dịch vụ | Thời gian sống | Vai trò |
|---|---|---|
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) |
| Pipeline trang‑hình ảnh | Singleton | Thực hiện xử lý hình ảnh cho các trang (đánh dấu, quay, thu phóng, 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 | Xuất các artefact của tài liệu tới bộ nhớ chia sẻ (xem Triển khai Phân tán) |
Kiểm tra sức khỏe "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 lưu ý:
- Converter yêu cầu plugin của nó. Giải quyết
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
TRIALcũ, hoặc giấy phép trả phí mà không có khả năng 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 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 mình:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)Thêm middleware trang‑hình ảnh 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 Khái niệm Cốt lõi → Cách Trình xem Hoạt Động) — 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ó vào một nhánh riêng, như trong các mẫu trên trang này. Khi UnsafeMode ở trạng thái 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 (khách hàng 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 trình xem vẫn 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 nơi 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 tham gia
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // kho lưu trữ chung cho tải lên widgetPhần đọc là một middleware riêng biệt từ assembly Doconut.Clouds, được đóng gói trong cùng một 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?