Triển khai Quản lý Tài liệu với Doconut

Một quy trình quản lý tài liệu trong một cổng .NET thường cần ba điều:

1. Một cách để tải PDF, tệp Office, bản vẽ CAD hoặc hình ảnh mà không cần viết trình xem từ đầu.
2. Một token bảo mật liên kết tài liệu đã tải với phiên trình duyệt hiện tại.
3. Một bước dọn dẹp giải phóng bộ nhớ ngay khi người dùng hoàn thành.

Doconut cung cấp cả ba thông qua một dịch vụ Viewer duy nhất, một phiên IMemoryCache nhẹ, và các lời gọi CloseDocument rõ ràng.

---

1. Đăng ký trình xem trong container DI

Trong quá trình khởi động ứng dụng, thêm các dịch vụ Doconut vào container DI bằng cách gọi phương thức đăng ký Doconut được mô tả trong tài liệu chính thức. Bước này đăng ký trình xem, xử lý giấy phép và bộ nhớ đệm trong bộ nhớ sẽ chứa các phiên tài liệu.

Quá trình đăng ký xác thực giấy phép khi khởi động, vì vậy bất kỳ giấy phép thiếu hoặc không hợp lệ nào sẽ thất bại ngay và bạn sẽ biết vấn đề trước khi yêu cầu đầu tiên tới máy chủ.

---

2. Chèn middleware phục vụ hình ảnh trang, thumbnail và dữ liệu chú thích

Cấu hình middleware Doconut trong pipeline yêu cầu sao cho bất kỳ yêu cầu nào chứa chuỗi truy vấn ?token= đều được Doconut xử lý. Middleware áp dụng dấu bảo mật mặc định (secure-{token}) khi UnsafeMode là false (mặc định) và phục vụ hình ảnh trang, thumbnail và dữ liệu chú thích.

Đặt middleware trên một nhánh riêng giữ cho phần còn lại của pipeline của bạn không bị ảnh hưởng và cho phép mở rộng ngang mà không cần session dính.

---

3. Mở tài liệu và nhận token phiên không trong suốt

Tạo một endpoint duy nhất nhận đường dẫn tệp (hoặc stream) và trả về token. Token là thông tin xác thực duy nhất mà widget client có thể nhìn thấy.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Token là không trong suốt — chuyển nó cho widget, không bao giờ ghi log hoặc lưu trữ nó.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Contract.pdf");
    return Results.Ok(new { token });
});

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

1. Cổng giấy phép – một giấy phép không hợp lệ sẽ ném LicenseException ngay lập tức.
2. Tạo phiên – Doconut chọn trình xem định dạng phù hợp (PDF, Word, DWG, …) và lưu engine vào IMemoryCache dưới một token GUID.
3. Đăng ký bảo mật – với UnsafeMode = false token được gắn với phiên ASP.NET của người gọi thông qua dấu secure-{token}. Chỉ phiên trình duyệt đó có thể yêu cầu các trang.
4. Trả token – client nhận token và sử dụng nó cho mọi yêu cầu tiếp theo (/DocImage.axd?token=…).

Thời gian hết hạn trượt mặc định là 60 phút (có thể cấu hình qua DocOptions.TimeOut). Mỗi yêu cầu trang sẽ đặt lại đồng hồ, vì vậy các phiên không hoạt động sẽ tự động biến mất.

---

4. Kết xuất tài liệu phía client

Từ trình duyệt, bạn gọi endpoint, lấy token và truyền nó cho widget Doconut:

fetch('/api/open', { method: 'POST' })
    .then(r => r.json())
    .then(d => {
        const token = d.token;
        objViewer.View(token);   // JavaScript widget được cung cấp bởi Doconut
    });

Widget nội bộ gửi các yêu cầu trang, thumbnail, tìm kiếm và chú thích mà tất cả đều bao gồm token. Vì token được gắn với phiên phía máy chủ, người dùng độc hại không thể chiếm đoạt tài liệu của người dùng khác.

---

5. Đóng tài liệu ngay khi người dùng rời khỏi trình xem

Đối với các tệp PDF hoặc CAD lớn, bạn nên giải phóng engine kết xuất ngay lập tức. Gọi CloseDocument từ một endpoint phía máy chủ hoặc từ sự kiện “unload” của widget.

// Endpoint phía máy chủ
app.MapPost("/api/close", (Viewer viewer, string token) =>
{
    viewer.CloseDocument(token);
    return Results.Ok();
});

// Gọi trực tiếp từ widget (nếu bạn để lộ token cho backend)
viewer.CloseDocument(token);

CloseDocument loại bỏ phiên khỏi bộ nhớ đệm, giải phóng engine tài liệu nền, xóa dấu secure-{token}, và thu hồi quyền truy cập. Thời gian hết hạn trượt sẽ cuối cùng thực hiện điều tương tự, nhưng việc đóng rõ ràng đảm bảo bộ nhớ được thu hồi ngay khi người dùng hoàn thành.

---

6. Tùy chọn: Chuyển đổi tài liệu trên máy chủ

Nếu quy trình của bạn yêu cầu xuất PDF từ tệp Word đã tải lên, bật plugin Converter trong cấu hình Doconut (xem tài liệu). Sau khi plugin được đăng ký, bạn có thể tiêm DocumentConverter và gọi phương thức ConvertAsync của nó. Quá trình chuyển đổi chạy trên máy chủ, vì vậy bạn không bao giờ cần cài đặt Office trên máy chủ web.

---

7. Các cân nhắc mở rộng cho quản lý tài liệu cấp doanh nghiệp

• Giao diện không trạng thái – Widget trình xem không bao giờ giữ dữ liệu tài liệu; mọi xử lý nặng đều diễn ra trên máy chủ.
• Bộ nhớ đệm phân tán – Thay thế bộ nhớ đệm trong bộ nhớ mặc định bằng nhà cung cấp phân tán (Redis, NCache) nếu bạn chạy nhiều nút web‑farm. Bản đồ token‑to‑session vẫn hoạt động không thay đổi vì middleware đọc từ IMemoryCache đã cấu hình.
• Công việc nền – Bạn có thể mở trước tài liệu trong worker nền, lưu token vào bộ nhớ đệm và truyền cho UI sau. Chỉ cần nhớ mỗi token chỉ dùng một lần cho mỗi phiên; việc tái sử dụng yêu cầu một lời gọi OpenDocumentAsync mới.

Những mẫu này cho phép bạn xây dựng một nền tảng quản lý tài liệu có thể mở rộng từ cổng intranet máy chủ đơn đến dịch vụ đám mây đa vùng mà không cần viết lại logic trình xem.

---

8. Danh sách kiểm tra nhanh cho triển khai sẵn sàng sản xuất

Bước	Hành động
1	Đăng ký dịch vụ Doconut trong Program.cs (xác thực giấy phép).
2	Thêm middleware Doconut trên một nhánh riêng.
3	Tiết lộ một endpoint /api/open mà gọi OpenDocumentAsync.
4	Truyền token đã trả về cho objViewer.View(token) ở phía client.
5	Gọi CloseDocument(token) khi trình xem bị ẩn hoặc trang unload.
6	(Tùy chọn) Bật ConverterPlugin nếu bạn cần chuyển đổi phía máy chủ.
7	(Tùy chọn) Thay thế IMemoryCache bằng bộ nhớ đệm phân tán để mở rộng ngang.

Theo dõi danh sách, và bạn sẽ có một luồng quản lý tài liệu hoàn chỉnh, bảo mật, hiệu suất cao được xây dựng trên trình xem .NET gốc của Doconut.