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 biệt. Đ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 đường ống 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 việc đăng ký hiện tại và mô hình API, đồng thời tránh gắn kết chuyển đổi với 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 trình xem cơ bản và bộ chuyển đổi:

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 cố định phiên bản trong tệp 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.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Ứng dụng phải sử dụng giấy phép cho phép tính 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 hoãn chúng vào hàng đợi nền nơi chúng sẽ khó chẩn đoán hơn.

Chuyển Đổi Tệp Từ C#

Tiêm DocumentConverter vào endpoint hoặc dịch vụ chịu trách nhiệm yêu cầu chuyển đổi. Hàm khởi tạo của converter là nội bộ, vì vậy mã ứng dụng không nên tạo thể hiện của nó một cách 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 sử 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");
});

Xử lý tên tệp và phần mở rộng như là đầu vào khô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 cho người dùng yêu cầu, và tránh sử dụng tên tệp đã gửi làm đường dẫn lưu trữ.

Chọn Đích Đến Dựa Trên Khả Năng Thực Tế

Plugin cung cấp một enum ConversionTarget, nhưng không phải mọi định dạng nguồn đều có thể tạo ra mọi đích đến. Giao diện người dùng tùy chỉnh nên hiển thị chỉ các đích được phép cho nguồn đã tải lên thay vì hiển thị 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. Sử dụng phản hồi này làm nguồn thông tin chính xác cho tệp hiện tại.

Thiết Kế Chuyển Đổi Nền Nạ Như Một Quy Trình Ứng Dụng

Converter có thể được gọi từ một dịch vụ ứ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à đích mong muốn.
Tin nhắn hàng đợi chứa ID công việc ứng dụng, không phải thông tin xác thực thô.
Worker lấy nguồn thông qua một lớp trừu tượng lưu trữ đã được ủy quyền.
Một hoạt động chuyển đổi có giới hạn kèm khả năng hủy.
Lưu trữ đầu ra bền vững với các quy tắc giữ lại rõ ràng.
Cập nhật trạng thái mà không lộ các đường dẫn nội bộ hoặc chi tiết ngoại lệ nhạy cảm.

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

Giữ Các Khiếu Nại Bảo Mật Chính Xác

Chạy converter 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 một API chuyển đổi trực tuyến riêng. Nó 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, lấy tệp nguồn, cấu hình lưu trữ, bảo vệ log, phân phối đầu ra và xóa dữ liệu tạm thời hoặc đã lưu giữ.

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 quá trình cấu hình dịch vụ.
Giải quyết DocumentConverter thông qua tiêm phụ thuộc.
Bao gồm dấu chấm đầu trong phần mở rộng nguồn của luồng.
Giải phóng các 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ợ từ nguồn tới đích thay vì giả định mọi cặp đều hoạt động.
Kiểm tra độ chính xác và sử dụng tài nguyên với các tệp đại diện.
Giữ các quyết định về lưu trữ, ủy quyền, kiểm toán và giữ lại trong mã ứng dụng.

Xem tổng quan chính thức của Plugin Converter của 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.