ปลั๊กอินแปลงไฟล์
แปลงเอกสารเป็น 45 รูปแบบเป้าหมาย
ปลั๊กอิน Converter ทำให้ Doconut กลายเป็นบริการแปลงเอกสาร มันเป็นส่วนที่ให้เครื่องยนต์เบื้องหลังส่วนหน้าสาธารณะ DocumentConverter และ — หากเลือกใช้ — วิดเจ็ตแบบ drop‑in ที่มีสัญญา HTTP ของตนเอง เพื่อให้คุณสามารถแปลงเอกสารจาก C#, จากวิดเจ็ต, หรือจากส่วนหน้า (frontend) ที่คุณเขียนเองได้
| พื้นผิว | ใช้เมื่อ |
|---|---|
DocumentConverter (C#) | คุณแปลงบนเซิร์ฟเวอร์โดยไม่มีเบราว์เซอร์เข้ามาเกี่ยวข้อง |
วิดเจ็ตแบบ drop‑in (doconutConverter.js) | คุณต้องการหน้าจออัปโหลด, แปลงและดาวน์โหลดที่พร้อมใช้งานในหน้าเว็บของคุณ |
จุดเชื่อมต่อ HTTP (?convert=open|run|download) | คุณสร้าง UI การแปลงของคุณเองโดยอิงสัญญาเซิร์ฟเวอร์ที่มีเอกสาร |
ติดตั้งแพ็กเกจ
ติดตั้งปลั๊กอิน Converter รุ่นเสถียรล่าสุด:
dotnet add package Doconut.NETStandard.Converterเพื่อระบุเวอร์ชันของปลั๊กอินให้ตรงกับเอกสารนี้ ให้ระบุเวอร์ชันแยกต่างหาก:
dotnet add package Doconut.NETStandard.Converter --version 26.10.0รักษาแพ็กเกจ Converter ให้มีเวอร์ชันเดียวกับ Doconut.NETStandard แพ็กเกจ ID คือ
Doconut.NETStandard.Converter; .<version> ปรากฏเฉพาะในชื่อไฟล์ .nupkg ที่ดาวน์โหลดมา
ไฟล์ใบอนุญาตของปลั๊กอิน, Doconut.Viewer.Converter.lic, จะวางในโฟลเดอร์เดียวกับ Doconut.Viewer.lic; ไฟล์นี้จะถูกอ่านพร้อมกับใบอนุญาตของ viewer
ลงทะเบียนปลั๊กอิน
ไม่มีเมธอด 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>();
});นี่คือทั้งหมดที่ส่วนหน้า C# ต้องการ วิดเจ็ตและจุดเชื่อมต่อ HTTP ของมันเป็นส่วนที่ต้องเลือกใช้เพิ่มเติม, AddConverterWidget() (ดู วิดเจ็ตแบบ drop‑in).
ปลั๊กอินต้องการใบอนุญาตที่ให้ความสามารถ Converter หากไม่มี จะทำให้ AddDoconut() โยนข้อผิดพลาด InvalidOperationException ขณะเริ่มต้น ก่อนแอปจะให้บริการคำขอใด ๆ:
The Converter plugin is registered via AddPlugin but no active license grants Converter. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.ข้อผิดพลาดจะเกิดเมื่อไม่มีใบอนุญาต, ไฟล์ legacy TRIAL, ใบอนุญาตที่ขาด Converter, หรือใบอนุญาตที่ชำระแล้วใช้เกินช่วงเวอร์ชันที่กำหนด ใบอนุญาต Demo/NFR ชั่วคราวก็ได้รับการยอมรับ ไม่มีระดับฟรีแบบเงียบ ๆ ดู การตั้งค่าใบอนุญาต เพื่อดูวิธีโหลดใบอนุญาต
การให้สิทธิ์และลายน้ำ
| สถานะใบอนุญาต | การเริ่มต้น | ผลลัพธ์การแปลง |
|---|---|---|
ใบอนุญาต viewer แบบชำระที่ให้ความสามารถ Converter, อยู่ในช่วงเวอร์ชันที่กำหนด | เริ่มทำงาน | สะอาด — watermarked: false |
| ใบอนุญาตชั่วคราว (Demo/NFR) ที่ใช้งานอยู่ | เริ่มทำงาน | แปลงได้, พร้อมลายน้ำการประเมินผล — watermarked: true |
| ใบอนุญาตชั่วคราว (Demo/NFR) ที่หมดอายุ | เริ่มทำงาน | แปลงได้, พร้อมลายน้ำการประเมินผล — watermarked: true |
ไม่มีใบอนุญาต, ไฟล์ legacy TRIAL, ใบอนุญาตที่ขาด Converter, หรือใบอนุญาตชำระที่อยู่นอกช่วงเวอร์ชัน | AddDoconut() โยนข้อผิดพลาด | — |
เส้นทางการเรียกทั้งสองคำนวณค่าสถานะจากกฎเดียวกัน: ส่วนหน้า C# DocumentConverter สร้างค่านี้จากสถานะ IsViewerLicensed และ IsTemporary ของใบอนุญาตภายใน, ส่วน handler ?convert=run ของวิดเจ็ตทำการตรวจสอบเทียบเท่า (IsViewerLicensed && !IsTrial && !IsTemporary) เพื่อเติมฟิลด์ watermarked ที่มันส่งคืน การบูรณาการสามารถสร้างและทดสอบจากต้นจนจบด้วยใบอนุญาตประเมินผลก่อนการซื้อ — เพียงแค่ไบต์ผลลัพธ์ที่เปลี่ยนไป
แหล่งข้อมูล DICOM (.dcm, .ima) ก็ต้องการความสามารถ Dicom ด้วย หากไม่มี, ConvertAsync จะโยนข้อผิดพลาด LicenseException (Converting '.dcm' requires the Dicom capability license.) และคำตอบของวิดเจ็ต open จะเป็น 403.
การใช้งานจาก C#
การแปลงแต่ละครั้งจะคืนค่า MemoryStream ที่สามารถเลื่อนตำแหน่งได้ซึ่งตั้งอยู่ที่ 0 พร้อมให้อ่านหรือคัดลอกได้ทันที. แก้ไข DocumentConverter จาก DI ที่ใดก็ได้ที่คุณต้องการ — มันไม่มีสถานะตามการออกแบบ ดังนั้นอินสแตนซ์เดียวจึงปลอดภัยต่อการใช้งานซ้ำหลายคำขอ.
// 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);// html: Stream ที่ถือ HTML เพื่อแปลงกลับเป็นเอกสาร Word, เช่นผลลัพธ์ของ WordToHtmlAsync
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);สองรายละเอียดที่ง่ายต่อการทำผิด: sourceExtension บน overload ของสตรีมต้องรวมจุดนำหน้า (".xlsx", ไม่ใช่ "xlsx") — ตัวแปลงจะจับคู่กับแคตาล็อกฟอร์แมตและส่วนขยายที่ไม่มีจุดจะไม่สามารถแก้ได้. และแม้ชื่อจะบ่งบอก, WordToHtmlAsync จะคืนค่า Task<Stream>, ไม่ใช่ Task<string> — คุณจะได้รับเอกสาร HTML (รูปภาพฝังเป็น Base64) เป็นสตรีม, เช่นเดียวกับผลลัพธ์การแปลงอื่น ๆ ทุกประเภท.
ผู้เรียกใช้เป็นเจ้าของสตรีมที่คืนค่าและควรทำการ dispose หลังจากคัดลอกหรือส่งคืนเนื้อหา. เซอร์วิส DocumentConverter เองถูกแก้จาก dependency injection; อย่าสร้างหรือทำการ dispose ด้วยตนเอง.
รูปแบบเป้าหมาย
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ไม่ใช่ทุกแหล่งจะสามารถแปลงเป็นทุกเป้าหมาย — ปลั๊กอินจะแมปแต่ละตระกูลฟอร์แมตของแหล่ง (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, เอกสารเว็บ, DICOM) ไปยังชุดเป้าหมายที่กำหนดไว้. การแปลงแหล่ง DICOM (.dcm, .ima) ยังต้องการใบอนุญาตที่ให้ความสามารถ Dicom; เป้าหมายของมันคือ Pdf, Png, Jpeg, Bmp, Tiff และ Gif. อย่า hardcode enum นี้เป็นรายการเป้าหมายของ UI ของคุณ: ?convert=open จะคืนค่า allowedTargets ที่แท้จริงสำหรับไฟล์ที่เพิ่งอัปโหลด, และนั่นคือสิ่งที่ควรใช้เป็นตัวเลือก.
วิดเจ็ตแบบ Drop-in
เปิดใช้งาน endpoints
endpoint ?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;
});
});AddConverterWidget() โดยไม่มีอาร์กิวเมนต์จะเปิดใช้งานวิดเจ็ตด้วยค่าเริ่มต้น (MaxUploadMb = 25). มันไม่ได้ให้สิทธิ์การแปลงโดยตัวเอง: มันต้องการ AddPlugin<ConverterPlugin>(), หรือ AddDoconut() จะทำการโยนข้อยกเว้น:
AddConverterWidget() was called but the Converter plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() (the widget needs it), or remove the AddConverterWidget() call.หากไม่มี AddConverterWidget(), สาม endpoint ?convert= จะตอบกลับด้วย 404 — แต่ไฟล์ JS เองยังคงให้บริการอยู่ (เป็นทรัพยากรสแตติกที่ฝังอยู่; มีเพียง endpoint ที่มันสื่อสารที่ถูกจำกัด).
ฝังไว้
<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>Doconut.convert(selectorOrElement, options) รับตัวเลือก CSS หรือองค์ประกอบ, ขว้างข้อผิดพลาดหากไม่พบการเมานท์, และคืนค่า handle. วิดเจ็ตอัปโหลดไฟล์, แสดงตัวอย่างของหน้า 1, ให้ผู้ใช้เลือกหนึ่งใน allowedTargets, แปลง, แสดงตัวอย่างผลลัพธ์เมื่อทำได้, และเสนอการดาวน์โหลด.
ตัวเลือก
| ตัวเลือก | ประเภท | ค่าเริ่มต้น | หมายเหตุ |
|---|---|---|---|
basePath | string | /doconut | เส้นทางฐานสำหรับ endpoint ของ ?convert=; ต้องตรงกับสาขา ASP.NET ที่ UseDoconut() ถูกเมานท์จริง (โดยปกติประสานงานผ่าน MiddlewarePath) |
resPath | string | /doconut-res | รับเพื่อความสอดคล้องของการกำหนดค่ากับวิดเจ็ต Doconut ตัวอื่น; วิดเจ็ตแปลงยังไม่ได้สร้าง URL ใดจากค่าเหล่านี้ |
maxUploadMb | number | 25 | ตรวจสอบล่วงหน้าที่ฝั่งไคลเอนต์เท่านั้น — ปฏิเสธไฟล์ที่ใหญ่เกินขนาดก่อนอัปโหลด. เซิร์ฟเวอร์บังคับใช้ขีดจำกัดของตนเองอย่างอิสระและตอบกลับ 413 หากเกิน |
licenseUrl | string | null | null | เมื่อกำหนดค่า, จะเปลี่ยนข้อความลายน้ำบนหน้าผลลัพธ์ให้เป็นลิงก์ไปยัง URL นี้ |
labels | object | {} | แทนที่ส่วนย่อยใด ๆ ของสตริงค่าเริ่มต้นภาษาอังกฤษของวิดเจ็ต (ข้อความลากลง, ปุ่ม, การประกาศ aria-live, ข้อความแสดงข้อผิดพลาด) |
การเรียกกลับ
| การเรียกกลับ | เกิดขึ้นเมื่อ | ข้อมูลที่ส่ง |
|---|---|---|
onReady() | วิดเจ็ตได้แสดงหน้าจอพัก/ลากลง | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | ?convert=open สำเร็จ | โทเค็นเซสชันต้นทาง, จำนวนหน้า, ส่วนขยายของแหล่ง (ไม่มีจุดนำหน้า), รายการเป้าหมายที่อนุญาต |
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target }) | ?convert=run สำเร็จ | ฟิลด์เดียวกันกับการตอบสนองการรัน, พร้อมกับ target ที่ร้องขอ |
onDownload({ downloadName, downloadToken }) | ผู้ใช้คลิกที่ลิงก์ดาวน์โหลด | ทำงานพร้อมกับการดาวน์โหลดตามธรรมชาติของเบราว์เซอร์ — ไม่ดักจับหรือแทนที่ |
onError({ phase, message }) | คำขอเปิดหรือรันล้มเหลว | phase คือ 'open' หรือ 'run'; message คือข้อผิดพลาดจากเซิร์ฟเวอร์ที่ทำความสะอาดแล้ว (หรือข้อความจากไคลเอนต์สำหรับการตรวจสอบขนาดอัปโหลดล่วงหน้า) |
การเรียกกลับที่ขว้างข้อยกเว้นจะถูกจับและบันทึก; มันไม่เคยทำให้วิดเจ็ตหยุดทำงาน.
ตัวจัดการเชิงบังคับ
Doconut.convert() คืนค่าตัวอย่างของวิดเจ็ตเอง — เก็บไว้เพื่อควบคุมวิดเจ็ตโดยโปรแกรม:
const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
const file = document.querySelector('#picker').files[0]; // File จากของคุณเอง <input type="file" id="picker">
conv.reset(); // กลับไปที่หน้าจอ idle/drop; ไม่ทำการ fire ใหม่ onReady
conv.loadFile(file); // เริ่ม flow ด้วยอ็อบเจกต์ File; no-op ยกเว้นเมื่อกำลัง idle
conv.destroy(); // ลบ listeners, ทำให้ mount ว่าง; instance จะไม่สามารถใช้ได้หลังจากนี้ป้ายกำกับ
ทุกสตริงมีค่าเริ่มต้นเป็นภาษาอังกฤษ; labels แทนที่ส่วนย่อยใด ๆ และส่วนที่เหลือคงเป็นภาษาอังกฤษ. ส่วนที่เปลี่ยนแปลงระหว่างการทำงานใช้ {placeholders}, เช่น uploading: 'Uploading {name}…' และ pages: '{n} pages'.
| คีย์ | ค่าเริ่มต้นภาษาอังกฤษ |
|---|---|
dropPrompt | Drag & drop a document here |
dropHint | PDF, Word, Excel, PowerPoint, images and more |
chooseFile | Choose file |
uploading | Uploading {name}… |
page / pages | 1 page / {n} pages |
noTargets | No conversion targets are available for this file. |
convertTo / convert | Convert to / Convert |
converting | Converting to {target}… |
readyToDownload | Ready to download |
download / convertAnother | Download / Convert another |
watermarkNotice | Output is watermarked — get a license to remove it. |
retry | Retry |
genericError | Something went wrong. Please try again. |
sizeLimit | That file is larger than the {mb} MB upload limit. Please choose a smaller file. |
serverError | The server could not process this request. Please try again. |
networkError | Could not reach the server. Please check your connection and try again. |
คีย์เพิ่มเติมครอบคลุม aria-label ของโซนลากลง (dropAriaLabel), ข้อความ preview alt (previewAlt, resultAlt), รูปแบบลิงก์ของข้อความลายน้ำที่ใช้กับ licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), การตอบสนองที่ไม่สามารถอ่านได้ (badResponse) และการประกาศ aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).
ข้อผิดพลาด JSON จากเซิร์ฟเวอร์จะแสดงตามที่เซิร์ฟเวอร์เขียนไว้; serverError ใช้เฉพาะเมื่อการตอบสนองที่ล้มเหลวไม่มีข้อผิดพลาด JSON, เช่น 404 ของวิดเจ็ตที่ถูกปิดใช้งาน.
ธีม
วิดเจ็ตเพิ่มคลาส dcw ไปยังองค์ประกอบที่เมานท์และอ่านสี, รัศมีและฟอนต์จากคุณสมบัติ CSS ที่กำหนดเอง, ดังนั้นคุณสามารถปรับธีมได้โดยไม่ต้องแก้ไขภายในของมัน:
#doconut-convert.dcw {
--dcw-accent: #6b46c1;
--dcw-radius: 12px;
--dcw-font: "Inter", system-ui, sans-serif;
}ค่าเริ่มต้น: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px, และฟอนต์ UI ของระบบสำหรับ --dcw-font.
สร้างส่วนหน้าเอง
วิดเจ็ตเป็นเพียงไคลเอนต์สำหรับสัญญา HTTP นี้ — สร้างส่วนหน้าเองโดยเชื่อมต่อโดยตรงเพื่อประสบการณ์ผู้ใช้ที่แตกต่าง. เส้นทางทั้งสามอยู่ภายใต้สาขา ASP.NET ที่ UseDoconut() ถูกเมานท์ (โดยปกติคือ /doconut) และพวกมันตอบกลับ 404 จนกว่า AddConverterWidget() จะถูกเรียก. ข้อผิดพลาดมีเนื้อหา JSON, { "error": "..." }, ยกเว้นในกรณีที่ตารางระบุว่า "status only". ค่าที่ไม่รู้จักของ ?convert= จะตอบกลับด้วย 400.
| เส้นทาง | วัตถุประสงค์ | การตอบสนองสำเร็จ |
|---|---|---|
POST ?convert=open (multipart, one file) | อัปโหลดและเปิดเอกสารต้นทางเพื่อดูตัวอย่าง | 200 — { token, pages, sourceExt, allowedTargets } |
POST ?token=<token>&convert=run&target=<ext> | แปลงต้นทางที่เก็บไว้เป็น target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET ?convert=download&token=<downloadToken> | สตรีมไฟล์ที่แปลงแล้ว | 200 — file bytes, Content-Disposition: attachment, Cache-Control: no-store |
sourceExt ในการตอบกลับ open ไม่มีจุดนำหน้า (เช่น "docx") — ซึ่งตรงกันข้ามกับรูปแบบของพารามิเตอร์ sourceExtension บน DocumentConverter.ConvertAsync ที่ต้องมีจุด. allowedTargets แสดงรายการชื่อเป้าหมายเป็นตัวพิมพ์เล็ก ("pdf", "html", …); ส่งค่าหนึ่งในนั้นเป็น target ซึ่งจะจับคู่โดยไม่คำนึงถึงตัวพิมพ์ใหญ่/เล็ก. open ใช้ไฟล์แรกในส่วน multipart.
resultToken คือ null, และ resultPages คือ 0, เมื่อผลลัพธ์ไม่สามารถดูตัวอย่างได้. downloadName คือชื่อไฟล์ต้นทางพร้อมนามสกุลของเป้าหมาย.
ภาพตัวอย่างใช้เส้นทางภาพผู้ชมมาตรฐาน, {basePath}?token={token}&page=1&thumb=1&width={px}, พร้อมกับ token จาก open หรือ resultToken จาก run. วิดเจ็ตขอ width=240.
ไบต์ของแหล่งที่อัปโหลดจะถูกเก็บไว้ที่เซิร์ฟเวอร์และคงอยู่เป็นเวลา 30 นาทีหลังจากที่อ่านครั้งสุดท้าย; เมื่อช่วงเวลานั้นหมด, run จะตอบกลับด้วย 404 และไฟล์ต้องเปิดใหม่. ผลลัพธ์ที่แปลงแล้วอยู่ในที่เก็บเดียวกัน — downloadToken จะได้รับช่วงเวลา 30 นาทีใหม่เมื่อการแปลงเสร็จสิ้น — ส่วน resultToken เป็นโทเค็นเซสชันผู้ชมทั่วไปสำหรับดูตัวอย่างผลลัพธ์. เมื่อผลลัพธ์สามารถดูตัวอย่างได้, downloadToken และ resultToken มีค่าเดียวกัน. การปิดผลลัพธ์ผู้ชมจะไม่ลบที่เก็บดาวน์โหลดที่ยังมีอายุ, และการรีเซ็ตวิดเจ็ตในเบราว์เซอร์จะไม่ขยายช่วงเวลาใด ๆ.
โหมดความล้มเหลว, จัดกลุ่มตามเส้นทาง:
| เส้นทาง | สถานะ | เมื่อ | เนื้อหา |
|---|---|---|---|
| any | 404 | วิดเจ็ตไม่ได้เปิดใช้งาน (AddConverterWidget() ไม่เคยถูกเรียก) — ตรวจสอบก่อนที่เส้นทางทั้งสามจะถูกส่ง | เฉพาะสถานะ |
| any | 405 | HTTP verb ไม่ถูกต้อง (open/run ต้องการ POST; download ต้องการ GET) | เฉพาะสถานะ |
open | 400 | ไม่ใช่การอัปโหลดแบบ multipart | Expected a multipart file upload. |
open | 400 | ไม่มีไฟล์ หรือไฟล์ว่าง | No file uploaded. |
open | 400 | ส่วนขยายของแหล่งที่ไม่สามารถแปลงได้ | This file type cannot be converted. |
open | 403 | ประเภทไฟล์ต้องการความสามารถที่ใบอนุญาตไม่ได้ให้ (ไฟล์ DICOM ที่ไม่มี Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | ไฟล์ที่อัปโหลดเกิน MaxUploadMb, ตรวจสอบเทียบกับ Content-Length และขณะอ่านการอัปโหลด | File is too large. |
run | 400 | โทเค็นรูปแบบไม่ถูกต้อง (ไม่ใช่ GUID) | Invalid token. |
run | 400 | target ที่ไม่สามารถแปลงเป็น ConversionTarget | Unknown target format. |
run | 400 | target ไม่ได้อยู่ใน allowedTargets ของแหล่ง | That target format is not available for this file. |
run | 404 | การอัปโหลดที่เก็บไว้หมดอายุหรือโทเค็นไม่เคยเปิด | Upload expired — please re-open the file. |
open, run | 500 | การประมวลผลล้มเหลือภายใน | ข้อความที่ทำให้สะอาด — ทำให้สะอาดเช่นเดียวกับเส้นทางข้อผิดพลาด Doconut ทุกเส้นทาง; ไม่เปิดเผยรายละเอียดภายใน |
download | 400 | โทเค็นรูปแบบไม่ถูกต้อง (ไม่ใช่ GUID) | เฉพาะสถานะ |
download | 404 | โทเค็นดาวน์โหลดที่ไม่รู้จักหรือหมดอายุ | เฉพาะสถานะ |
การเดินทางรอบเต็มด้วย fetch:
// file: ไฟล์ที่ต้องการแปลง, ตัวอย่างเช่นจาก <input type="file">.
async function convertFile(file) {
const base = '/doconut';
// 1. open: อัปโหลดไฟล์
const form = new FormData();
form.append('file', file, file.name);
const openResp = await fetch(base + '?convert=open', { method: 'POST', body: form });
if (!openResp.ok) throw new Error((await openResp.json()).error);
const opened = await openResp.json();
// 2. run: แปลงเป็น PDF เมื่อได้รับอนุญาต, มิฉะนั้นเป็นเป้าหมายที่ได้รับอนุญาตเป็นอันดับแรก
const target = opened.allowedTargets.includes('pdf') ? 'pdf' : opened.allowedTargets[0];
const runResp = await fetch(base + '?token=' + encodeURIComponent(opened.token) +
'&convert=run&target=' + target, { method: 'POST' });
if (!runResp.ok) throw new Error((await runResp.json()).error);
const converted = await runResp.json();
// 3. download: GET ธรรมดาที่เบราว์เซอร์สามารถทำตามได้
window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}จุดเชื่อมต่อเป็น same-origin: เวอร์ชันนี้ไม่มีการสนับสนุน CORS. ให้บริการ UI ของคุณและสคริปต์วิดเจ็ตจากต้นทางเดียวกับ Doconut, หรือทำ reverse-proxy ทั้งสองเส้นทาง /doconut (เส้นทาง middleware และเส้นทาง resources) ภายใต้ต้นทางของ UI ของคุณ.
ในการผลิต
- ติดตั้งปลั๊กอิน ข้างแพ็กเกจหลัก, ที่เวอร์ชันเดียวกัน:
dotnet add package Doconut.NETStandard.Converter. - เพิ่มไฟล์ใบอนุญาต. ใส่
Doconut.Viewer.Converter.licในโฟลเดอร์เดียวกับDoconut.Viewer.lic. - ตั้งค่าขีดจำกัดของเซิร์ฟเวอร์.
MaxUploadMbในAddConverterWidgetคือขีดจำกัดที่เซิร์ฟเวอร์บังคับใช้;maxUploadMbของวิดเจ็ตเป็นเพียงการตรวจสอบด้านไคลเอนต์เท่านั้น. ให้สองค่าตรงกัน. - ให้บริการ UI จากต้นทางเดียวกัน กับจุดเชื่อมต่อ Doconut, หรือทำ reverse‑proxy (ดู สร้างส่วนหน้าเอง).
- ทำลายผลการแปลง. สตรีม
ConvertAsyncที่คืนค่ามานั้นอยู่ในพูล; การทำลายมันจะคืนบัฟเฟอร์กลับไปยังพูล.
ฟาร์มเว็บ
วิดเจ็ตเก็บการอัปโหลดแต่ละรายการและผลลัพธ์ไว้ในหน่วยความจำบนโหนดที่ให้บริการ open. หากอยู่หลังโหลดบาลานเซอร์ที่ไม่มี sticky sessions, คำขอ run, download หรือ preview ที่ตามมาภายหลังอาจไปยังโหนดอื่นและไม่พบการอัปโหลด. ลงทะเบียนที่เก็บวิดเจ็ตที่แชร์และเข้ารหัสหนึ่งครั้ง, หลังจาก AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // โฟลเดอร์ที่ทุกโหนดสามารถอ่านและเขียนได้
store.FarmKey = farmKey; // อย่างน้อย 32 bytes, เหมือนกันบนทุกโหนด
// store.Ttl = TimeSpan.FromMinutes(30); // ระยะเวลาที่ไฟล์อัปโหลดจะถูกเก็บ (ค่าเริ่มต้น)
});- เซิร์ฟเวอร์เดียวไม่ต้องทำอะไร: หากไม่มีการเรียกนี้ จะใช้ที่เก็บในหน่วยความจำ
- การอัปโหลดและผลลัพธ์ถูกเข้ารหัสที่พักบนแชร์ (AES-256, encrypt-then-MAC), และไฟล์แต่ละไฟล์ผูกกับโทเคนของมัน, ดังนั้นโทเคนหนึ่งไม่สามารถอ่านไฟล์ของโทเคนอื่นได้.
- บนแชร์, การอัปโหลดหรือผลลัพธ์จะถูกเก็บไว้เป็นเวลา
Ttlหลังจากเขียน; การอ่านไม่ขยายช่วงเวลานั้น. FarmKeyต้องมีขนาดอย่างน้อย 32 ไบต์และต้องเหมือนกันบนทุกโหนด. โหลดจากที่เก็บความลับ; อย่า hard‑code. การลงทะเบียนจะโยนArgumentExceptionเมื่อRootPathหายไปหรือFarmKeyมีความยาวน้อยกว่า 32 ไบต์.- ตั้งค่า
RootPathให้ชี้ไปที่ตำแหน่งแชร์เดียวกันที่ตัวดูแบบกระจายใช้.
เอกสารอ้างอิง API
ฟาซาเดและตัวเลือกของวิดเจ็ตอยู่ในเนมสเปซ Doconut; ConversionTarget อยู่ใน Doconut.Configs.Conversion. ConverterPlugin อยู่ใน Doconut.Plugins.Converter.
DocumentConverter
public sealed class DocumentConverter
{
public Task<Stream> ConvertAsync(
string filePath, ConversionTarget target,
string? password = null, CancellationToken ct = default);
public Task<Stream> ConvertAsync(
Stream source, string sourceExtension, ConversionTarget target,
string? password = null, CancellationToken ct = default);
public Task<Stream> WordToHtmlAsync(string filePath, CancellationToken ct = default);
public Task<Stream> HtmlToWordAsync(
Stream htmlSource, ConversionTarget outputFormat = ConversionTarget.Docx,
CancellationToken ct = default);
}ได้รับจากการฉีดพึ่งพา; ตัวสร้างเป็น internal. sourceExtension มีจุดนำหน้า. HtmlToWordAsync เขียนไฟล์ .doc เมื่อ outputFormat เป็น ConversionTarget.Doc, และไฟล์ .docx สำหรับค่าที่อื่นใด
ConversionTarget
45 รูปแบบผลลัพธ์ที่ระบุใน รูปแบบเป้าหมาย.
ConverterWidgetOptions
public sealed class ConverterWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
}ตั้งค่าผ่าน DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), ซึ่งคืนค่า DoconutOptions เพื่อให้สามารถเรียงคำสั่งได้
การแก้ไขปัญหา
| อาการ | สาเหตุ | วิธีแก้ |
|---|---|---|
AddDoconut() ขว้าง The Converter plugin is registered via AddPlugin but no active license grants Converter. | ไม่มีใบอนุญาต, ไฟล์ TRIAL, ใบอนุญาตที่ไม่มี Converter, หรือใบอนุญาตแบบชำระเงินที่อยู่นอกช่วงเวอร์ชันของมัน | ติดตั้งใบอนุญาตที่ให้สิทธิ Converter, หรือเอา AddPlugin<ConverterPlugin>() ออก |
AddDoconut() ขว้าง AddConverterWidget() was called but the Converter plugin is not registered. | วิดเจ็ตถูกเปิดใช้งานโดยไม่มีปลั๊กอินของมัน | เพิ่ม options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() |
การแก้ไข DocumentConverter ขว้าง No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>(). | ConverterPlugin ยังไม่ได้ลงทะเบียน | เพิ่ม AddPlugin<ConverterPlugin>() ภายใน AddDoconut() |
| การแปลงสตรีมบอกว่ารูปแบบไม่รองรับ | sourceExtension ไม่มีจุดนำหน้า | ส่ง ".xlsx", ไม่ใช่ "xlsx" |
ConvertAsync ขว้าง Converting '.dcm' requires the Dicom capability license. | แหล่ง DICOM, และใบอนุญาตไม่ได้ให้สิทธิ Dicom | ใช้ใบอนุญาตที่ให้สิทธิ Dicom |
| ผลลัพธ์มีลายน้ำ | ใบอนุญาตเป็นแบบชั่วคราว (Demo/NFR) | ใช้ใบอนุญาตแบบชำระเงินที่ให้สิทธิ Converter |
วิดเจ็ตโหลดแล้วแต่คำขอตอบกลับด้วย 404 | AddConverterWidget() ไม่ได้ถูกเรียก, หรือ basePath ไม่ตรงกับสาขาที่ UseDoconut() ถูกเมานท์ | เรียก AddConverterWidget(); แก้ basePath |
open ตอบกลับ 403 Converting this file type requires the Dicom capability license. | การอัปโหลด DICOM, และใบอนุญาตไม่ได้ให้สิทธิ Dicom | ใช้ใบอนุญาตที่ให้สิทธิ Dicom |
open ตอบกลับ 413 File is too large. | การอัปโหลดเกิน MaxUploadMb | ยก MaxUploadMb ใน AddConverterWidget; maxUploadMb ของวิดเจ็ตเป็นเพียงการตรวจสอบด้านไคลเอนต์ |
run ตอบกลับ 400 That target format is not available for this file. | เป้าหมายไม่ใช่หนึ่งใน allowedTargets ของแหล่ง | เสนอเฉพาะ allowedTargets จาก open |
run หรือ download ตอบกลับ 404 (Upload expired — please re-open the file. จาก run) | ช่วงเวลา 30 นาทีหมดแล้ว, หรือโหนดเว็บฟาร์มไม่มีการอัปโหลด | เปิดไฟล์อีกครั้ง; ในฟาร์ม, ลงทะเบียน AddDoconutDistributedWidgets |
| วิดเจ็ตล้มเหลวเมื่อ UI อยู่บนต้นทางอื่น | จุดเชื่อมต่อไม่มีการสนับสนุน CORS | ให้บริการ UI จากต้นทางเดียวกัน, หรือทำ reverse‑proxy เส้นทาง Doconut |
| ธีมไม่ทำงาน | ตัวแปรถูกตั้งค่าบนองค์ประกอบบรรพบุรุษหรือบนองค์ประกอบภายใน mount; กฎ .dcw ของวิดเจ็ตเองตั้งค่าไว้บน mount | กำหนดเป้าหมายที่ mount เอง: #doconut-convert.dcw หรือ #doconut-convert |
หมายเหตุของเฟรมเวิร์ก
viewer.Converter.GetConverter()ไม่มีอยู่ที่นี่. การแปลงไม่สามารถเข้าถึงผ่านอินสแตนซ์ของ viewer ได้อีกต่อไป: แทรกDoconut.DocumentConverterแทน.- enum
ConversionTargetนี้ครอบคลุมทุกครอบครัวของแหล่งข้อมูล. ไลบรารีก่อนหน้านี้มีประเภท*ConfigConverterแยกตามครอบครัว —WordConfigConverter,ExcelConfigConverter, เป็นต้น — แต่ละประเภทมี enumEnTargetFormatซ้อนอยู่ของตนเอง, พร้อมกับ enumSourceFormatConverterสำหรับอินพุต. ทั้งหมดหายไป; ดู คู่มือการย้าย. - เฉพาะ Windows เช่นเดียวกับส่วนที่เหลือของแพคเกจ .NET Standard.
หน้านี้เป็นประโยชน์หรือไม่?