Chuyển Đổi Tài Liệu Phía Máy Chủ trong .NET với Doconut

Giới thiệu

Chuyển đổi tài liệu phía máy chủ cho phép một ứng dụng tạo ra đầu ra chuẩn hoá mà không cần tự động hoá Microsoft Office hoặc gửi nguồn tới một dịch vụ chuyển đổi trực tuyến riêng. Điều này có thể đơn giản hoá các cổng tài liệu, công việc nền, và quy trình xuất khẩu có kiểm soát — nhưng ứng dụng chủ vẫn sở hữu kiểm soát truy cập, lưu trữ, giữ lại, giám sát và giao kết quả.

Các định dạng tài liệu trừu tượng chảy qua một pipeline chuyển đổi thành một đầu ra chuẩn hoá

Plugin Converter .NET 8 của Doconut cung cấp khả năng chuyển đổi thông qua dịch vụ DocumentConverter được tiêm phụ thuộc. Hướng dẫn này tập trung vào cách đăng ký hiện tại và mô hình API, đồng thời tránh việc gắn chuyển đổi vào một phiên xem tài liệu.

Cài đặt các gói phù hợp

Cài đặt các gói viewer và converter cơ bản:

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Converter

Giữ cả hai gói ở cùng một phiên bản phát hành. Khi việc xây dựng có thể tái tạo là quan trọng, hãy ghim phiên bản trong file dự án hoặc truyền cùng một giá trị --version cho cả hai lệnh.

Đăng ký Plugin Converter

Các plugin được đăng ký bên trong callback tùy chọn AddDoconut. Không có phương thức đăng ký riêng AddConverter():

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

Ứng dụng phải sử dụng giấy phép cho phép khả năng Converter. Hãy giải quyết các lỗi khởi động và giấy phép trước khi chấp nhận công việc chuyển đổi; không trì hoãn chúng vào hàng đợi nền nơi chúng khó chẩn đoán hơn.

Chuyển đổi tệp từ C#

Tiêm DocumentConverter vào endpoint hoặc service chịu trách nhiệm yêu cầu chuyển đổi. Constructor của converter là nội bộ, vì vậy mã ứng dụng không nên khởi tạo trực tiếp.

app.MapPost("/api/convert", async (
    DocumentConverter converter,
    CancellationToken ct) =>
{
    await using Stream pdf = await converter.ConvertAsync(
        "documents/contract.docx",
        ConversionTarget.Pdf,
        ct: ct);

    using var copy = new MemoryStream();
    await pdf.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "contract.pdf");
});

Luồng trả về có thể di chuyển vị trí và được đặt ở đầu. Người gọi sở hữu nó và nên giải phóng sau khi sao chép hoặc trả về nội dung.

Chuyển đổi luồng đã tải lên

Phiên bản overload cho luồng cần phần mở rộng nguồn — bao gồm dấu chấm đầu — vì converter dùng nó để xác định định dạng nguồn:

app.MapPost("/api/convert-upload", async (
    IFormFile file,
    DocumentConverter converter,
    CancellationToken ct) =>
{
    var extension = Path.GetExtension(file.FileName);
    await using var source = file.OpenReadStream();
    await using Stream output = await converter.ConvertAsync(
        source,
        extension,
        ConversionTarget.Pdf,
        password: null,
        ct: ct);

    using var copy = new MemoryStream();
    await output.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "converted.pdf");
});

Xem xét tên tệp và phần mở rộng là đầu vào không đáng tin cậy. Áp dụng giới hạn tải lên, xác thực loại nguồn, ủy quyền người dùng yêu cầu, và tránh dùng tên tệp đã gửi làm đường dẫn lưu trữ.

Chọn mục tiêu dựa trên khả năng thực tế

Plugin cung cấp enum ConversionTarget, nhưng không phải mọi định dạng nguồn đều có thể tạo ra mọi mục tiêu. Giao diện UI tùy chỉnh nên hiển thị chỉ các mục tiêu được phép cho nguồn đã tải lên thay vì liệt kê mọi giá trị enum.

Khi sử dụng widget converter tùy chọn của Doconut, phản hồi mở của nó bao gồm allowedTargets. Hãy dùng phản hồi này làm nguồn sự thật cho tệp hiện tại.

Thiết kế chuyển đổi nền như một quy trình làm việc của ứng dụng

Converter có thể được gọi từ một service ứng dụng hoặc worker trong hàng đợi. Một công việc mạnh mẽ thường bao gồm:

Yêu cầu đã xác thực ghi lại nguồn và mục tiêu mong muốn.
Thông điệp hàng đợi chứa ID công việc ứng dụng, không phải thông tin đăng nhập thô.
Worker truy xuất nguồn qua một lớp trừu tượng lưu trữ có ủy quyền.
Hoạt động chuyển đổi có giới hạn thời gian hủy.
Lưu trữ đầu ra bền vững với quy tắc giữ lại rõ ràng.
Cập nhật trạng thái mà không lộ đường dẫn nội bộ hoặc chi tiết ngoại lệ nhạy cảm.

Đo lường mức đồng thời với các tài liệu đại diện trước khi quyết định số lượng worker. Chi phí chuyển đổi thay đổi tùy theo định dạng nguồn, độ phức tạp tài liệu, phông chữ, hình ảnh và mục tiêu đầu ra.

Giữ các claim bảo mật chính xác

Chạy converter bên trong ứng dụng .NET của bạn có nghĩa là hoạt động chuyển đổi không yêu cầu tự động hoá Microsoft Office hoặc API chuyển đổi trực tuyến riêng. Điều này không tự động đảm bảo tính riêng tư, tuân thủ, xóa bỏ hoặc mã hoá cho toàn bộ hệ thống.

Những thuộc tính này phụ thuộc vào cách ứng dụng xác thực người dùng, truy xuất tệp nguồn, cấu hình lưu trữ, bảo vệ log, phân phối đầu ra và loại bỏ dữ liệu tạm thời hoặc đã giữ lại.

Danh sách kiểm tra vận hành

Giữ các phiên bản Doconut.NET8 và Doconut.NET8.Converter đồng bộ.
Đăng ký ConverterPlugin trong cấu hình dịch vụ.
Tiêm DocumentConverter qua dependency injection.
Bao gồm dấu chấm đầu trong phần mở rộng nguồn của luồng.
Giải phóng luồng nguồn và kết quả.
Sử dụng hủy và giới hạn kích thước tệp ở mức ứng dụng.
Xác thực hỗ trợ nguồn‑đến‑mục tiêu thay vì giả định mọi cặp đều hoạt động.
Kiểm tra độ trung thực và sử dụng tài nguyên với các tệp đại diện.
Giữ quyết định lưu trữ, ủy quyền, audit và giữ lại trong mã ứng dụng.

Xem tổng quan chính thức của Plugin Converter Doconut và tài liệu Doconut để biết thông tin sản phẩm và tích hợp hiện tại.