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

แปลงเอกสารเป็น 45 รูปแบบเป้าหมาย

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

ส่วนใช้เมื่อใด
DocumentConverter (C#)คุณทำการแปลงบนเซิร์ฟเวอร์โดยไม่มีเบราว์เซอร์เข้ามาเกี่ยวข้อง
Drop-in widget (doconutConverter.js)คุณต้องการหน้าจออัปโหลด, แปลงและดาวน์โหลดที่พร้อมใช้งานในหน้าของคุณ
HTTP endpoints (?convert=open|run|download)คุณสร้าง UI การแปลงของคุณเองโดยอิงสัญญาเซิร์ฟเวอร์ที่มีเอกสารอธิบาย

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

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

bash
dotnet add package Doconut.NET8.Converter

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

bash
dotnet add package Doconut.NET8.Converter --version 26.10.0

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

ไฟล์ใบอนุญาตของปลั๊กอิน, Doconut.Viewer.Converter.lic, จะอยู่ในโฟลเดอร์เดียวกับ Doconut.Viewer.lic; มันจะถูกอ่านพร้อมกับใบอนุญาตของ viewer.

แพลตฟอร์ม. ปลั๊กอินทำงานได้ทุกที่ที่ Doconut.NET8 ทำงาน: Windows, และ Linux ที่ใช้ glibc บน x64 (ไม่ใช่ Alpine หรือดิสทริบิวชันที่ใช้ musl อื่นๆ) บน Linux, ให้ติดตั้งไลบรารีการกำหนดค่าแบบอักษรก่อนที่เอกสารแรกจะเปิด:

bash
apt-get update && apt-get install -y libfontconfig1

บน RHEL, Fedora และดิสทริบิวชันที่คล้ายกัน แพคเกจคือ fontconfig. หากไม่มีมัน การเปิดเอกสารจะล้มเหลวด้วย The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

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

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

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

นั่นคือทั้งหมดที่ façade ของ C# ต้องการ วิดเจ็ตและ HTTP endpoint ของมันเป็นการเลือกใช้แยกต่างหาก, AddConverterWidget() (ดู วิดเจ็ตดรอปอิน).

ปลั๊กอินต้องการใบอนุญาตที่ให้ความสามารถ Converter. หากไม่มี, AddDoconut() จะโยน InvalidOperationException ที่การเริ่มต้น, ก่อนที่แอปจะให้บริการคำขอ:

text
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() โยนข้อผิดพลาด—

เส้นทางการเรียกใช้ทั้งสองคำนวณแฟล็กจากกฎเดียวกัน: façade C# ของ DocumentConverter สร้างขึ้นจากภายในโดยอิงจากสถานะ IsViewerLicensed และ IsTemporary ของใบอนุญาต, และตัวจัดการ ?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 ที่ใดก็ได้ที่คุณต้องการ — มันไม่มีสถานะตามการออกแบบ ดังนั้นอินสแตนซ์เดียวจึงปลอดภัยต่อการใช้งานซ้ำหลายคำขอ.

csharp
// Inject DocumentConverter; ตัวสร้างของมันเป็น internal ดังนั้นห้าม `new` มัน
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension มีจุดนำหน้าอยู่. password จะเป็น null เว้นแต่เอกสารถูกป้องกัน
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// 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 รายการ:

text
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

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

csharp
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() จะทำการ throw:

text
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(), สาม endpoints ?convert= จะตอบกลับด้วย 404 — แต่ไฟล์ JS เองยังคงให้บริการอยู่ (เป็นทรัพยากรสแตติกที่ฝังอยู่; มีเพียง endpoints ที่มันสื่อสารที่ถูกจำกัด).

ฝังวิดเจ็ต

html
<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 selector หรือ element, จะ throw หากไม่พบ mount, และคืนค่า handle. วิดเจ็ตอัปโหลดไฟล์, แสดงตัวอย่างของหน้า 1, ให้ผู้ใช้เลือกหนึ่งใน allowedTargets, ทำการแปลง, แสดงตัวอย่างผลลัพธ์เมื่อทำได้, และเสนอให้ดาวน์โหลด.

ตัวเลือก

ตัวเลือกประเภทค่าเริ่มต้นหมายเหตุ
basePathstring/doconutเส้นทางฐานสำหรับ endpoint ของ ?convert=; ต้องตรงกับสาขา ASP.NET ที่ UseDoconut() ถูกเมานท์จริง (โดยปกติประสานงานผ่าน MiddlewarePath)
resPathstring/doconut-resยอมรับเพื่อความสอดคล้องของการกำหนดค่ากับวิดเจ็ต Doconut อื่น ๆ; วิดเจ็ตแปลงยังไม่ได้สร้าง URL ใด ๆ จากค่าเหล่านี้
maxUploadMbnumber25ตรวจสอบล่วงหน้าที่ฝั่งไคลเอนต์เท่านั้น — ปฏิเสธไฟล์ที่ใหญ่เกินขนาดก่อนอัปโหลด. เซิร์ฟเวอร์บังคับใช้ขีดจำกัดของตนเองอย่างอิสระและตอบกลับ 413 หากเกิน
licenseUrlstring | nullnullเมื่อกำหนดค่า จะเปลี่ยนข้อความลายน้ำบนหน้าจอผลลัพธ์ให้เป็นลิงก์ไปยัง URL นี้
labelsobject{}แทนที่ส่วนใดส่วนหนึ่งของสตริงค่าเริ่มต้นภาษาอังกฤษของวิดเจ็ต (ข้อความลากลง, ปุ่ม, การประกาศ aria-live, ข้อความแสดงข้อผิดพลาด)

คอลแบ็ก

คอลแบ็กเกิดขึ้นเมื่อข้อมูลที่ส่ง
onReady()วิดเจ็ตได้แสดงหน้าจอว่าง/ลากลง—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open succeedsโทเคนเซสชันของแหล่ง, จำนวนหน้า, ส่วนขยายของแหล่ง (ไม่มีจุดนำหน้า), รายการเป้าหมายที่อนุญาต
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run succeedsฟิลด์เดียวกันกับการตอบสนองการทำงาน, พร้อมกับ target ที่ร้องขอ
onDownload({ downloadName, downloadToken })ผู้ใช้คลิกลิงก์ดาวน์โหลดทำงานพร้อมกับการดาวน์โหลดตามปกติของเบราว์เซอร์ — ไม่ดักจับหรือแทนที่
onError({ phase, message })การร้องขอเปิดหรือทำงานล้มเหลวphase คือ 'open' หรือ 'run'; message คือข้อผิดพลาดจากเซิร์ฟเวอร์ที่ทำความสะอาดแล้ว (หรือข้อความจากไคลเอนต์สำหรับการตรวจสอบขนาดอัปโหลดล่วงหน้า)

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

ตัวจัดการเชิงบังคับ

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

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
const file = document.querySelector('#picker').files[0]; // ไฟล์จาก <input type="file" id="picker"> ของคุณเอง
conv.reset();         // กลับไปที่หน้าจอว่าง/ปล่อย; ไม่ทำการเรียก onReady อีกครั้ง
conv.loadFile(file);  // เริ่มกระบวนการด้วยอ็อบเจ็กต์ File; ไม่ทำอะไรหากไม่ได้อยู่ในสถานะว่าง
conv.destroy();       // ลบ listener, ทำให้ mount ว่าง; อินสแตนซ์จะไม่สามารถใช้ได้หลังจากนี้

ป้ายกำกับ

ทุกสตริงมีค่าเริ่มต้นเป็นภาษาอังกฤษ; labels แทนที่ส่วนใดส่วนหนึ่งและส่วนที่เหลือคงเป็นภาษาอังกฤษ. ส่วนที่เปลี่ยนแปลงในขณะทำงานใช้ {placeholders}, เช่น uploading: 'Uploading {name}…' และ pages: '{n} pages'.

คีย์ค่าเริ่มต้นภาษาอังกฤษ
dropPromptDrag & drop a document here
dropHintPDF, Word, Excel, PowerPoint, images and more
chooseFileChoose file
uploadingUploading {name}…
page / pages1 page / {n} pages
noTargetsNo conversion targets are available for this file.
convertTo / convertConvert to / Convert
convertingConverting to {target}…
readyToDownloadReady to download
download / convertAnotherDownload / Convert another
watermarkNoticeOutput is watermarked — get a license to remove it.
retryRetry
genericErrorSomething went wrong. Please try again.
sizeLimitThat file is larger than the {mb} MB upload limit. Please choose a smaller file.
serverErrorThe server could not process this request. Please try again.
networkErrorCould not reach the server. Please check your connection and try again.

คีย์เพิ่มเติมครอบคลุม aria-label ของโซนลากลง (dropAriaLabel), ข้อความพรีวิว alt (previewAlt, resultAlt), รูปแบบเชื่อมโยงของข้อความลายน้ำที่ใช้กับ licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), การตอบสนองที่ไม่สามารถอ่านได้ (badResponse) และการประกาศ aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).

