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

บทนำ

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

Doconut's .NET 8 Converter Plugin เปิดเผยการแปลงผ่านบริการ DocumentConverter ที่ฉีดพึ่งพา คู่มือฉบับนี้มุ่งเน้นที่การลงทะเบียนและโมเดล API ปัจจุบันและหลีกเลี่ยงการเชื่อมต่อการแปลงกับเซสชัน viewer

---

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

ติดตั้งแพคเกจ viewer และ converter พื้นฐาน:

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

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

ลงทะเบียนปลั๊กอิน Converter

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

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

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

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

ฉีด DocumentConverter เข้าไปใน endpoint หรือบริการที่เป็นเจ้าของคำขอแปลง. ตัวสร้างของ converter เป็น 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");
});

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

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

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

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

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

ออกแบบการแปลงเบื้องหลังเป็นเวิร์กโฟว์ของแอปพลิเคชัน

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

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

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

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

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

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

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

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

ดูภาพรวมอย่างเป็นทางการของ ปลั๊กอิน Doconut Converter และ เอกสาร Doconut สำหรับข้อมูลผลิตภัณฑ์และการผสานรวมล่าสุด.