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

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

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

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

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

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

bash
dotnet add package Doconut.NET6.Converter

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

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

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

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

แพลตฟอร์ม. ปลั๊กอินทำงานได้ทุกที่ที่ Doconut.NET6 ทำงาน: 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.NET6.Converter, ติดตั้งพร้อมกับแพ็กเกจ viewer พื้นฐาน

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

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

ปลั๊กอินต้องการใบอนุญาตที่ให้ความสามารถ 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() โยน—

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

แหล่ง 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 document, เช่นผลลัพธ์ของ 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 สำเร็จโทเคนเซสชันต้นทาง, จำนวนหน้า, ส่วนขยายของแหล่ง (ไม่มีจุดนำหน้า), รายการเป้าหมายที่อนุญาต
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run สำเร็จฟิลด์เดียวกันกับการตอบสนองการรัน, พร้อมกับ 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]; // File จากของคุณเอง <input type="file" id="picker">
conv.reset();         // กลับไปที่หน้าจอ idle/drop; ไม่ทำการเรียก onReady อีกครั้ง
conv.loadFile(file);  // เริ่มกระบวนการด้วยอ็อบเจ็กต์ File; ไม่ทำอะไรหากไม่ได้อยู่ในสถานะ idle
conv.destroy();       // ลบ listeners, ทำให้ mount ว่าง; instance จะไม่สามารถใช้ได้หลังจากนี้

ป้ายกำกับ

ทุกสตริงมีค่าเริ่มต้นภาษาอังกฤษ; 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.

RoutePurposeSuccess response
POST ?convert=open (multipart, one file)Upload and open a source document for preview200 — { token, pages, sourceExt, allowedTargets }
POST ?token=<token>&convert=run&target=<ext>Convert the stashed source to target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET ?convert=download&token=<downloadToken>Stream the converted file200 — 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 มีค่าเดียวกัน. การปิดผลลัพธ์ผู้ชมจะไม่ลบที่เก็บการดาวน์โหลดที่ยังมีอายุอยู่, และการรีเซ็ตวิดเจ็ตเบราว์เซอร์จะไม่ขยายช่วงเวลาใดๆ.

โหมดความล้มเหลว, จัดกลุ่มตามเส้นทาง:

RouteStatusWhenBody
any404วิดเจ็ตไม่ได้เปิดใช้งาน (AddConverterWidget() ไม่เคยถูกเรียก) — ตรวจสอบก่อนที่เส้นทางใดๆ ในสามเส้นทางจะทำงานstatus only
any405HTTP verb ไม่ถูกต้อง (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.NET6.Converter.
  2. เพิ่มไฟล์ใบอนุญาต. ใส่ Doconut.Viewer.Converter.lic ในโฟลเดอร์เดียวกันกับ Doconut.Viewer.lic.
  3. ตั้งค่าขีดจำกัดของเซิร์ฟเวอร์. MaxUploadMb ใน AddConverterWidget เป็นขีดจำกัดที่เซิร์ฟเวอร์บังคับใช้; maxUploadMb ของวิดเจ็ตเป็นเพียงการตรวจสอบด้านไคลเอนต์เท่านั้น. ให้สองค่านี้เท่ากัน.
  4. ให้บริการ UI จากต้นกำเนิดเดียวกัน กับ endpoint ของ Doconut, หรือทำ 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() โยน 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
วิดเจ็ตโหลดแล้วแต่คำขอตอบกลับ 404AddConverterWidget() ไม่ได้ถูกเรียก, หรือ 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 อยู่บนต้นกำเนิดอื่นendpoint ไม่มีการสนับสนุน CORSให้บริการ UI จากต้นกำเนิดเดียวกัน, หรือทำ reverse-proxy ให้กับเส้นทาง Doconut
ธีมไม่ทำงานตัวแปรถูกตั้งค่าใน ancestor หรือใน element ภายใน mount; กฎ .dcw ของวิดเจ็ตเองตั้งค่าไว้บน mountเป้าหมายที่ mount เอง: #doconut-convert.dcw หรือ #doconut-convert

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