ข้อผิดพลาด JSON จากเซิร์ฟเวอร์จะแสดงตามที่เซิร์ฟเวอร์เขียนไว้; serverError ใช้เฉพาะเมื่อการตอบสนองที่ล้มเหลวไม่มีข้อผิดพลาด JSON, เช่น 404 ของวิดเจ็ตที่ปิดการใช้งาน.

ธีม

วิดเจ็ตจะเพิ่มคลาส dcw ไปยังองค์ประกอบที่เมานท์และอ่านสี, รัศมีและฟอนต์จากคุณสมบัติ CSS แบบกำหนดเอง, ดังนั้นคุณสามารถกำหนดธีมได้โดยไม่ต้องแก้ไขภายในของมัน:

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 (หลายส่วน, หนึ่งไฟล์)อัปโหลดและเปิดเอกสารต้นทางเพื่อแสดงตัวอย่าง200 — { token, pages, sourceExt, allowedTargets }
POST ?token=<token>&convert=run&target=<ext>แปลงแหล่งที่เก็บไว้เป็น target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET ?convert=download&token=<downloadToken>สตรีมไฟล์ที่แปลงแล้ว200 — ไบต์ของไฟล์, 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 และไฟล์ต้องเปิดใหม่อีกครั้ง. ผลลัพธ์ที่แปลงแล้วอยู่ใน stash เดียวกัน — downloadToken จะได้รับช่วงเวลา 30 นาทีใหม่เมื่อการแปลงเสร็จ — ในขณะที่ resultToken เป็นโทเคนเซสชันผู้ชมทั่วไปสำหรับการแสดงตัวอย่างผลลัพธ์. เมื่อผลลัพธ์สามารถแสดงตัวอย่างได้, downloadToken และ resultToken มีค่าเดียวกัน. การปิดผลลัพธ์ผู้ชมจะไม่ลบ stash การดาวน์โหลดที่ยังมีอายุ, และการรีเซ็ตวิดเจ็ตในเบราว์เซอร์จะไม่ขยายช่วงเวลาใด ๆ.

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

