ปลั๊กอินแปลงไฟล์

ปลั๊กอิน Converter ทำให้ Doconut กลายเป็นบริการแปลงเอกสาร มันเป็นส่วนสำคัญของเอนจินที่อยู่เบื้องหลังฟาซาเด DocumentConverter สาธารณะ และ — ตามการเลือก — วิดเจ็ตแบบ drop‑in ที่มีสัญญา HTTP ของตัวเอง ทำให้คุณสามารถแปลงเอกสารจาก C#, จากวิดเจ็ต, หรือจากส่วนหน้า (frontend) ที่คุณเขียนเองได้

ติดตั้งแพคเกจ

Install the latest stable Converter plugin:

dotnet add package Doconut.NET8.Converter

To pin the plugin to the current 26.7.0 release, pass the version separately:

dotnet add package Doconut.NET8.Converter --version 26.7.0

Keep the Converter package at the same version as Doconut.NET8. The package ID is Doconut.NET8.Converter; .26.7.0 appears only in the downloaded .nupkg filename.

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

ไม่มีเมธอด AddConverter() — โมเดลปลั๊กอินของ Doconut มีความสอดคล้องกันทุกตัว ปลั๊กอินทั้งหมด รวมถึง Converter ด้วย จะลงทะเบียนในรูปแบบเดียวกัน: เรียก AddPlugin<TPlugin>() ภายใน AddDoconut() ConverterPlugin มาพร้อมกับแพคเกจ NuGet ของมันเอง คือ Doconut.NET8.Converter ซึ่งจะถูกติดตั้งพร้อมกับแพคเกจตัวดูเอกสารพื้นฐาน

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

การเรียกนี้จะโยนข้อยกเว้นในขั้นตอนเริ่มต้นหากไม่มีใบอนุญาต, มีไฟล์ TRIAL เก่า, หรือใบอนุญาตที่ไม่ใช่แบบชั่วคราวซึ่งไม่ได้ให้ความสามารถ Converter — จะเกิด InvalidOperationException จากภายใน AddDoconut() ก่อนแอปจะให้บริการคำขอ ใบอนุญาตแบบ Demo/NFR ชั่วคราวจะได้รับการยอมรับ; หลังจากหมดอายุตามปฏิทิน การแปลงยังคงทำได้แต่ผลลัพธ์จะมีลายน้ำ ไม่มีระดับฟรีแบบเงียบ ดู การตั้งค่าใบอนุญาต เพื่อดูวิธีโหลดใบอนุญาต

แปลงจาก C#

การแปลงแต่ละครั้งจะคืนค่า MemoryStream ที่สามารถเลื่อนตำแหน่งได้และอยู่ที่ตำแหน่ง 0 พร้อมให้อ่านหรือคัดลอกทันที ให้ดึง DocumentConverter จาก DI ทุกที่ที่ต้องการ — มันไม่มีสถานะ (stateless) โดยออกแบบ ดังนั้นอินสแตนซ์เดียวจึงปลอดภัยต่อการใช้งานซ้ำหลายคำขอ

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

สองประเด็นที่มักทำผิดง่าย: sourceExtension ใน overload ที่รับสตรีมต้องมีจุดนำหน้า (".xlsx" ไม่ใช่ "xlsx") — ตัวแปลงจะตรวจสอบกับแคตาล็อกรูปแบบและส่วนขยายที่ไม่มีจุดจะไม่สามารถจับคู่ได้ และแม้ชื่อจะบอกว่า WordToHtmlAsync จะคืนค่า Task<Stream> ไม่ใช่ Task<string> — คุณจะได้เอกสาร HTML (รูปภาพฝังเป็น Base64) เป็นสตรีม เหมือนกับผลลัพธ์การแปลงทุกประเภทอื่น ๆ

รูปแบบเป้าหมาย

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

ไม่ใช่ทุกแหล่งข้อมูลจะสามารถแปลงเป็นทุกรูปแบบเป้าหมายได้ — ปลั๊กอินจะแมปตระกูลรูปแบบของแหล่ง (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, เอกสารเว็บ) ไปยังชุดเป้าหมายที่อนุญาตของมันเอง อย่า hardcode enum นี้เป็นรายการเป้าหมายของ UI ของคุณ: ?convert=open จะคืนค่า allowedTargets ที่แท้จริงสำหรับไฟล์ที่เพิ่งอัปโหลด และควรใช้ค่านั้นเป็นตัวขับเคลื่อนตัวเลือก

วิดเจ็ตแบบ Drop‑in

เอ็นด์พอยต์ ?convert=open|run|download ของวิดเจ็ตเป็นแบบ opt‑in และถูกปิดใช้งานโดยค่าเริ่มต้น — ปลอดภัยโดยค่าเริ่มต้น ให้เปิดใช้งานด้านเซิร์ฟเวอร์พร้อมกับการลงทะเบียนปลั๊กอิน

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

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

