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

แปลงเอกสารเป็น 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 การแปลงของคุณเองโดยอ้างอิงสัญญาเซิร์ฟเวอร์ที่มีเอกสารอธิบาย

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

powershell
Install-Package Doconut.NETFramework.Converter

เพื่อผูกปลั๊กอินกับเวอร์ชันที่เอกสารนี้อธิบาย:

powershell
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

csharp
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:

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.

ใน 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 ทุกที่ที่คุณต้องการและใช้ซ้ำได้อย่างอิสระ

csharp
// Resolve DocumentConverter จาก DoconutHost.Services; ตัวสร้างของมันเป็น 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"), มิฉะนั้นจะไม่สามารถ resolve ได้ และแม้ชื่อจะบ่งบอก, WordToHtmlAsync คืนค่า Task<Stream>, ไม่ใช่ Task<string> — เอกสาร HTML (ภาพฝังเป็น Base64) จะมาถึงเป็นสตรีมเช่นเดียวกับผลลัพธ์อื่น ๆ ทุกอย่าง

ผู้เรียกต้องเป็นเจ้าของ MemoryStream ที่การแปลงคืนค่าและควรทำการ dispose หลังจากคัดลอกหรือคืนค่า (MVC's File(stream, …) จะทำการ dispose ให้คุณ) อย่าสร้างหรือ dispose DocumentConverter ด้วยตนเอง — ตัวสร้างของมันเป็น internal

ในคอนโทรลเลอร์ MVC 5

ทำให้แอคชันเป็นแบบอะซิงโครนัสและ await การแปลง:

csharp
[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" และรันการแปลงเป็นงานอะซิงโครนัสของหน้า:

aspx
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>
csharp
// 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 สมาชิก:

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, 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 และ ปิดโดยค่าเริ่มต้น. เปิดใช้งานพวกมันข้างๆ การลงทะเบียนปลั๊กอิน:

csharp
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 จะโยนข้อผิดพลาด:

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.

สองสิ่งที่ต้องตรวจสอบเมื่อวิดเจ็ตทำงานผิดพลาด:

  • basePath: '/DocImage.axd'. ค่าเริ่มต้นของวิดเจ็ต, /doconut, คือ endpoint ของ ASP.NET Core. ในแพคเกจนี้, endpoint คือ handler DocImage.axd จาก Web.config.
  • สคริปต์และ endpoint แยกจากกัน. โมดูลทรัพยากรให้บริการ doconutConverter.js ไม่ว่าวิดเจ็ตจะเปิดใช้งานหรือไม่. หากไม่มี AddConverterWidget(), วิดเจ็ตจะโหลด, วาดโซนดรอปของมัน, และดูถูกต้องทั้งหมด — และการกระทำแรกของมันตอบกลับด้วย 404.

ขีดจำกัดการอัปโหลด

ASP.NET อ่านเนื้อหาคำขอทั้งหมดก่อนที่ DocImage.axd จะทำงาน การอัปโหลดที่มากกว่า MaxUploadMb แต่ต่ำกว่าขีดจำกัดของโฮสต์จะได้รับ JSON ของวิดเจ็ตเอง 413 (File is too large.) การอัปโหลดที่เกินขีดจำกัดของโฮสต์จะถูก IIS ปฏิเสธก่อน โดยมีหน้าข้อผิดพลาดที่วิดเจ็ตไม่สามารถอ่านได้ เก็บขีดจำกัดของโฮสต์ทั้งสองไว้ใน Web.config ที่สูงกว่าขีดจำกัดของวิดเจ็ต:

xml
<system.web>
  <httpRuntime maxRequestLength="30720" />           <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
  <security>
    <requestFiltering>
      <requestLimits maxAllowedContentLength="31457280" />  <!-- BYTES: 30 MB -->
    </requestFiltering>
  </security>
</system.webServer>

ฝังมัน

html
<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, ทำการแปลง, แสดงตัวอย่างผลลัพธ์เมื่อทำได้, และเสนอการดาวน์โหลด.

ตัวเลือก

ตัวเลือกประเภทค่าเริ่มต้นหมายเหตุ
basePathstring/doconutURL ของ endpoint. ตั้งค่า '/DocImage.axd' บนแพ็กเกจนี้
resPathstring/doconut-resยอมรับเพื่อความสอดคล้องกับวิดเจ็ต Doconut อื่น ๆ; วิดเจ็ตแปลงรูปแบบจะไม่สร้าง URL ใด ๆ จากมัน
maxUploadMbnumber25ตรวจสอบล่วงหน้าฝั่งไคลเอนต์เท่านั้น; เซิร์ฟเวอร์บังคับใช้ขีดจำกัดของตนเอง
licenseUrlstring | nullnullเปลี่ยนข้อความลายน้ำบนหน้าผลลัพธ์ให้เป็นลิงก์
labelsobject{}แทนที่ส่วนย่อยใด ๆ ของสตริงภาษาอังกฤษของวิดเจ็ต

คอลแบ็ก

คอลแบ็กเกิดเมื่อข้อมูลที่ส่ง
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: '/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'.

คีย์ค่าเริ่มต้นภาษาอังกฤษ
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 นี้บน 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>แปลงต้นทางที่อัปโหลดเป็น target200 — { 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)เฉพาะสถานะ
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 (แต่ไม่เกินขีดจำกัดของ IIS)File is too large.
run400โทเค็นรูปแบบไม่ถูกต้อง (ไม่ใช่ GUID)Invalid token.
run400target ที่ไม่สามารถแปลงเป็น ConversionTargetUnknown target format.
run400เป้าหมายที่ไม่อยู่ใน allowedTargetsThat target format is not available for this file.
run404การอัปโหลดหมดอายุหรือไม่เคยเปิดUpload expired — please re-open the file.
open, run500การประมวลผลล้มเหลวข้อความที่ทำความสะอาดแล้ว
download400 / 404โทเค็นดาวน์โหลดที่รูปแบบไม่ถูกต้อง, ไม่รู้จัก, หรือหมดอายุเฉพาะสถานะ

การเดินทางรอบสมบูรณ์ด้วย fetch:

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

ในขั้นตอนการผลิต

  1. ติดตั้งปลั๊กอิน ถัดจากแพคเกจหลัก, ในเวอร์ชันเดียวกัน: Install-Package Doconut.NETFramework.Converter.
  2. เพิ่มไฟล์ใบอนุญาต. ใส่ Doconut.Viewer.Converter.lic ในโฟลเดอร์เดียวกับ Doconut.Viewer.lic.
  3. ตั้งค่าขีดจำกัดการอัปโหลด. MaxUploadMb ใน AddConverterWidget คือขีดจำกัดที่ Doconut บังคับใช้; รักษา maxRequestLength และ maxAllowedContentLength ใน Web.config ให้เหนือกว่ามัน (ดู ขีดจำกัดการอัปโหลด), และให้ maxUploadMb ของวิดเจ็ตเท่ากับมัน.
  4. ห้ามบล็อกการแปลง ใน Web Forms (ดู ใน Web Forms).
  5. ทำลายผลการแปลง. สตรีม ConvertAsync ที่คืนค่ามานั้นถูกจัดสรรในพูล; การทำลายมันจะคืนบัฟเฟอร์กลับไปยังพูล.

ฟาร์มเว็บ

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

csharp
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

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

ได้รับการแก้ไขจาก DoconutHost.Services; ตัวสร้างเป็น 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 เพื่อให้สามารถเรียกต่อกันได้.

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

อาการสาเหตุวิธีแก้
ทุกคำขอตอบด้วย 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
วิดเจ็ตโหลดได้แต่คำขอของมันคืนค่า 404AddConverterWidget() ไม่ได้ถูกเรียก, หรือ 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

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