เส้นทางสถานะเมื่อเนื้อหา
any404วิดเจ็ตไม่ได้เปิดใช้งาน (AddConverterWidget() ไม่เคยถูกเรียก) — ตรวจสอบก่อนที่เส้นทางทั้งสามจะถูกส่งstatus only
any405วิธี HTTP ไม่ถูกต้อง (open/run ต้องการ POST; download ต้องการ GET)status only
open400ไม่ใช่การอัปโหลด multipartExpected a multipart file upload.
open400ไม่มีไฟล์ หรือไฟล์ว่างNo file uploaded.
open400ส่วนขยายของแหล่งที่ไม่สามารถแปลงได้This file type cannot be converted.
open403ประเภทไฟล์ต้องการความสามารถที่ใบอนุญาตไม่ได้ให้ (ไฟล์ DICOM ที่ไม่มี Dicom)Converting this file type requires the Dicom capability license.
open413ไฟล์ที่อัปโหลดเกิน MaxUploadMb, ตรวจสอบกับ Content-Length และขณะอ่านการอัปโหลดFile is too large.
run400โทเคนรูปแบบไม่ถูกต้อง (ไม่ใช่ GUID)Invalid token.
run400target ที่ไม่สามารถแปลงเป็น ConversionTargetUnknown target format.
run400target ไม่ได้อยู่ใน allowedTargets ของแหล่งThat target format is not available for this file.
run404การอัปโหลดที่เก็บไว้หมดอายุหรือโทเคนไม่เคยเปิดUpload expired — please re-open the file.
open, run500การประมวลผลล้มเหลือภายในข้อความที่ทำให้เป็นมาตรฐาน — ทำให้เป็นมาตรฐานเช่นเดียวกับเส้นทางข้อผิดพลาด Doconut ทุกเส้นทาง; ไม่เปิดเผยรายละเอียดภายใน
download400โทเคนรูปแบบไม่ถูกต้อง (ไม่ใช่ GUID)status only
download404โทเคนการดาวน์โหลดที่ไม่รู้จักหรือหมดอายุstatus only

