Cách hoạt động của Viewer

Vòng đời yêu cầu tài liệu

Doconut hiển thị tài liệu dưới dạng hình ảnh phân trang được phục vụ qua middleware ASP.NET Core. Hiểu vòng đời — mở, token, yêu cầu trang, đóng — giải thích hầu hết mọi hành vi bạn sẽ quan sát, bao gồm các thông báo lỗi.

Ba thành phần di chuyển

  • Viewer — dịch vụ công cộng bạn tiêm vào. Nó mở tài liệu và trả về token phiên.
  • Phiên tài liệu — một đối tượng phía máy chủ giữ tài liệu đã tải, được khóa bằng token trong IMemoryCache.
  • Middleware Doconut — được thêm bởi UseDoconut(); trả lời mọi yêu cầu mà widget trình duyệt thực hiện (pages, thumbnails, search, annotations, …), luôn được xác thực bằng token.

Viewer là không trạng thái — theo thiết kế

Viewer được đóng kín, không giữ trạng thái tài liệu theo yêu cầu, và cố ý không thực hiện IDisposable. Các phiên tồn tại độc lập trong trình quản lý phiên và được dọn dẹp bằng việc hết thời gian cache hoặc một CloseDocument(token) rõ ràng.

Tiêm nó ở bất kỳ nơi nào bạn cần:

csharp
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

Điều gì xảy ra bên trong OpenDocumentAsync

  1. License gate. Một giấy phép bị từ chối hoặc hết hạn phiên bản (bị đưa vào danh sách đen, bị giả mạo, hoặc một bản dựng ngoài cửa sổ cập nhật của giấy phép) ném ra một LicenseException ngay lập tức, với lý do từ chối làm tin nhắn — việc mở không bao giờ giảm chất lượng một cách im lặng đối với giấy phép không hợp lệ (ngược lại với không có giấy phép). Một giấy phép Temporary hoặc thuê bao hết hạn theo lịch là ngoại lệ: nó không ném — nó giảm xuống thành watermark.
  2. Session creation. Nhà máy viewer chọn viewer định dạng đúng cho phần mở rộng tệp và tải tài liệu (xem Rendering Pipeline). Phiên được lưu trong IMemoryCache dưới một token GUID mới với thời gian hết hạn trượt — DocOptions.TimeOut phút, mặc định 60. Mỗi yêu cầu trang sẽ đặt lại đồng hồ.
  3. Security registration. Với UnsafeMode = false (mặc định), token được liên kết với phiên ASP.NET của người gọi: một dấu hiệu secure-{token} được ghi vào phiên, vì vậy chỉ phiên trình duyệt đã mở tài liệu mới có thể yêu cầu các trang của nó.
  4. Token được trả về. Nó là thông tin xác thực duy nhất cho mọi thứ tiếp theo.

Ba overload chỉ khác nhau ở đầu vào: một đường dẫn tệp, một đường dẫn tệp cộng với cấu hình theo định dạng (PdfConfig, WordConfig, …), hoặc một Stream cộng với một FileInfo mà phần mở rộng quyết định việc phát hiện định dạng.

Cách widget nhận các trang

Widget khách hàng gọi middleware Doconut với token trong chuỗi truy vấn. Những gì middleware thực hiện phụ thuộc vào yêu cầu:

Truy vấnMục đích
?token=…&page=NHình ảnh trang đã render (PNG)
?token=…&page=N&thumb=1Hình thu nhỏ
?token=…&zoom=…Render trang phóng to
?token=…&search=termTìm kiếm toàn văn (có kiểm soát giấy phép)
?token=…&bookmarksĐề cương tài liệu/dấu trang
?token=…&copy / &showlinks / &fileFormatSao chép văn bản, siêu liên kết và thông tin định dạng
?token=…&metaSiêu dữ liệu kỹ thuật DICOM; trả về 501 cho một phiên DICOM trên .NET 6
?token=…&action=rotate/flip/closeHành động trang và đóng rõ ràng
?token=…&AnnSave=… / &AnnLoadLưu/tải chú thích

Mỗi một trong các đường này đều được xác thực trước:

  • No token → middleware trả về 404 (hoặc một banner phiên bản khi ShowDoconutInfo = true).
  • Unknown or expired token → một hình ảnh lỗi với Document session not found. Please re-open document.
  • Session middleware missing (với UnsafeMode = false) → HTTP 500 với Session middleware not configured. Call UseSession() before UseDoconut().
  • Token opened by a different browser session → một hình ảnh lỗi với You Are Not Authorized To View This Page.

Phục vụ các trang từ lưu trữ chia sẻ thay vì nút mở là một cách sắp xếp hoàn toàn khác; xem Distributed Deployments.

Đóng tài liệu

csharp
viewer.CloseDocument(token);

CloseDocument loại bỏ phiên khỏi cache (điều này giải phóng engine tài liệu nền và giải phóng bộ nhớ ngay lập tức), xóa dấu hiệu secure-{token}, và thu hồi quyền truy cập. Gọi nó là tùy chọn — thời gian hết hạn trượt tự động thực hiện cùng việc dọn dẹp — nhưng đối với tài liệu lớn, đây là cách lịch sự để giải phóng bộ nhớ ngay khi người dùng hoàn thành.

Những điểm cần nhớ

  • Một tài liệu mở = một phiên = một token. Token thuộc mỗi phiên trình duyệt, không phải URL toàn cục.
  • Token hết hạn theo cửa sổ trượt; một viewer để nghỉ quá DocOptions.TimeOut cần mở lại.
  • Viewer có thể được tiêm và chia sẻ tự do; các phiên mang toàn bộ trạng thái.

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