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ó trên 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 → session cache (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 → auto-search)
Đường dẫn xử lý ảnh trangSingletonThự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)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 Signer Plugin)
DistributedDocumentPublisherTransientPhá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 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 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ể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 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:

csharp
app.MapHealthChecks("/health");

UseDoconut

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

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

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

UseDoconutWebFarm(...) 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

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?