การทำรอบครบวงจรด้วย fetch:

javascript
// 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 ของคุณ.

ในสภาพการผลิต

  1. ติดตั้งปลั๊กอิน ข้างแพ็คเกจหลัก, ที่เวอร์ชันเดียวกัน: dotnet add package Doconut.NET8.Converter.
  2. เพิ่มไฟล์ใบอนุญาต. ใส่ Doconut.Viewer.Converter.lic ในโฟลเดอร์เดียวกันกับ Doconut.Viewer.lic.
  3. ตั้งค่าขีดจำกัดของเซิร์ฟเวอร์. MaxUploadMb ใน AddConverterWidget คือขีดจำกัดที่เซิร์ฟเวอร์บังคับใช้; maxUploadMb ของวิดเจ็ตเป็นเพียงการตรวจสอบบนฝั่งไคลเอนต์เท่านั้น. ให้สองค่าเท่ากัน.
  4. ให้บริการ UI จากต้นทางเดียวกัน กับ Doconut endpoints, หรือทำ reverse‑proxy ให้ (ดู สร้างส่วนหน้าของคุณเอง).
  5. ทำลายผลการแปลง. สตรีม ConvertAsync ที่คืนค่ามานั้นอยู่ในพูล; การทำลายมันจะคืนบัฟเฟอร์กลับไปยังพูล.

ฟาร์มเว็บ

วิดเจ็ตเก็บการอัปโหลดแต่ละรายการและผลลัพธ์ของมันในหน่วยความจำบนโหนดที่ให้บริการ open. หลังจากโหลดบาลานเซอร์ที่ไม่มี sticky sessions, คำขอ run, download หรือการพรีวิวที่ตามมาภายหลังอาจไปถึงโหนดอื่นและไม่พบการอัปโหลด. ลงทะเบียนที่เก็บวิดเจ็ตที่แชร์และเข้ารหัสเพียงครั้งเดียว, หลังจาก AddDoconut():

csharp
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // โฟลเดอร์ที่ทุกโหนดสามารถอ่านและเขียนได้
    store.FarmKey = farmKey;                   // อย่างน้อย 32 ไบต์, เหมือนกันบนทุกโหนด
    // store.Ttl = TimeSpan.FromMinutes(30);   // ระยะเวลาที่การอัปโหลดจะถูกเก็บ (ค่าเริ่มต้น)
});
  • เซิร์ฟเวอร์เดียวไม่ต้องทำอะไร: หากไม่ได้เรียกนี้ จะใช้ที่เก็บในหน่วยความจำ.
  • การอัปโหลดและผลลัพธ์ถูกเข้ารหัสเมื่อพักอยู่บนแชร์ (AES-256, encrypt-then-MAC), และแต่ละไฟล์ผูกกับโทเค็นของมัน, ดังนั้นโทเค็นหนึ่งจะไม่สามารถอ่านไฟล์ของโทเค็นอื่นได้.
  • บนแชร์, การอัปโหลดหรือผลลัพธ์จะถูกเก็บไว้เป็นเวลา Ttl หลังจากที่เขียนแล้ว; การอ่านไม่ขยายช่วงเวลานั้น.
  • FarmKey ต้องมีขนาดอย่างน้อย 32 ไบต์และต้องเหมือนกันบนทุกโหนด. โหลดจากที่เก็บความลับ; อย่า hard‑code. การลงทะเบียนจะโยน ArgumentException เมื่อ RootPath หายไปหรือ FarmKey มีความยาวน้อยกว่า 32 ไบต์.
  • ตั้งค่า RootPath ให้ชี้ไปที่ตำแหน่งแชร์เดียวกันที่ผู้ชมแบบกระจายใช้.

อ้างอิง API

Facade และตัวเลือกวิดเจ็ตอยู่ใน namespace Doconut; ConversionTarget อยู่ใน Doconut.Configs.Conversion. ConverterPlugin อยู่ใน Doconut.Plugins.Converter.

