ปลั๊กอินแปลงไฟล์
แปลงเอกสารเป็น 45 รูปแบบเป้าหมาย
ปลั๊กอิน Converter ทำให้ Doconut กลายเป็นบริการแปลงเอกสาร มันเป็นส่วนของเอนจินที่อยู่เบื้องหลัง facade สาธารณะ DocumentConverter และ — หากเลือกใช้ — วิดเจ็ตแบบ drop‑in ที่ให้บริการโดย DocImage.axd ดังนั้นคุณจึงสามารถแปลงเอกสารจาก C#, จากวิดเจ็ต, หรือจากส่วนหน้า (frontend) ที่คุณเขียนเองได้
| พื้นผิว | ใช้เมื่อ |
|---|---|
DocumentConverter (C#) | คุณทำการแปลงบนเซิร์ฟเวอร์โดยไม่มีเบราว์เซอร์เข้ามาเกี่ยวข้อง |
Drop-in widget (doconutConverter.js) | คุณต้องการหน้าจออัปโหลด, แปลงและดาวน์โหลดที่เตรียมไว้แล้วในหน้าของคุณ |
HTTP endpoints on DocImage.axd (?convert=open|run|download) | คุณสร้าง UI การแปลงของคุณเองโดยอ้างอิงสัญญาเซิร์ฟเวอร์ที่มีเอกสารอธิบาย |
ติดตั้งแพ็กเกจ
Install-Package Doconut.NETFramework.Converterเพื่อผูกปลั๊กอินกับเวอร์ชันที่เอกสารนี้อธิบาย:
Install-Package Doconut.NETFramework.Converter -Version 26.10.0รักษาแพ็กเกจ Converter ให้เป็นเวอร์ชันเดียวกับ Doconut.NETFramework
ไฟล์ใบอนุญาตของปลั๊กอิน, Doconut.Viewer.Converter.lic, จะอยู่ในโฟลเดอร์เดียวกับ Doconut.Viewer.lic; จะถูกอ่านพร้อมกับใบอนุญาตของ viewer
ลงทะเบียนปลั๊กอิน
ปลั๊กอินทุกตัวจะลงทะเบียนด้วยวิธีเดียวกัน: AddPlugin<TPlugin>() ใน DoconutHost.Initialize, เรียกจาก Application_Start
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});นั่นคือทั้งหมดที่ facade ของ C# ต้องการ วิดเจ็ตและ HTTP endpoint ของมันเป็นส่วน opt‑in แยกต่างหาก, AddConverterWidget() (ดู วิดเจ็ตแบบ drop‑in).
ปลั๊กอินต้องการใบอนุญาตที่ให้ความสามารถ Converter หากไม่มีใบอนุญาต, DoconutHost.Initialize จะโยนข้อผิดพลาดจาก Application_Start:
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.ใน System.Web นั่นหมายความว่าทุกคำขอจะตอบกลับด้วย 500 ว่างเปล่า, และสาเหตุจะอยู่ใน Windows event log (source ASP.NET) เท่านั้น มันจะโยนข้อผิดพลาดเมื่อไม่มีใบอนุญาต, มีไฟล์ legacy TRIAL, ใบอนุญาตที่ไม่มี Converter, หรือใบอนุญาตที่ชำระเงินถูกใช้นอกช่วงเวอร์ชันของมัน ใบอนุญาต Demo/NFR ชั่วคราวจะได้รับการยอมรับ ดู การตั้งค่าใบอนุญาต.
การให้สิทธิ์และลายน้ำ
| สถานะใบอนุญาต | การเริ่มต้น | ผลลัพธ์การแปลง |
|---|---|---|
ใบอนุญาต viewer แบบชำระเงินที่ให้ความสามารถ Converter, ภายในช่วงเวอร์ชันของมัน | เริ่มต้น | สะอาด — watermarked: false |
| ใบอนุญาตชั่วคราว (Demo/NFR) ที่ใช้งานอยู่ | เริ่มต้น | แปลงได้, พร้อมลายน้ำการประเมินผล — watermarked: true |
| ใบอนุญาตชั่วคราว (Demo/NFR) ที่หมดอายุ | เริ่มต้น | แปลงได้, พร้อมลายน้ำการประเมินผล — watermarked: true |
ไม่มีใบอนุญาต, ไฟล์ legacy TRIAL, ใบอนุญาตที่ไม่มี Converter, หรือใบอนุญาตที่ชำระเงินนอกช่วงเวอร์ชันของมัน | Application_Start จะโยนข้อผิดพลาด; ทุกคำขอตอบกลับด้วย 500 ว่างเปล่า | — |
facade DocumentConverter และตัวจัดการ ?convert=run ของวิดเจ็ตใช้กฎเดียวกัน การบูรณาการสามารถสร้างและทดสอบแบบ end‑to‑end ด้วยใบอนุญาตการประเมินผลก่อนการซื้อ — เพียงแค่ไบต์ผลลัพธ์ที่เปลี่ยนไป
แหล่ง DICOM (.dcm, .ima) ก็ต้องการความสามารถ Dicom ด้วย หากไม่มี, ConvertAsync จะโยน LicenseException (Converting '.dcm' requires the Dicom capability license.) และตัวจัดการของวิดเจ็ต open จะตอบกลับด้วย 403
ใช้จาก C#
การแปลงแต่ละครั้งจะคืนค่า MemoryStream ที่สามารถเลื่อนตำแหน่งได้และอยู่ที่ตำแหน่ง 0. DocumentConverter ไม่มีสถานะ: ให้ดึงจาก DoconutHost.Services ทุกที่ที่คุณต้องการและใช้ซ้ำได้อย่างอิสระ
// Resolve DocumentConverter จาก DoconutHost.Services; ตัวสร้างของมันเป็น 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"), มิฉะนั้นจะไม่สามารถ resolve ได้ และแม้ชื่อจะบ่งบอก, WordToHtmlAsync คืนค่า Task<Stream>, ไม่ใช่ Task<string> — เอกสาร HTML (ภาพฝังเป็น Base64) จะมาถึงเป็นสตรีมเช่นเดียวกับผลลัพธ์อื่น ๆ ทุกอย่าง
ผู้เรียกต้องเป็นเจ้าของ MemoryStream ที่การแปลงคืนค่าและควรทำการ dispose หลังจากคัดลอกหรือคืนค่า (MVC's File(stream, …) จะทำการ dispose ให้คุณ) อย่าสร้างหรือ dispose DocumentConverter ด้วยตนเอง — ตัวสร้างของมันเป็น internal
ในคอนโทรลเลอร์ MVC 5
ทำให้แอคชันเป็นแบบอะซิงโครนัสและ await การแปลง:
[HttpPost]
public async Task<ActionResult> ToPdf(HttpPostedFileBase file)
{
var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
Stream pdf = await converter.ConvertAsync(
file.InputStream, Path.GetExtension(file.FileName), ConversionTarget.Pdf,
password: null, ct: Response.ClientDisconnectedToken);
return File(pdf, "application/pdf", Path.GetFileNameWithoutExtension(file.FileName) + ".pdf");
}ใน Web Forms: อย่าบล็อกการแปลง
หน้า Web Forms ทำงานบนบริบทการร้องขอแบบ single-threaded. ConvertAsync จะทำงานต่อบนบริบทนั้นเมื่อเสร็จสิ้น, ดังนั้นหน้าที่รออย่าง synchronous — .Result, .Wait(), .GetAwaiter().GetResult() — จะครอบครองเธรดที่การแปลงต้องการให้เสร็จ. คำร้องขอจะไม่คืนค่าเลย. เบราว์เซอร์จะหมุนต่อไป, IIS ไม่บันทึกอะไร, และส่วนที่เหลือของเว็บไซต์ยังทำงานต่อ, ทำให้ดูเหมือนการแปลงช้าแทนที่จะเป็น deadlock.
ทำเครื่องหมายหน้าด้วย Async="true" และรันการแปลงเป็นงานอะซิงโครนัสของหน้า:
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// Web Forms: คำสั่ง @Page ต้องการ Async="true", และการแปลงทำงานเป็นงานอะซิงค์ของหน้า.
// การบล็อกบนมันแทน (.Result, .Wait(), .GetAwaiter().GetResult()) ทำให้คำขอเกิด deadlock:
// มันจะไม่คืนค่าและไม่มีอะไรถูกบันทึก.
protected void Page_Load(object sender, EventArgs e)
{
if (!IsPostBack) return;
RegisterAsyncTask(new PageAsyncTask(async ct =>
{
var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
using (var pdf = await converter.ConvertAsync(
Server.MapPath("~/App_Data/contract.docx"), ConversionTarget.Pdf, ct: ct))
using (var ms = new MemoryStream())
{
if (pdf.CanSeek) pdf.Position = 0;
await pdf.CopyToAsync(ms);
Response.ContentType = "application/pdf";
Response.AddHeader("Content-Disposition", "attachment; filename=contract.pdf");
Response.BinaryWrite(ms.ToArray());
// Context, ไม่ใช่ HttpContext.Current: หลังจาก await ตัวหลังอาจเป็น null.
Context.ApplicationInstance.CompleteRequest();
}
}));
}หากไม่มี Async="true" ใน directive @Page, RegisterAsyncTask จะถูกละเลยโดยไม่มีข้อความแจ้ง. หลังจาก await, ใช้ Context ของหน้า; HttpContext.Current สามารถเป็น null ที่นั่น.
รูปแบบเป้าหมาย
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, PSD, เอกสารเว็บ, DICOM) มีชุดเป้าหมายที่อนุญาตของตนเอง. การแปลงแหล่งที่มาชนิด DICOM (.dcm, .ima) ยังต้องการไลเซนส์ที่ให้ความสามารถ Dicom; เป้าหมายของมันคือ Pdf, Png, Jpeg, Bmp, Tiff และ Gif. อย่า hardcode enum นี้เป็นรายการเป้าหมายของ UI ของคุณ: ?convert=open คืนค่า allowedTargets สำหรับไฟล์ที่อัปโหลด, และนั่นคือสิ่งที่ควรใช้เป็นตัวเลือก.
วิดเจ็ตแบบ Drop-in
เปิดใช้งาน endpoint
endpoint ?convert=open|run|download ของวิดเจ็ตให้บริการโดย DocImage.axd และ ปิดโดยค่าเริ่มต้น. เปิดใช้งานพวกมันข้างๆ การลงทะเบียนปลั๊กอิน:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget(widget =>
{
widget.MaxUploadMb = 25;
});
});
// System.Web อ่านข้อมูลอัปโหลดทั้งหมดก่อนที่ Doconut จะเห็น: ควรตั้งค่า maxRequestLength (KB) และ
// maxAllowedContentLength (bytes) ใน Web.config ให้สูงกว่าค่า MaxUploadMb ของวิดเจ็ต.AddConverterWidget() โดยไม่มีอาร์กิวเมนต์จะเปิดใช้งานวิดเจ็ตด้วยค่าเริ่มต้น (MaxUploadMb = 25). มันไม่ได้ให้สิทธิ์การแปลงโดยตัวเอง: ต้องการ AddPlugin<ConverterPlugin>(), หรือ DoconutHost.Initialize จะโยนข้อผิดพลาด:
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.สองสิ่งที่ต้องตรวจสอบเมื่อวิดเจ็ตทำงานผิดพลาด:
basePath: '/DocImage.axd'. ค่าเริ่มต้นของวิดเจ็ต,/doconut, คือ endpoint ของ ASP.NET Core. ในแพคเกจนี้, endpoint คือ handlerDocImage.axdจากWeb.config.- สคริปต์และ endpoint แยกจากกัน. โมดูลทรัพยากรให้บริการ
doconutConverter.jsไม่ว่าวิดเจ็ตจะเปิดใช้งานหรือไม่. หากไม่มีAddConverterWidget(), วิดเจ็ตจะโหลด, วาดโซนดรอปของมัน, และดูถูกต้องทั้งหมด — และการกระทำแรกของมันตอบกลับด้วย404.
ขีดจำกัดการอัปโหลด
ASP.NET อ่านเนื้อหาคำขอทั้งหมดก่อนที่ DocImage.axd จะทำงาน การอัปโหลดที่มากกว่า MaxUploadMb แต่ต่ำกว่าขีดจำกัดของโฮสต์จะได้รับ JSON ของวิดเจ็ตเอง 413 (File is too large.) การอัปโหลดที่เกินขีดจำกัดของโฮสต์จะถูก IIS ปฏิเสธก่อน โดยมีหน้าข้อผิดพลาดที่วิดเจ็ตไม่สามารถอ่านได้ เก็บขีดจำกัดของโฮสต์ทั้งสองไว้ใน Web.config ที่สูงกว่าขีดจำกัดของวิดเจ็ต:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>ฝังมัน
<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd', maxUploadMb: 25 });
</script>Doconut.convert(selectorOrElement, options) รับตัวเลือก CSS หรืออิลิเมนต์, จะโยนข้อผิดพลาดหากไม่พบตำแหน่งเมานท์, และคืนค่า handle. วิดเจ็ตอัปโหลดไฟล์, แสดงตัวอย่างของหน้า 1, ให้ผู้ใช้เลือกหนึ่งใน allowedTargets, ทำการแปลง, แสดงตัวอย่างผลลัพธ์เมื่อทำได้, และเสนอการดาวน์โหลด.
ตัวเลือก
| ตัวเลือก | ประเภท | ค่าเริ่มต้น | หมายเหตุ |
|---|---|---|---|
basePath | string | /doconut | URL ของ endpoint. ตั้งค่า '/DocImage.axd' บนแพ็กเกจนี้ |
resPath | string | /doconut-res | ยอมรับเพื่อความสอดคล้องกับวิดเจ็ต Doconut อื่น ๆ; วิดเจ็ตแปลงรูปแบบจะไม่สร้าง URL ใด ๆ จากมัน |
maxUploadMb | number | 25 | ตรวจสอบล่วงหน้าฝั่งไคลเอนต์เท่านั้น; เซิร์ฟเวอร์บังคับใช้ขีดจำกัดของตนเอง |
licenseUrl | string | null | null | เปลี่ยนข้อความลายน้ำบนหน้าผลลัพธ์ให้เป็นลิงก์ |
labels | object | {} | แทนที่ส่วนย่อยใด ๆ ของสตริงภาษาอังกฤษของวิดเจ็ต |
คอลแบ็ก
| คอลแบ็ก | เกิดเมื่อ | ข้อมูลที่ส่ง |
|---|---|---|
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: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // ไฟล์จากของคุณเอง <input type="file" id="picker">
conv.reset(); // กลับไปที่หน้าจอวาง; ไม่ทำการเรียก onReady ใหม่
conv.loadFile(file); // เริ่มกระบวนการด้วย File; ไม่ทำอะไรหากวิดเจ็ตไม่ได้อยู่ที่หน้าจอวาง
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), ข้อความพรีวิว 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 นี้บน DocImage.axd. เส้นทางตอบกลับ 404 จนกว่า AddConverterWidget() จะถูกเรียก. ข้อผิดพลาดมีเนื้อหา JSON, { "error": "..." }, ยกเว้นในกรณีที่ตารางระบุว่า "status only". ค่าที่ไม่รู้จักของ ?convert= จะตอบกลับ 400.
| เส้นทาง | วัตถุประสงค์ | การตอบสนองสำเร็จ |
|---|---|---|
POST /DocImage.axd?convert=open (multipart, one file) | อัปโหลดและเปิดเอกสารต้นทาง | 200 — { token, pages, sourceExt, allowedTargets } |
POST /DocImage.axd?token=<token>&convert=run&target=<ext> | แปลงต้นทางที่อัปโหลดเป็น target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET /DocImage.axd?convert=download&token=<downloadToken> | สตรีมไฟล์ที่แปลงแล้ว | 200 — ไฟล์, Content-Disposition: attachment, Cache-Control: no-store |
sourceExt ในการตอบกลับ open ไม่มีจุดนำหน้า ("docx") — ซึ่งตรงกันข้ามกับพารามิเตอร์ sourceExtension ของ ConvertAsync. allowedTargets แสดงรายการชื่อเป้าหมายเป็นตัวพิมพ์เล็ก ("pdf", "html", …); ส่งหนึ่งในนั้นเป็น target, ซึ่งจะจับคู่โดยไม่คำนึงถึงตัวพิมพ์ใหญ่/เล็ก. open ใช้ไฟล์แรกในส่วน multipart ของ body.
resultToken คือ null, และ resultPages คือ 0, เมื่อผลลัพธ์ไม่สามารถแสดงตัวอย่างได้. downloadName คือชื่อไฟล์ต้นทางพร้อมส่วนขยายของเป้าหมาย.
รูปภาพตัวอย่างใช้เส้นทางภาพผู้ชมมาตรฐาน, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, พร้อมกับ token จาก open หรือ resultToken จาก run. วิดเจ็ตขอ width=240.
แหล่งที่อัปโหลดจะถูกเก็บไว้เป็นเวลา 30 นาทีหลังจากที่อ่านครั้งสุดท้าย; หลังจากนั้น, run จะตอบกลับ 404 และไฟล์ต้องเปิดใหม่อีกครั้ง. downloadToken จะได้รับหน้าต่าง 30 นาทีของมันเองเมื่อการแปลงเสร็จสิ้น. resultToken คือโทเค็นผู้ชมทั่วไปสำหรับการแสดงตัวอย่างผลลัพธ์; เมื่อผลลัพธ์สามารถแสดงตัวอย่างได้, มันจะมีค่าเดียวกับ downloadToken.
| เส้นทาง | สถานะ | เมื่อ | เนื้อหา |
|---|---|---|---|
| ใดๆ | 404 | วิดเจ็ตไม่ได้เปิดใช้งาน (AddConverterWidget() ไม่เคยถูกเรียก) | เฉพาะสถานะ |
| ใดๆ | 405 | คำกริยาผิด (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 (แต่ไม่เกินขีดจำกัดของ IIS) | File is too large. |
run | 400 | โทเค็นรูปแบบไม่ถูกต้อง (ไม่ใช่ GUID) | Invalid token. |
run | 400 | target ที่ไม่สามารถแปลงเป็น ConversionTarget | Unknown target format. |
run | 400 | เป้าหมายที่ไม่อยู่ใน allowedTargets | That target format is not available for this file. |
run | 404 | การอัปโหลดหมดอายุหรือไม่เคยเปิด | Upload expired — please re-open the file. |
open, run | 500 | การประมวลผลล้มเหลว | ข้อความที่ทำความสะอาดแล้ว |
download | 400 / 404 | โทเค็นดาวน์โหลดที่รูปแบบไม่ถูกต้อง, ไม่รู้จัก, หรือหมดอายุ | เฉพาะสถานะ |
การเดินทางรอบสมบูรณ์ด้วย fetch:
// file: ไฟล์ที่ต้องแปลง, ตัวอย่างเช่นจาก <input type="file">.
async function convertFile(file) {
const base = '/DocImage.axd';
// 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 ตัวจัดการและเส้นทางทรัพยากรภายใต้ต้นทางของ UI ของคุณ.
ในขั้นตอนการผลิต
- ติดตั้งปลั๊กอิน ถัดจากแพคเกจหลัก, ในเวอร์ชันเดียวกัน:
Install-Package Doconut.NETFramework.Converter. - เพิ่มไฟล์ใบอนุญาต. ใส่
Doconut.Viewer.Converter.licในโฟลเดอร์เดียวกับDoconut.Viewer.lic. - ตั้งค่าขีดจำกัดการอัปโหลด.
MaxUploadMbในAddConverterWidgetคือขีดจำกัดที่ Doconut บังคับใช้; รักษาmaxRequestLengthและmaxAllowedContentLengthในWeb.configให้เหนือกว่ามัน (ดู ขีดจำกัดการอัปโหลด), และให้maxUploadMbของวิดเจ็ตเท่ากับมัน. - ห้ามบล็อกการแปลง ใน Web Forms (ดู ใน Web Forms).
- ทำลายผลการแปลง. สตรีม
ConvertAsyncที่คืนค่ามานั้นถูกจัดสรรในพูล; การทำลายมันจะคืนบัฟเฟอร์กลับไปยังพูล.
ฟาร์มเว็บ
วิดเจ็ตเก็บการอัปโหลดแต่ละรายการและผลลัพธ์ของมันในหน่วยความจำบนเซิร์ฟเวอร์ที่ให้บริการ open. หลังจากโหลดบาลานเซอร์ที่ไม่มี sticky sessions, คำขอ run, download หรือการพรีวิวในภายหลังอาจไปยังเซิร์ฟเวอร์อื่นและไม่พบการอัปโหลด. ลงทะเบียนที่เก็บวิดเจ็ตที่แชร์และเข้ารหัสผ่านอาร์กิวเมนต์ที่สองของ DoconutHost.Initialize:
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);
Doconut.DoconutHost.Initialize(
options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget();
},
services => 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
ฟาซาดและตัวเลือกวิดเจ็ตอยู่ในเนมสเปซ 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);
}ได้รับการแก้ไขจาก DoconutHost.Services; ตัวสร้างเป็น 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 เพื่อให้สามารถเรียกต่อกันได้.
การแก้ไขปัญหา
| อาการ | สาเหตุ | วิธีแก้ |
|---|---|---|
ทุกคำขอตอบด้วย 500 ว่างหลังจากเพิ่มปลั๊กอิน; บันทึกเหตุการณ์ของ Windows (source ASP.NET) แสดง The Converter plugin is registered via AddPlugin but no active license grants Converter. | ไม่มีใบอนุญาต, ไฟล์ TRIAL, ใบอนุญาตที่ไม่มี Converter, หรือใบอนุญาตแบบชำระเงินที่อยู่นอกช่วงเวอร์ชัน | ติดตั้งใบอนุญาตที่ให้สิทธิ์ Converter, หรือเอา AddPlugin<ConverterPlugin>() ออก |
ทุกคำขอตอบด้วย 500 ว่าง; บันทึกเหตุการณ์แสดง 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>() ใน DoconutHost.Initialize |
| การแปลง Web Forms ไม่เคยคืนค่า | หน้าเว็บบล็อกที่ ConvertAsync | ใช้ Async="true" และ RegisterAsyncTask |
| การแปลงสตรีมบอกว่ารูปแบบไม่รองรับ | sourceExtension ไม่มีจุดนำหน้า | ส่ง ".xlsx" ไม่ใช่ "xlsx" |
ConvertAsync ทำให้เกิดข้อผิดพลาด Converting '.dcm' requires the Dicom capability license. | แหล่ง DICOM, และใบอนุญาตไม่ได้ให้สิทธิ์ Dicom | ใช้ใบอนุญาตที่ให้สิทธิ์ Dicom |
| ผลลัพธ์มีลายน้ำ | ใบอนุญาตเป็นแบบชั่วคราว (Demo/NFR) | ใช้ใบอนุญาตแบบชำระเงินที่ให้สิทธิ์ Converter |
วิดเจ็ตโหลดได้แต่คำขอของมันคืนค่า 404 | AddConverterWidget() ไม่ได้ถูกเรียก, หรือ basePath ไม่ใช่ '/DocImage.axd' | เรียก AddConverterWidget(); ตั้งค่า basePath: '/DocImage.axd' |
| การอัปโหลดขนาดใหญ่แสดงหน้าข้อผิดพลาดของ IIS แทนข้อความของวิดเจ็ต | maxRequestLength / maxAllowedContentLength ต่ำกว่า MaxUploadMb | เพิ่มขีดจำกัด Web.config ให้สูงกว่า MaxUploadMb |
open ตอบ 403 Converting this file type requires the Dicom capability license. | การอัปโหลด DICOM, และใบอนุญาตไม่ได้ให้สิทธิ์ Dicom | ใช้ใบอนุญาตที่ให้สิทธิ์ Dicom |
run ตอบ 400 That target format is not available for this file. | เป้าหมายไม่ใช่หนึ่งใน allowedTargets ของแหล่ง | เสนอเฉพาะ allowedTargets จาก convert=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 |
หมายเหตุของเฟรมเวิร์ก
เมื่อเทียบกับแพคเกจ ASP.NET Core, แพคเกจนี้แตกต่างกันเฉพาะด้านการโฮสต์; API, สัญญา endpoint, สคริปต์วิดเจ็ตและกฎการให้ใบอนุญาตยังคงเหมือนเดิม.
- การลงทะเบียน อยู่ใน
Application_Start, ผ่านDoconutHost.Initialize, แทนที่builder.Services.AddDoconut. บริการเช่นAddDoconutDistributedWidgetsจะอยู่ในอาร์กิวเมนต์ที่สองของมัน - จุดเชื่อมต่อ ให้บริการโดย
DocImage.axdและสคริปต์โดยDoconutResourceModule, ทั้งสองลงทะเบียนในWeb.config, แทนที่UseDoconut()และUseDoconutResources(). วิดเจ็ตต้องการbasePath: '/DocImage.axd' - ความล้มเหลวในการเริ่มต้น ปรากฏเป็น
500ว่างในทุกคำขอ, โดยเหตุผลอยู่ในบันทึกเหตุการณ์ของ Windows - การอัปโหลด ถูกอ่านเต็มโดย ASP.NET ก่อนที่ Doconut จะเห็น, ดังนั้นขีดจำกัดของ IIS ต้องสูงกว่า
MaxUploadMb - Web Forms หน้าไม่ควรบล็อกบนการแปลง; ดูที่ ใน Web Forms
- เฉพาะ Windows เช่นเดียวกับส่วนที่เหลือของแพคเกจ .NET Framework
หน้านี้เป็นประโยชน์หรือไม่?