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ó 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ụ:
| 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 → session cache (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 → auto-search) |
| Đường dẫn xử lý ảnh trang | Singleton | Thực hiện xử lý ảnh cho các trang (đánh dấu, xoay, thu phóng, chú thích) |
| Bảo mật tài liệu (kho 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 Signer Plugin) |
DistributedDocumentPublisher | Transient | Phát hành các artefact của tài liệu tới bộ nhớ chia sẻ |
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 |
Không có lời gọi tương đương trong thư viện .NET Standard trước đây. Nó tạo new Viewer(cache, accessor) cho mỗi yêu cầu và truyền tùy chọn tới middleware; cả hai đều được thay thế bằng đăng ký duy nhất này.
Hai hành vi đáng biết:
- 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 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 sau 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 có 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 biểu ngữ 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ó.
Không nhận bất kỳ đối số nào. Việc truyền một thể hiện DoconutOptions ở đây là dạng của thư viện trước và hiện không còn biên dịch được.
Một cấu hình 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 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í.
Đây là cách thay thế được hỗ trợ để kết nối middleware xử lý tài nguyên nhúng một cách thủ công.
Serving from shared storage
Hai đăng ký bổ sung tồn tại cho các triển khai mà nút 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 Distributed Deployments; các chữ ký là:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // hàng đợi xuất bản nền tùy chọn tham gia
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // kho lưu trữ nền chia sẻ cho việc 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 : BaseCloudHandlerUseDoconutWebFarm(...) và WebFarmOptions không tồn tại trong phiên bản này. Xem migration guide để biết ánh xạ từng cài đặt.
Ordering recap
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?