การแปลงเอกสารฝั่งเซิร์ฟเวอร์ใน .NET ด้วย Doconut

บทนำ

การแปลงเอกสารฝั่งเซิร์ฟเวอร์ทำให้แอปพลิเคชันสามารถสร้างผลลัพธ์ที่เป็นมาตรฐานได้โดยไม่ต้องอัตโนมัติ Microsoft Office หรือส่งไฟล์ต้นฉบับไปยังบริการแปลงออนไลน์แยกต่างหาก ซึ่งสามารถทำให้พอร์ทัลเอกสาร งานเบื้องหลัง และกระบวนการส่งออกที่ควบคุมได้ง่ายขึ้น—แต่แอปพลิเคชันโฮสต์ยังคงเป็นเจ้าของการควบคุมการเข้าถึง การจัดเก็บ การเก็บรักษา การตรวจสอบ และการส่งมอบผลลัพธ์

ปลั๊กอินแปลงไฟล์ .NET 8 ของ Doconut เปิดเผยการแปลงผ่านบริการ DocumentConverter ที่ฉีดพึ่งพา คู่มือนี้มุ่งเน้นที่การลงทะเบียนและโมเดล API ปัจจุบันและหลีกเลี่ยงการเชื่อมโยงการแปลงกับเซสชันของผู้ชม

---

ติดตั้งแพคเกจที่ตรงกัน

ติดตั้งแพคเกจผู้ชมพื้นฐานและแพคเกจแปลงไฟล์:

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

รักษาให้ทั้งสองแพคเกจใช้เวอร์ชันปล่อยเดียวกัน เมื่อความสำคัญของการสร้างที่ทำซ้ำได้สูง ให้กำหนดเวอร์ชันในไฟล์โครงการหรือส่งค่า --version เดียวกันให้กับทั้งสองคำสั่ง

ลงทะเบียนปลั๊กอินแปลงไฟล์

ปลั๊กอินจะลงทะเบียนภายในคอลแบ็กตัวเลือก AddDoconut. ไม่มีเมธอดการลงทะเบียน AddConverter() แยกต่างหาก:

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

แอปพลิเคชันต้องใช้ใบอนุญาตที่ให้ความสามารถการแปลงไฟล์ แก้ไขข้อผิดพลาดการเริ่มต้นและใบอนุญาตก่อนรับงานแปลง; อย่าผัดผ่อนข้อผิดพลาดเหล่านั้นไปยังคิวเบื้องหลังซึ่งจะทำให้วินิจฉัยยากขึ้น

แปลงไฟล์จาก C#

ฉีด DocumentConverter เข้าไปใน endpoint หรือบริการที่รับผิดชอบคำขอการแปลง ไฟล์คอนสตรัคเตอร์ของตัวแปลงเป็น internal ดังนั้นโค้ดแอปพลิเคชันไม่ควรสร้างอินสแตนซ์โดยตรง

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");
});

สตรีมที่ส่งกลับสามารถเลื่อนตำแหน่งได้และอยู่ที่จุดเริ่มต้น ผู้เรียกเป็นเจ้าของและควรทำการ dispose หลังจากคัดลอกหรือส่งคืนเนื้อหา

แปลงสตรีมที่อัปโหลด

เมธอด overload ของสตรีมต้องการส่วนขยายของไฟล์ต้นฉบับ—รวมถึงจุดนำหน้า—เนื่องจากตัวแปลงใช้มันเพื่อระบุรูปแบบต้นฉบับ:

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");
});

พิจารณาชื่อไฟล์และส่วนขยายเป็นข้อมูลที่ไม่เชื่อถือได้ บังคับใช้ขีดจำกัดการอัปโหลด ตรวจสอบประเภทต้นฉบับ ให้สิทธิ์ผู้ใช้ที่ร้องขอ และหลีกเลี่ยงการใช้ชื่อไฟล์ที่ส่งเข้ามาเป็นเส้นทางการจัดเก็บ

เลือกเป้าหมายจากความสามารถจริง

