Kích hoạt Widget Chuyển Đổi Drop‑in của Doconut trong .NET 8
← Back to Blog••6 min read

Kích hoạt Widget Chuyển Đổi Drop‑in của Doconut trong .NET 8

Đăng ký và kích hoạt widget chuyển đổi drop‑in của Doconut trong .NET 8

Widget drop‑in là giao diện sẵn có của Doconut để tải lên một tệp, thực hiện chuyển đổi và tải xuống kết quả.
Mặc định, ba endpoint ?convert= của widget trả về 404; chúng chỉ hoạt động khi bạn đăng ký plugin Converter và gọi AddConverterWidget() trên DoconutOptions.

Dưới đây là cấu hình khởi động đầy đủ, sẵn sàng sao chép, đáp ứng cả hai yêu cầu.

1. Các yêu cầu trước – giấy phép và hỗ trợ phiên

  • License – Plugin Converter yêu cầu một giấy phép cung cấp khả năng Converter. Đặt tệp (ví dụ, Doconut.Viewer.lic) ở vị trí mà ứng dụng có thể truy cập và chỉ định DoconutOptions.LicensePath tới nó.
  • Session state – Mô hình bảo mật của Doconut lưu trữ token phiên tài liệu trong session của ASP.NET Core. Thêm một cache phân tán và AddSession() trước khi middleware được kết nối.
builder.Services.AddDistributedMemoryCache();   // cần thiết cho phiên làm việc
builder.Services.AddSession();                  // cho phép phiên được hỗ trợ bởi IDistributedCache

2. Đăng ký các dịch vụ lõi của Doconut

AddDoconut() là điểm vào duy nhất để tiêm viewer, dịch vụ giấy phép và registry plugin.

builder.Services.AddDoconut(options =>
{
    // Cho Doconut biết nơi tìm tệp giấy phép.
    options.LicensePath = "Doconut.Viewer.lic";

    // Đăng ký plugin Converter – điều này cũng xác thực khả năng giấy phép.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Nếu giấy phép không bao gồm khả năng Converter, lời gọi trên sẽ ném InvalidOperationException và ứng dụng sẽ không khởi động. Hành vi fail‑fast này ngăn bạn triển khai bản dựng không có giấy phép hợp lệ.

3. Bật widget bằng AddConverterWidget

Widget này là tùy chọn. Gọi AddConverterWidget() đăng ký ba endpoint chuyển đổi (?convert=open, ?convert=run, ?convert=download) và cấu hình một lượng nhỏ cài đặt phía client (kích thước tải lên tối đa, đường dẫn cơ bản, v.v.).

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();

    // Bật giao diện drop‑in và đặt giới hạn tải lên phía máy khách.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // kiểm tra trước phía máy khách; máy chủ thực thi giới hạn riêng của nó
    });
});

Chỉ lời gọi AddConverterWidget tạo ra các endpoint; tệp JavaScript tĩnh (doconutConverter.js) luôn được phục vụ như một tài nguyên nhúng, nhưng sẽ không thể liên lạc với máy chủ nếu các endpoint thiếu.

4. Kết nối middleware theo đúng thứ tự

Middleware phục vụ tài nguyên tĩnh UseDoconutResources phải chạy trước middleware viewer cuối cùng UseDoconut. Middleware session cũng cần được đặt trước vì Doconut xác thực phiên trên mỗi yêu cầu.

app.UseSession();           // phải đứng trước UseDoconut()
app.UseDoconutResources();  // phục vụ JS, CSS, hình ảnh
app.UseDoconut();           // xử lý ?convert= và các yêu cầu trang tài liệu

Với pipeline này, một yêu cầu tới /doconut-res/doconutConverter.js sẽ thành công, và widget có thể gọi /doconut?convert=open, /doconut?convert=run, và /doconut?convert=download.

5. Widget thực sự làm gì

Giai đoạnEndpoint máy chủPhản hồi điển hình
Mở?convert=openTrả về một payload JSON chứa một token, số trang, phần mở rộng nguồn, và danh sách các định dạng đích được phép.
Chạy?convert=runBắt đầu chuyển đổi và trả về một downloadToken, số trang kết quả, tên tệp đề xuất, và một cờ cho biết liệu đầu ra có được dán watermark hay không.
Tải xuống?convert=downloadPhát luồng tệp đã chuyển đổi khi client theo URL tải xuống được cung cấp.

Phía client, widget thực hiện kiểm tra kích thước tải lên trước dựa trên widget.MaxUploadMb. Nếu tệp vượt quá giới hạn này, widget sẽ hủy tải lên và kích hoạt callback onError với phase = "open" và một thông báo thân thiện. Máy chủ áp dụng giới hạn riêng và sẽ trả lời 413 Payload Too Large nếu yêu cầu vượt qua kiểm tra phía client.

6. Kết nối vào các sự kiện của widget (không cần phía C#)

Tất cả các callback (onReady, onSourceLoaded, onConverted, onError, v.v.) là các hàm JavaScript được cung cấp bởi trang chứa widget. Vì câu hỏi tập trung vào phía đăng ký, bạn không cần viết bất kỳ mã C# nào thêm để xử lý các callback này — widget sẽ tự động gọi chúng khi các endpoint đã hoạt động.

7. Những lỗi thường gặp và cách tránh

Triệu chứngNguyên nhân khả dĩCách khắc phục
404 on /doconut?convert=openAddConverterWidget() đã bị bỏ qua.Thêm lời gọi như đã hiển thị trong mục 3.
Ứng dụng không khởi động được với InvalidOperationException về khả năng thiếuTệp giấy phép không cấp Converter.Lấy một giấy phép bao gồm khả năng Converter.
Lỗi 500 liên quan tới sessionUseSession() được đặt sau UseDoconut() hoặc thiếu đăng ký cache.Đảm bảo app.UseSession() chạy trước app.UseDoconut() và một dịch vụ cache đã được đăng ký.

8. Chạy ứng dụng và xem widget hoạt động

  1. Xây dựng và chạy dự án ASP.NET Core.
  2. Mở một trang chứa phần tử <div id="doconut-convert"></div> và bao gồm script chuyển đổi của Doconut (script được phục vụ tự động từ /doconut-res/doconutConverter.js).
  3. Kéo một tệp được hỗ trợ (PDF, DOCX, DWG, v.v.) vào khu vực thả.
  4. Widget sẽ gọi ?convert=open, sau đó ?convert=run, và cuối cùng hiển thị một liên kết Download trỏ tới ?convert=download.

Nếu ba endpoint trả về JSON thay vì 404, widget đã được đăng ký đúng và sẵn sàng cho môi trường sản xuất.

Bước tiếp theo: Thêm các đoạn mã trên vào Program.cs (hoặc Startup.cs) của bạn, xác nhận tệp giấy phép có sẵn, và khởi chạy ứng dụng. Widget chuyển đổi drop‑in sẽ hoạt động mà không cần bất kỳ thay đổi nào phía máy chủ.

#dotnet#doconut#converter#widget#plugin#bộ chuyển đổi
← Previous Post

Xây dựng một Trình xem Quản lý Tài liệu Bảo mật trong .NET với Doconut

Next Post →

Cách cấu hình Doconut cho triển khai máy chủ phân tán