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

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

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

ติดตั้งปลั๊กอิน Converter รุ่นเสถียรล่าสุด:

dotnet add package Doconut.NETStandard.Converter

เพื่อระบุเวอร์ชันของปลั๊กอินให้ตรงกับรุ่น 26.8.0 ปัจจุบัน, ให้ส่งเวอร์ชันแยกต่างหาก:

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

รักษาแพ็กเกจ Converter ให้เป็นเวอร์ชันเดียวกับ Doconut.NETStandard. รหัสแพ็กเกจคือ Doconut.NETStandard.Converter; .26.8.0 ปรากฏเฉพาะในชื่อไฟล์ .nupkg ที่ดาวน์โหลด.

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

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

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 ทุกที่ที่คุณต้องการ — มันไม่มีสถานะโดยออกแบบ, ดังนั้นอินสแตนซ์เดียวจึงปลอดภัยต่อการใช้ซ้ำในหลายคำขอ.

viewer.Converter.GetConverter() ไม่มีในที่นี้. การแปลงไม่ได้เข้าถึงผ่านอินสแตนซ์ viewer อีกต่อไป: ให้ฉีด Doconut.DocumentConverter แทน.

// 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) เป็นสตรีม, เช่นเดียวกับผลลัพธ์การแปลงอื่น ๆ ทุกประเภท.

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

ConversionTarget (namespace Doconut.Configs.Conversion) มีสมาชิกทั้งหมด 45 รายการ:

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

enum นี้ครอบคลุมทุกตระกูลแหล่งที่มา. ไลบรารีก่อนหน้านี้มีประเภท *ConfigConverter แยกตามตระกูล — WordConfigConverter, ExcelConfigConverter ฯลฯ — แต่ละประเภทมี EnTargetFormat enum ย่อยของตนเอง, พร้อมกับ SourceFormatConverter enum สำหรับอินพุต. ทั้งหมดนี้ได้ถูกลบออก; ดู คู่มือการย้าย.

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

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

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

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();         // back to the idle/drop screen; does not re-fire onReady
conv.loadFile(file);  // starts the flow with a File object; no‑op unless currently idle
conv.destroy();       // removes listeners, empties the mount; the instance is unusable after this

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

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

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

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

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

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

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

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

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

การใส่น้ำหนัก

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

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