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.

csharp
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

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 → Startup validation), và đăng ký toàn bộ đồ thị dịch vụ:

Dịch vụThời gian sốngVai trò
DoconutOptionsSingletonĐối tượng cấu hình
Dịch vụ bộ nhớ đệm phiênSingletonToken → bộ nhớ đệm phiên (IMemoryCache cũng được đăng ký)
IDoconutLicenseServiceSingletonGiấ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 ảnhSingletonThự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)SingletonCấp quyền cho việc ràng buộc token‑to‑session
ViewerTransientGiao diện mở/đóng công cộng
DocumentConverterTransientGiao diện chuyển đổi — yêu cầu plugin Converter
DocumentSignerTransientGiao diện ký — yêu cầu plugin Signer (xem Plugin Chữ ký)
DistributedDocumentPublisherTransientXuấ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 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>().

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 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 vào thời điểm AddDoconut(). 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:

csharp
app.MapHealthChecks("/health");

UseDoconut

text
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: '/'):

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() 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à:

text
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 widget

Phầ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:

text
IApplicationBuilder UseDoconutCloud<THandler>(
    this IApplicationBuilder app,
    Action<CloudOptions>? configure = null,
    string pathPrefix = "/doconut-cloud")
    where THandler : BaseCloudHandler

Tóm tắt thứ tự

csharp
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 MapWhen

Trang này có hữu ích không?