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 chuyển động
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 một 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 triển khai 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ởi việc hết hạn bộ nhớ đệm hoặc một CloseDocument(token) rõ ràng.
Bạn không còn tự tạo nó nữa. AddDoconut() đăng ký nó như một dịch vụ tạm thời; tiêm nó bất cứ nơi nào bạn cần:
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync($"files/{fileName}");
return Results.Content(token, "text/plain");
});Trong một ứng dụng MVC, lấy nó như một tham số khởi tạo; trong một Razor view, sử dụng
@inject Doconut.Viewer Viewer. Bộ nhớ đệm thuộc ứng dụng cho các thể hiện Viewer không còn cần thiết — và không còn đúng, vì chúng không giữ gì đáng để lưu vào bộ nhớ đệm.
Điều gì xảy ra bên trong OpenDocumentAsync
- Cổng giấy phép. Một giấy phép bị từ chối hoặc hết hạn phiên bản (bị liệt kê đen, bị can thiệp, hoặc một bản dựng ngoài cửa sổ cập nhật của giấy phép) sẽ ném một
LicenseExceptionngay lập tức, với lý do từ chối làm thông điệp — 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ệ (khác với không có). Một giấy phép Tạm thời 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 dấu nước. - Tạo phiên. 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
IMemoryCachedưới một token GUID mới với hết hạn trượt —DocOptions.TimeOutphút, mặc định 60. Mỗi yêu cầu trang sẽ đặt lại đồng hồ. - Đăng ký bảo mật. Với
UnsafeMode = false(mặc định), token được ràng buộc với phiên ASP.NET của người gọi: một dấu hiệusecure-{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ó. - Token được trả về. Nó là thông tin xác thực duy nhất cho mọi thứ tiếp theo.
Không có bước khởi động riêng. Thư viện trước đây đã cung cấp InitCache() cho mục đích đó; nó không còn tồn tại, và không có gì thay thế nó.
Ba phương thức quá tải 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 lấy 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ấn | Mục đích |
|---|---|
?token=…&page=N | Hình ảnh trang đã render (PNG) |
?token=…&page=N&thumb=1 | Hình thu nhỏ |
?token=…&zoom=… | Render trang phóng to |
?token=…&search=term | Tì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=…© / &showlinks / &fileFormat | Sao chép văn bản, siêu liên kết và thông tin định dạng |
?token=…&meta | Siêu dữ liệu kỹ thuật DICOM; trả về 501 cho một phiên DICOM trên gói này |
?token=…&action=rotate/flip/close | Hành động trang và đóng rõ ràng |
?token=…&AnnSave=… / &AnnLoad | Lưu/tải chú thích |
Mỗi một trong các đường này đều được xác thực trước:
- Không có token → middleware trả về 404 (hoặc một biểu ngữ phiên bản khi
ShowDoconutInfo = true). - Token không xác định hoặc đã hết hạn → một hình ảnh lỗi với
Document session not found. Please re-open document. - Middleware phiên bị thiếu (với
UnsafeMode = false) → HTTP 500 vớiSession middleware not configured. Call UseSession() before UseDoconut(). - Token được mở bởi một phiên trình duyệt khác → một hình ảnh lỗi với
You Are Not Authorized To View This Page.
Nơi middleware được gắn
UseDoconut() trả lời các yêu cầu mang token, bất kể bạn gắn nó ở đâu. Một cấu hình chung giữ dạng yêu cầu lịch sử DocImage.axd trên một nhánh MapWhen, vì vậy một khách hàng hiện có vẫn gọi URL như trước. Bất kỳ lựa chọn nào, BasePath của khách hàng phải phù hợp — xem Cấu hình Viewer.
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 Triển khai Phân tán.
Đóng tài liệu
viewer.CloseDocument(token);CloseDocument loại bỏ phiên khỏi bộ nhớ đệm (đ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 — 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.
Nó được gọi trên Viewer đã tiêm. Mẫu trước — tạo một Viewer ngắn hạn trong một khối using chỉ để đóng token — không có tương đương và không cần thiết.
Những điểm cần nhớ
- Một tài liệu mở = một phiên = một token. Token là theo mỗi phiên trình duyệt, không phải URL toàn cục.
- Token hết hạn trên một cửa sổ trượt; một viewer để nghỉ quá
DocOptions.TimeOutcần mở lại. Viewercó 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?