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

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

Install the package

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

dotnet add package Doconut.NETStandard.Converter

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

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

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

Register the plugin

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

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

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

Convert from C#

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

viewer.Converter.GetConverter() ไม่มีอยู่ที่นี่ การแปลงไม่ผ่านอินสแตนซ์ของตัวดูอีกต่อไป: แทนที่ด้วยการฉีด Doconut.DocumentConverter

// Inject DocumentConverter; ตัวสร้างของมันเป็น internal, ดังนั้นห้าม `new` มันเลย.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension รวมจุดนำหน้า. password เป็น null เว้นแต่เอกสารถูกป้องกัน.
Stream png = await converter.ConvertAsync(stream, ".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) เป็นสตรีม, เช่นเดียวกับผลลัพธ์การแปลงอื่น ๆ ทุกอัน

Target formats

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, เป็นต้น — แต่ละตระกูลมี enum EnTargetFormat ย่อยของตนเอง, พร้อมกับ enum SourceFormatConverter สำหรับอินพุต ทั้งหมดนี้ได้หายไป; ดู คู่มือการย้าย

ไม่ใช่ทุกแหล่งข้อมูลที่แปลงเป็นทุกเป้าหมาย — ปลั๊กอินทำการแมปตระกูลฟอร์แมตของแต่ละแหล่ง (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();         // กลับไปที่หน้าจอ idle/drop; ไม่ทำการเรียก onReady อีกครั้ง
conv.loadFile(file);  // เริ่มกระบวนการด้วยอ็อบเจ็กต์ File; ไม่ทำอะไรหากไม่ได้อยู่ในสถานะ idle
conv.destroy();       // ลบผู้ฟัง, ทำให้ mount ว่าง; อินสแตนซ์จะไม่สามารถใช้ได้หลังจากนี้

สร้างส่วนหน้าเอง

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

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

sourceExt ในการตอบสนอง open ไม่มีจุดนำหน้า (เช่น "docx") — ตรงข้ามกับแนวปฏิบัติของพารามิเตอร์ sourceExtension บน DocumentConverter.ConvertAsync, ซึ่งต้องมีจุดนำหน้า.

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

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

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

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

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

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

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

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