ปลั๊กอินเปิดเผย enum ConversionTarget แต่ไม่ใช่ทุกรูปแบบต้นฉบับสามารถผลิตทุกเป้าหมาย UI ที่กำหนดเองควรแสดงเฉพาะเป้าหมายที่อนุญาตสำหรับต้นฉบับที่อัปโหลดแทนการแสดงค่า enum ทั้งหมด

เมื่อใช้วิดเจ็ตแปลงไฟล์เสริมของ Doconut การตอบกลับเปิดของมันจะรวม allowedTargets. ใช้การตอบกลับนั้นเป็นแหล่งความจริงสำหรับไฟล์ปัจจุบัน

ออกแบบการแปลงเบื้องหลังเป็นกระบวนการทำงานของแอปพลิเคชัน

ตัวแปลงสามารถถูกเรียกจากบริการแอปพลิเคชันหรือ worker ที่อยู่ในคิว งานที่แข็งแรงโดยปกติจะรวม:

1. คำขอที่ผ่านการตรวจสอบตัวตนซึ่งบันทึกต้นฉบับและเป้าหมายที่ต้องการ
2. ข้อความคิวที่มี ID งานของแอปพลิเคชัน ไม่ใช่ข้อมูลรับรองดิบ
3. Worker ที่ดึงต้นฉบับผ่านการนามธรรมการจัดเก็บที่ได้รับอนุญาต
4. การดำเนินการแปลงที่จำกัดพร้อมการยกเลิก
5. การจัดเก็บผลลัพธ์ที่ทนทานพร้อมกฎการเก็บรักษาที่ชัดเจน
6. การอัปเดตสถานะที่ไม่เปิดเผยเส้นทางภายในหรือรายละเอียดข้อยกเว้นที่ละเอียดอ่อน

วัดระดับความพร้อมทำงานพร้อมกันด้วยเอกสารตัวอย่างก่อนเลือกจำนวน worker ค่าใช้จ่ายการแปลงจะแตกต่างตามรูปแบบต้นฉบับ ความซับซ้อนของเอกสาร ฟอนต์ ภาพ และเป้าหมายผลลัพธ์

รักษาข้อเรียกร้องด้านความปลอดภัยให้ชัดเจน

การรันตัวแปลงภายในแอปพลิเคชัน .NET ของคุณหมายความว่าการแปลงไม่ต้องอัตโนมัติ Microsoft Office หรือ API แปลงออนไลน์แยกต่างหาก ซึ่งไม่ได้รับประกันความเป็นส่วนตัว การปฏิบัติตามกฎ การลบ หรือการเข้ารหัสโดยอัตโนมัติสำหรับระบบทั้งหมด

คุณสมบัติเหล่านั้นขึ้นอยู่กับวิธีที่แอปพลิเคชันตรวจสอบผู้ใช้ ดึงไฟล์ต้นฉบับ ตั้งค่าการจัดเก็บ ปกป้องบันทึก แจกจ่ายผลลัพธ์ และลบข้อมูลชั่วคราวหรือที่เก็บไว้

รายการตรวจสอบการดำเนินงาน

• รักษาเวอร์ชันของ Doconut.NET8 และ Doconut.NET8.Converter ให้สอดคล้องกัน
• ลงทะเบียน ConverterPlugin ระหว่างการกำหนดค่าบริการ
• ดึง DocumentConverter ผ่านการฉีดพึ่งพา
• รวมจุดนำหน้าในส่วนขยายของสตรีมต้นฉบับ
• ทำการ dispose สตรีมต้นฉบับและผลลัพธ์
• ใช้การยกเลิกและขีดจำกัดขนาดไฟล์ระดับแอปพลิเคชัน
• ตรวจสอบการสนับสนุนจากต้นฉบับไปยังเป้าหมายแทนการสมมติว่าทุกคู่ทำงานได้
• ทดสอบความแม่นยำและการใช้ทรัพยากรด้วยไฟล์ตัวอย่าง
• รักษาการตัดสินใจเกี่ยวกับการจัดเก็บ การให้สิทธิ์ การตรวจสอบ และการเก็บรักษาในโค้ดแอปพลิเคชัน

ดูภาพรวมของ ปลั๊กอินแปลงไฟล์ Doconut และ เอกสาร Doconut สำหรับข้อมูลผลิตภัณฑ์และการบูรณาการในปัจจุบัน.