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

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 các 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 đánh dấu bằng token trong IMemoryCache.
• Middleware Doconut — được thêm bằng UseDoconut(); trả lời mọi yêu cầu mà widget trình duyệt gửi (pages, thumbnails, search, annotations, …), luôn được xác thực bằng token.

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

Viewer được đóng gói, 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ằng việc hết thời gian cache hoặc bằng cách gọi CloseDocument(token) một cách 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 kỳ 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, nhận nó như một tham số của constructor; trong một Razor view, sử dụng @inject Doconut.Viewer Viewer. Các cache do ứng dụng sở hữu 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 để cache.

Những gì xảy ra bên trong OpenDocumentAsync

1. 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ị đưa vào danh sách đen, bị giả mạo, hoặc một bản dựng ngoài thời gian cập nhật của giấy phép) sẽ ném ra LicenseException ngay lập tức, với lý do từ chối làm thông điệp — việc mở sẽ không giảm chất lượng một cách âm thầm đối với giấy phép không hợp lệ (khác với việc không có giấy phép). 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 ra — mà giảm chất lượng thành watermark.
2. Tạo phiên. Nhà máy viewer chọn viewer định dạng phù hợp 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. Đăng ký bảo mật. 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 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.

Không có bước khởi động riêng. Thư viện trước đây cung cấp InitCache() cho mục đích đó; hiện không còn tồn tại và không có gì thay thế.

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 định dạng riêng (PdfConfig, WordConfig, …), hoặc một Stream cộng với một FileInfo mà phần mở rộng quyết định định dạng.

Cách widget nhận các trang

Widget client 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:

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

• Không có token → middleware trả về 404 (hoặc một banner phiên bản khi ShowDoconutInfo = true).
• Token không biết hoặc đã hết hạn → hình ảnh lỗi với thông báo Document session not found. Please re-open document.
• Middleware phiên bị thiếu (với UnsafeMode = false) → HTTP 500 với thông báo Session middleware not configured. Call UseSession() before UseDoconut().
• Token được mở bởi một phiên trình duyệt khác → hình ảnh lỗi với thông báo 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. Ứng dụng tham chiếu giữ dạng yêu cầu lịch sử DocImage.axd trên một nhánh MapWhen, vì vậy client hiện có vẫn gọi URL như trước. Bất kỳ lựa chọn nào, BasePath của client 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 xóa 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 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 sẽ tự động 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 khối using chỉ để đóng token — không còn 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 thuộc về 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 để không hoạt động 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.