DocumentConverter

csharp
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);
}

ได้รับการแก้ไขจาก dependency injection; ตัวสร้างเป็น internal. sourceExtension มีจุดนำหน้า. HtmlToWordAsync เขียนไฟล์ .doc เมื่อ outputFormat เป็น ConversionTarget.Doc, และไฟล์ .docx สำหรับค่าอื่นใด.

ConversionTarget

รูปแบบผลลัพธ์ 45 แบบที่ระบุใน รูปแบบเป้าหมาย.

ConverterWidgetOptions

csharp
public sealed class ConverterWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
}

ตั้งค่าผ่าน DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), ซึ่งคืนค่า DoconutOptions เพื่อให้สามารถเรียงต่อกันได้.

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

อาการสาเหตุวิธีแก้
AddDoconut() throws The Converter plugin is registered via AddPlugin but no active license grants Converter.ไม่มีใบอนุญาต, ไฟล์ TRIAL, ใบอนุญาตที่ไม่มี Converter, หรือใบอนุญาตแบบชำระเงินที่อยู่นอกช่วงเวอร์ชันของมันติดตั้งใบอนุญาตที่ให้สิทธิ์ Converter, หรือเอา AddPlugin<ConverterPlugin>() ออก
AddDoconut() throws AddConverterWidget() was called but the Converter plugin is not registered.วิดเจ็ตถูกเปิดใช้งานโดยไม่มีปลั๊กอินของมันเพิ่ม options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>()
Resolving DocumentConverter throws No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().ConverterPlugin ยังไม่ได้ลงทะเบียนเพิ่ม AddPlugin<ConverterPlugin>() ภายใน AddDoconut()
Stream conversion says the format is unsupportedsourceExtension ไม่มีจุดนำหน้าส่ง ".xlsx", ไม่ใช่ "xlsx"
ConvertAsync throws Converting '.dcm' requires the Dicom capability license.แหล่ง DICOM, และใบอนุญาตไม่ได้ให้สิทธิ์ Dicomใช้ใบอนุญาตที่ให้สิทธิ์ Dicom
The output is watermarkedใบอนุญาตเป็นแบบชั่วคราว (Demo/NFR)ใช้ใบอนุญาตแบบชำระเงินที่ให้สิทธิ์ Converter
The widget loads but its requests answer 404AddConverterWidget() ไม่ได้ถูกเรียก, หรือ basePath ไม่ตรงกับสาขาที่ UseDoconut() ถูกเมานท์เรียก AddConverterWidget(); แก้ไข basePath
open answers 403 Converting this file type requires the Dicom capability license.การอัปโหลด DICOM, และใบอนุญาตไม่ได้ให้สิทธิ์ Dicomใช้ใบอนุญาตที่ให้สิทธิ์ Dicom
open answers 413 File is too large.การอัปโหลดเกิน MaxUploadMbยก MaxUploadMb ใน AddConverterWidget; maxUploadMb ของวิดเจ็ตเป็นเพียงการตรวจสอบบนฝั่งไคลเอนต์
run answers 400 That target format is not available for this file.เป้าหมายไม่ใช่หนึ่งใน allowedTargets ของแหล่งเสนอเฉพาะ allowedTargets จาก open
run or download answers 404 (Upload expired — please re-open the file. from run)ช่วงเวลา 30 นาทีสิ้นสุดแล้ว, หรือโหนดเว็บฟาร์มไม่มีการอัปโหลดเปิดไฟล์อีกครั้ง; ในฟาร์ม, ลงทะเบียน AddDoconutDistributedWidgets
The widget fails when the UI is on another originEndpoints ไม่มีการสนับสนุน CORSให้บริการ UI จากต้นทางเดียวกัน, หรือทำ reverse‑proxy ให้กับเส้นทาง Doconut
The theme does not applyตัวแปรถูกตั้งค่าบนพาเรนท์หรือบนองค์ประกอบภายใน mount; กฎ .dcw ของวิดเจ็ตเองตั้งค่าไว้บน mountกำหนดเป้าหมายที่ mount เอง: #doconut-convert.dcw หรือ #doconut-convert

หน้านี้เป็นประโยชน์หรือไม่?