หากไม่ได้เรียก AddConverterWidget() เอ็นด์พอยต์สามตัว ?convert= จะตอบ 404 — แต่ไฟล์ JS ยังคงให้บริการ (เป็นทรัพยากรสแตติกที่ฝังอยู่; มีเพียงเอ็นด์พอยต์ที่ถูกเรียกเท่านั้นที่ถูกกั้น) AddConverterWidget() ยังต้องการให้ปลั๊กอิน Converter ถูกลงทะเบียนและต้องมีใบอนุญาตที่ให้สิทธิ์ Converter — มันไม่ได้ให้สิทธิ์การแปลงโดยอัตโนมัติ

ปรับแต่งวิดเจ็ต

ตัวเลือกเริ่มต้นที่ส่งให้ Doconut.convert(selector, options):

คอลแบ็ก:

Doconut.convert() คืนค่าอินสแตนซ์ของวิดเจ็ตเอง — เก็บอ้างอิงไว้เพื่อควบคุมวิดเจ็ตแบบโปรแกรมเมติก:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // กลับไปที่หน้าจอว่าง/ดรอป; ไม่ทำการเรียก onReady อีกครั้ง
conv.loadFile(file);  // เริ่มกระบวนการด้วยอ็อบเจกต์ File; ไม่ทำอะไรหากไม่ได้อยู่ในสถานะว่าง
conv.destroy();       // ลบ listener, ล้าง mount; อินสแตนซ์จะไม่สามารถใช้ได้ต่อไป

สร้างส่วนหน้า (frontend) ของคุณเอง

วิดเจ็ตเป็นเพียงไคลเอนต์สำหรับสัญญา HTTP นี้ — คุณสามารถสร้างส่วนหน้าเองโดยเรียกใช้สัญญานี้โดยตรงเพื่อ UX ที่แตกต่างกัน ทั้งสามเส้นทางอยู่ภายใต้สาขา ASP.NET ที่ UseDoconut() ถูกแมป (โดยปกติคือ /doconut):

ไบต์ของไฟล์ต้นฉบับจะถูกเก็บไว้ที่เซิร์ฟเวอร์เป็นเวลา 30 นาที; หลังจากช่วงเวลานั้น run จะตอบ 404 และต้องเปิดไฟล์ใหม่ ผลลัพธ์ที่แปลงแล้วอยู่ใน stash เดียวกัน — downloadToken จะได้รับหน้าต่าง 30 นาทีใหม่เมื่อการแปลงเสร็จ — ส่วน resultToken เป็น token ของเซสชันตัวดูปกติที่อายุการใช้งานตามแคชของตัวดู, ไม่ขึ้นกับ stash

sourceExt ในการตอบ open จะไม่มีจุดนำหน้า (เช่น "docx") — ตรงกันข้ามกับพารามิเตอร์ sourceExtension ของ DocumentConverter.ConvertAsync ที่ต้องมีจุดนำหน้า

โหมดความล้มเหลว แบ่งตามเส้นทาง:

ความเป็นเจ้าของทรัพยากร

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

สำหรับวิดเจ็ตบนเว็บ stash ของการอัปโหลดและดาวน์โหลดมี TTL 30 นาทีแยกกัน token resultToken ของตัวดูจะอายุตามเซสชันของตัวดู การปิดผลลัพธ์ของตัวดูจะไม่ลบ stash ของการดาวน์โหลดที่ยังคงมีอายุ, และการรีเซ็ตวิดเจ็ตในเบราว์เซอร์จะไม่ขยาย TTL ใด ๆ ทั้งสอง

การแก้ไขปัญหา

การใส่น้ำลายน้ำ

เมื่อ ConverterPlugin ถูกลงทะเบียน ใบอนุญาตของโฮสต์จะอยู่ในหนึ่งในสามสถานะ:

เส้นทางการเรียกทั้งสองคำนวณค่าสถานะจากกฎเดียวกัน: ฟาซาเด C# DocumentConverter ดึงค่าจากสถานะ IsViewerLicensed และ IsTemporary ของใบอนุญาต, ส่วน handler ?convert=run ของวิดเจ็ตทำการตรวจสอบเทียบเท่า (IsViewerLicensed && !IsTrial && !IsTemporary) เพื่อเติมฟิลด์ watermarked ที่ส่งกลับ การรวมเข้ากับระบบสามารถสร้างและทดสอบแบบ end‑to‑end ด้วยใบอนุญาตการประเมินก่อนซื้อ — เพียงแค่ผลลัพธ์ไบต์เท่านั้นที่เปลี่ยนแปลง.