Plugin Chuyển Đổi
Chuyển đổi tài liệu sang 45 định dạng mục tiêu
Plugin Converter biến Doconut thành một dịch vụ chuyển đổi tài liệu. Nó cung cấp động cơ phía sau giao diện công cộng DocumentConverter và — tùy chọn — một widget chèn sẵn được phục vụ bởi DocImage.axd, cho phép bạn chuyển đổi tài liệu từ C#, từ widget, hoặc từ giao diện phía trước mà bạn tự viết.
| Giao diện | Khi nào sử dụng |
|---|---|
DocumentConverter (C#) | Bạn chuyển đổi trên máy chủ, không có trình duyệt tham gia |
Widget chèn sẵn (doconutConverter.js) | Bạn muốn một màn hình tải lên, chuyển đổi và tải xuống đã sẵn sàng trong trang của mình |
Các endpoint HTTP trên DocImage.axd (?convert=open|run|download) | Bạn xây dựng UI chuyển đổi của riêng mình dựa trên hợp đồng máy chủ được tài liệu hoá |
Cài đặt gói
Install-Package Doconut.NETFramework.ConverterĐể cố định plugin vào phiên bản mà tài liệu này mô tả:
Install-Package Doconut.NETFramework.Converter -Version 26.10.0Giữ gói Converter ở cùng phiên bản với Doconut.NETFramework.
Tệp giấy phép của plugin, Doconut.Viewer.Converter.lic, nằm trong cùng thư mục với Doconut.Viewer.lic; nó được đọc cùng với giấy phép của trình xem.
Đăng ký plugin
Mỗi plugin được đăng ký theo cùng một cách: AddPlugin<TPlugin>() trong DoconutHost.Initialize, được gọi từ Application_Start.
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});Đó là tất cả những gì giao diện C# cần. Widget và các endpoint HTTP của nó là một tùy chọn riêng, AddConverterWidget() (xem Widget chèn sẵn).
Plugin cần một giấy phép cho phép khả năng Converter. Nếu không có, DoconutHost.Initialize sẽ ném lỗi từ 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.Trong System.Web điều này có nghĩa là mỗi yêu cầu trả về một 500 trống, và lý do chỉ có trong nhật ký sự kiện Windows (nguồn ASP.NET). Nó ném lỗi khi không có giấy phép, tệp legacy TRIAL, giấy phép thiếu Converter, và giấy phép trả phí được sử dụng ngoài khoảng thời gian phiên bản của nó. Các giấy phép Demo/NFR tạm thời được chấp nhận. Xem Cài đặt Giấy phép.
Cấp phép & watermark
| Trạng thái giấy phép | Khởi động | Kết quả chuyển đổi |
|---|---|---|
Giấy phép xem trả phí cho phép Converter, trong khoảng thời gian phiên bản | Bắt đầu | Sạch — watermarked: false |
| Giấy phép tạm thời hoạt động (Demo/NFR) | Bắt đầu | Chuyển đổi, với watermark đánh giá — watermarked: true |
| Giấy phép tạm thời đã hết hạn (Demo/NFR) | Bắt đầu | Chuyển đổi, với watermark đánh giá — watermarked: true |
Không có giấy phép, tệp legacy TRIAL, giấy phép thiếu Converter, hoặc giấy phép trả phí ngoài khoảng thời gian phiên bản | Application_Start ném lỗi; mỗi yêu cầu trả về một 500 trống | — |
Giao diện DocumentConverter và trình xử lý ?convert=run của widget áp dụng cùng một quy tắc. Một tích hợp có thể được xây dựng và thử nghiệm end to end trên giấy phép đánh giá trước khi mua — chỉ có các byte đầu ra thay đổi.
Một nguồn DICOM (.dcm, .ima) cũng cần khả năng Dicom. Nếu không, ConvertAsync ném một LicenseException (Converting '.dcm' requires the Dicom capability license.) và open của widget trả lời 403.
Sử dụng từ C#
Mỗi lần chuyển đổi trả về một MemoryStream có thể tìm kiếm, vị trí tại 0. DocumentConverter không trạng thái: lấy nó từ DoconutHost.Services bất cứ nơi nào bạn cần và tái sử dụng tự do.
// Lấy DocumentConverter từ DoconutHost.Services; constructor của nó là internal, vì vậy không bao giờ `new` nó.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);// sourceExtension bao gồm dấu chấm đầu tiên. password là null trừ khi tài liệu được bảo vệ.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// html: một Stream chứa HTML để chuyển lại thành tài liệu Word, chẳng hạn như kết quả của WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);Hai chi tiết dễ gây nhầm lẫn: sourceExtension trên overload stream phải bao gồm dấu chấm đầu (".xlsx", không phải "xlsx"), nếu không nó sẽ không được giải quyết. Và mặc dù tên gọi, WordToHtmlAsync trả về Task<Stream>, không phải Task<string> — tài liệu HTML (hình ảnh nhúng dưới dạng Base64) đến dưới dạng stream, giống như mọi kết quả khác.
Người gọi sở hữu MemoryStream mà một lần chuyển đổi trả về và nên giải phóng nó sau khi sao chép hoặc trả về (MVC's File(stream, …) sẽ giải phóng cho bạn). Không tự tạo hoặc giải phóng DocumentConverter — constructor của nó là nội bộ.
Trong một bộ điều khiển MVC 5
Biến hành động thành bất đồng bộ và await việc chuyển đổi:
[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");
}Trong Web Forms: không bao giờ chặn khi chuyển đổi
Một trang Web Forms chạy trên ngữ cảnh yêu cầu đơn luồng. ConvertAsync tiếp tục trên ngữ cảnh đó khi nó hoàn thành, vì vậy một trang chờ nó đồng bộ — .Result, .Wait(), .GetAwaiter().GetResult() — sẽ giữ lại luồng mà việc chuyển đổi cần để hoàn thành. Yêu cầu không bao giờ trả về. Trình duyệt vẫn quay vòng, IIS không ghi log gì, và phần còn lại của trang web vẫn hoạt động, vì vậy nó trông giống như một quá trình chuyển đổi chậm chứ không phải deadlock.
Đánh dấu trang Async="true" và chạy việc chuyển đổi như một tác vụ bất đồng bộ của trang:
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// Web Forms: chỉ thị @Page cần Async="true", và quá trình chuyển đổi chạy như một tác vụ async của trang.
// Việc chặn nó bằng cách này (.Result, .Wait(), .GetAwaiter().GetResult()) gây deadlock cho yêu cầu:
// nó không bao giờ trả về, và không có gì được ghi log.
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, không phải HttpContext.Current: sau một await, thứ sau có thể null.
Context.ApplicationInstance.CompleteRequest();
}
}));
}Nếu thiếu Async="true" trong chỉ thị @Page, RegisterAsyncTask sẽ bị bỏ qua một cách im lặng. Sau một await, sử dụng Context của trang; HttpContext.Current có thể được null ở đó.
Định dạng mục tiêu
ConversionTarget (namespace Doconut.Configs.Conversion) có 45 thành viên:
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, IcoKhông phải mọi nguồn đều chuyển đổi được sang mọi mục tiêu: mỗi họ định dạng nguồn (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project, PSD, tài liệu web, DICOM) có bộ mục tiêu cho phép riêng. Chuyển đổi một nguồn DICOM (.dcm, .ima) cũng cần một giấy phép cung cấp khả năng Dicom; các mục tiêu của nó là Pdf, Png, Jpeg, Bmp, Tiff và Gif. Đừng mã cứng enum này làm danh sách mục tiêu cho UI của bạn: ?convert=open trả về allowedTargets cho tệp đã tải lên, và đó là thứ nên điều khiển bộ chọn.
Tiện ích nhúng
Kích hoạt các endpoint
Các endpoint ?convert=open|run|download của tiện ích được phục vụ bởi DocImage.axd và mặc định là tắt. Kích hoạt chúng bên cạnh việc đăng ký plugin:
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 đọc toàn bộ tệp tải lên trước khi Doconut thấy nó: giữ maxRequestLength (KB) và
// maxAllowedContentLength (bytes) trong Web.config trên mức MaxUploadMb của widget.AddConverterWidget() không có đối số sẽ kích hoạt tiện ích với các giá trị mặc định (MaxUploadMb = 25). Nó không tự động cấp quyền chuyển đổi: nó cần AddPlugin<ConverterPlugin>(), nếu không DoconutHost.Initialize sẽ ném lỗi:
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.Hai điều cần kiểm tra khi tiện ích hoạt động không đúng:
basePath: '/DocImage.axd'. Mặc định của tiện ích,/doconut, là endpoint ASP.NET Core. Trong gói này, các endpoint là trình xử lýDocImage.axdtừWeb.config.- Script và các endpoint là độc lập. Module tài nguyên phục vụ
doconutConverter.jsbất kể tiện ích có được bật hay không. Nếu không cóAddConverterWidget(), tiện ích sẽ tải, vẽ vùng thả của mình, và trông hoàn toàn đúng — và hành động đầu tiên của nó trả lời404.
Giới hạn tải lên
ASP.NET đọc toàn bộ nội dung yêu cầu trước khi DocImage.axd chạy. Một tải lên vượt quá MaxUploadMb nhưng dưới mức giới hạn của máy chủ sẽ nhận được JSON 413 riêng của widget (File is too large.). Một tải lên vượt quá giới hạn của máy chủ sẽ bị IIS từ chối trước, kèm theo trang lỗi mà widget không thể đọc. Giữ cả hai giới hạn của máy chủ trong Web.config trên mức tối đa của widget:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Nhúng nó
<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) nhận một bộ chọn CSS hoặc một phần tử, ném lỗi nếu không tìm thấy vị trí gắn, và trả về một handle. Widget tải lên một tệp, hiển thị bản xem trước của trang 1, cho phép người dùng chọn một trong các allowedTargets, chuyển đổi, xem trước kết quả khi có thể, và cung cấp tùy chọn tải xuống.
Tùy chọn
| Tùy chọn | Kiểu | Mặc định | Ghi chú |
|---|---|---|---|
basePath | string | /doconut | URL điểm cuối. Đặt '/DocImage.axd' trên gói này |
resPath | string | /doconut-res | Được chấp nhận để đồng nhất với các widget Doconut khác; widget chuyển đổi không xây dựng URL nào từ nó |
maxUploadMb | number | 25 | Chỉ kiểm tra trước phía client; máy chủ thực thi giới hạn của riêng nó |
licenseUrl | string | null | null | Biến thông báo watermark trên màn hình kết quả thành một liên kết |
labels | object | {} | Ghi đè bất kỳ tập con nào của các chuỗi tiếng Anh của widget |
Các hàm gọi lại
| Callback | Khi nào | Dữ liệu |
|---|---|---|
onReady() | Widget đã hiển thị màn hình thả của nó | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | ?convert=open succeeds | Token nguồn, số trang, phần mở rộng nguồn (không có dấu chấm), các mục tiêu cho phép |
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target }) | ?convert=run succeeds | Phản hồi chạy cộng với target đã yêu cầu |
onDownload({ downloadName, downloadToken }) | Khi người dùng nhấn Tải xuống | Được kích hoạt cùng với việc tải xuống của trình duyệt |
onError({ phase, message }) | Một yêu cầu mở hoặc chạy thất bại | phase là 'open' hoặc 'run'; message là lỗi máy chủ đã được làm sạch |
Một callback ném lỗi sẽ được bắt và ghi lại; nó không bao giờ làm gián đoạn luồng của widget.
Handle bắt buộc
Doconut.convert() trả về thể hiện của widget:
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // một File từ của bạn <input type="file" id="picker">
conv.reset(); // quay lại màn hình thả; không kích hoạt lại onReady
conv.loadFile(file); // bắt đầu luồng với một File; không làm gì trừ khi widget đang ở màn hình thả
conv.destroy(); // gỡ bỏ các listener, làm trống mount; thể hiện này không thể sử dụng được sau nàyNhãn
Mỗi chuỗi đều có mặc định tiếng Anh; labels ghi đè bất kỳ tập con nào và phần còn lại vẫn giữ tiếng Anh. Các đoạn thay đổi tại thời gian chạy sử dụng {placeholders}, chẳng hạn như uploading: 'Uploading {name}…' và pages: '{n} pages'.
| Khóa | Mặc định tiếng Anh |
|---|---|
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. |
Các khóa bổ sung bao gồm aria-label của vùng thả (dropAriaLabel), các văn bản alt của bản xem trước (previewAlt, resultAlt), dạng liên kết của thông báo watermark được sử dụng với licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), một phản hồi không đọc được (badResponse) và các thông báo aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).
Lỗi JSON từ máy chủ được hiển thị như máy chủ đã ghi; serverError chỉ được sử dụng khi phản hồi thất bại không chứa lỗi JSON, chẳng hạn như 404 của một widget bị vô hiệu hoá.
Tùy chỉnh giao diện
Widget thêm lớp dcw vào phần tử gắn kết của nó và đọc các màu, bán kính và phông chữ từ các thuộc tính tùy chỉnh CSS, vì vậy bạn có thể tùy chỉnh giao diện mà không cần chạm vào nội bộ của nó:
#doconut-convert.dcw {
--dcw-accent: #6b46c1;
--dcw-radius: 12px;
--dcw-font: "Inter", system-ui, sans-serif;
}Mặc định: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px, và một phông chữ giao diện hệ thống cho --dcw-font.
Xây dựng giao diện người dùng của riêng bạn
Widget là một client cho hợp đồng HTTP này trên DocImage.axd. Các route trả lời 404 cho đến khi AddConverterWidget() được gọi. Lỗi mang theo một thân JSON, { "error": "..." }, ngoại trừ các trường hợp bảng ghi là "status only". Một giá trị ?convert= không biết trả lời 400.
| Đường dẫn | Mục đích | Phản hồi thành công |
|---|---|---|
POST /DocImage.axd?convert=open (multipart, one file) | Tải lên và mở tài liệu nguồn | 200 — { token, pages, sourceExt, allowedTargets } |
POST /DocImage.axd?token=<token>&convert=run&target=<ext> | Chuyển đổi nguồn đã tải lên sang target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET /DocImage.axd?convert=download&token=<downloadToken> | Phát luồng tệp đã chuyển đổi | 200 — tệp, Content-Disposition: attachment, Cache-Control: no-store |
sourceExt trong phản hồi open không có dấu chấm đầu ("docx") — ngược lại với tham số sourceExtension của ConvertAsync. allowedTargets liệt kê các tên mục tiêu viết thường ("pdf", "html", …); truyền một trong số chúng dưới dạng target, được so khớp không phân biệt chữ hoa thường. open sử dụng tệp đầu tiên trong phần multipart.
resultToken là null, và resultPages là 0, khi kết quả không thể được xem trước. downloadName là tên tệp nguồn với phần mở rộng của mục tiêu.
Các hình ảnh xem trước sử dụng route hình ảnh trình xem tiêu chuẩn, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, với token từ open hoặc resultToken từ run. Widget yêu cầu width=240.
Các nguồn đã tải lên được giữ trong 30 phút sau lần đọc cuối cùng; sau thời gian đó, run trả lời 404 và tệp phải được mở lại. downloadToken có cửa sổ 30 phút riêng khi quá trình chuyển đổi hoàn tất. resultToken là một token trình xem thông thường để xem trước kết quả; khi kết quả có thể xem trước, nó có cùng giá trị với downloadToken.
| Đường dẫn | Trạng thái | Khi | Thân |
|---|---|---|---|
| any | 404 | Widget không được bật (AddConverterWidget() chưa bao giờ được gọi) | status only |
| any | 405 | Phương thức sai (open/run yêu cầu POST, download yêu cầu GET) | status only |
open | 400 | Không phải tải lên multipart | Expected a multipart file upload. |
open | 400 | Không có tệp, hoặc tệp rỗng | No file uploaded. |
open | 400 | Kiểu không thể chuyển đổi | This file type cannot be converted. |
open | 403 | Kiểu tệp yêu cầu một khả năng mà giấy phép không cung cấp (tệp DICOM thiếu Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | Tải lên vượt quá MaxUploadMb (nhưng không vượt quá giới hạn IIS) | File is too large. |
run | 400 | Token không hợp lệ (không phải GUID) | Invalid token. |
run | 400 | Một target không thể phân tích thành ConversionTarget | Unknown target format. |
run | 400 | Mục tiêu không có trong allowedTargets | That target format is not available for this file. |
run | 404 | Tải lên đã hết hạn hoặc chưa bao giờ được mở | Upload expired — please re-open the file. |
open, run | 500 | Xử lý thất bại | Một thông điệp đã được làm sạch |
download | 400 / 404 | Token tải xuống không hợp lệ, không biết hoặc đã hết hạn | status only |
Một vòng tròn hoàn chỉnh với fetch:
// file: Tệp cần chuyển đổi, ví dụ từ một <input type="file">.
async function convertFile(file) {
const base = '/DocImage.axd';
// 1. open: tải lên tệp
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: chuyển sang PDF khi được phép, nếu không chuyển sang mục tiêu cho phép đầu tiên
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: một GET đơn giản mà trình duyệt có thể theo
window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}Các endpoint là same-origin: phiên bản này không hỗ trợ CORS. Phục vụ UI và script widget của bạn từ cùng một nguồn với Doconut, hoặc reverse-proxy handler và các đường dẫn tài nguyên dưới nguồn gốc của UI của bạn.
Trong môi trường sản xuất
- Cài đặt plugin bên cạnh gói lõi, ở cùng phiên bản:
Install-Package Doconut.NETFramework.Converter. - Thêm tệp giấy phép. Đặt
Doconut.Viewer.Converter.lictrong cùng thư mục vớiDoconut.Viewer.lic. - Đặt giới hạn tải lên.
MaxUploadMbtrongAddConverterWidgetlà giới hạn mà Doconut áp dụng; giữmaxRequestLengthvàmaxAllowedContentLengthtrongWeb.configở mức cao hơn (xem Giới hạn tải lên), vàmaxUploadMbcủa widget bằng với nó. - Không bao giờ chặn khi chuyển đổi trong Web Forms (xem Trong Web Forms).
- Giải phóng kết quả chuyển đổi. Luồng
ConvertAsynctrả về được đưa vào pool; việc giải phóng nó sẽ trả các bộ đệm về pool.
Mạng lưới máy chủ
Widget lưu mỗi lần tải lên và kết quả của nó trong bộ nhớ trên máy chủ đã phục vụ open. Đằng sau một bộ cân bằng tải mà không có phiên dính, một yêu cầu run, download hoặc xem trước sau này có thể tới máy chủ khác và không tìm thấy tệp tải lên. Đăng ký kho widget được chia sẻ và mã hóa thông qua đối số thứ hai của 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"; // một thư mục mà mọi máy chủ có thể đọc và ghi
store.FarmKey = farmKey; // ít nhất 32 byte, giống nhau trên mọi máy chủ
// store.Ttl = TimeSpan.FromMinutes(30); // thời gian một tệp tải lên được giữ (mặc định)
}));- Một máy chủ đơn lẻ không cần gì: nếu không gọi hàm này, kho lưu trong bộ nhớ sẽ được sử dụng.
- Các tệp tải lên và kết quả được mã hóa khi nghỉ trên chia sẻ (AES-256, encrypt-then-MAC), và mỗi tệp được ràng buộc với token của nó, vì vậy một token không bao giờ có thể đọc tệp của token khác.
- Trên chia sẻ, một lần tải lên hoặc một kết quả được giữ trong
Ttlsau khi được ghi; việc đọc không kéo dài thời gian này. FarmKeyphải có ít nhất 32 byte và giống nhau trên mọi máy chủ. Tải nó từ kho bí mật; không bao giờ mã cứng. Việc đăng ký sẽ ném mộtArgumentExceptionkhiRootPaththiếu hoặcFarmKeyngắn hơn 32 byte.- Đặt
RootPathtới cùng vị trí chia sẻ mà trình xem phân phối sử dụng.
Tham chiếu API
Facade và các tùy chọn widget nằm trong không gian tên Doconut; ConversionTarget nằm trong Doconut.Configs.Conversion. ConverterPlugin nằm trong 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);
}Được giải quyết từ DoconutHost.Services; hàm khởi tạo là nội bộ. sourceExtension bao gồm dấu chấm đầu. HtmlToWordAsync ghi một tệp .doc khi outputFormat là ConversionTarget.Doc, và một tệp .docx cho bất kỳ giá trị nào khác.
ConversionTarget
Có 45 định dạng đầu ra được liệt kê trong Định dạng mục tiêu.
ConverterWidgetOptions
public sealed class ConverterWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
}Đặt thông qua DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), nó trả về DoconutOptions để các lời gọi có thể được nối chuỗi.
Khắc phục sự cố
| Triệu chứng | Nguyên nhân | Cách khắc phục |
|---|---|---|
Mỗi yêu cầu trả về một 500 trống sau khi thêm plugin; nhật ký sự kiện Windows (nguồn ASP.NET) hiển thị The Converter plugin is registered via AddPlugin but no active license grants Converter. | Không có giấy phép, một tệp TRIAL, một giấy phép không có Converter, hoặc một giấy phép trả phí nằm ngoài cửa sổ phiên bản của nó | Cài đặt một giấy phép cung cấp Converter, hoặc loại bỏ AddPlugin<ConverterPlugin>() |
Mỗi yêu cầu trả về một 500 trống; nhật ký sự kiện hiển thị AddConverterWidget() was called but the Converter plugin is not registered. | Widget được bật mà không có plugin của nó | Thêm options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() |
Giải quyết DocumentConverter gây ra lỗi No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>(). | ConverterPlugin chưa được đăng ký | Thêm AddPlugin<ConverterPlugin>() trong DoconutHost.Initialize |
| Quá trình chuyển đổi Web Forms không bao giờ trả về | Trang bị chặn ở ConvertAsync | Sử dụng Async="true" và RegisterAsyncTask |
| Chuyển đổi luồng cho biết định dạng không được hỗ trợ | sourceExtension không có dấu chấm đầu | Truyền ".xlsx", không phải "xlsx" |
ConvertAsync gây ra lỗi Converting '.dcm' requires the Dicom capability license. | Một nguồn DICOM, và giấy phép không cung cấp Dicom | Sử dụng một giấy phép cung cấp Dicom |
| Kết quả có dấu watermark | Giấy phép là tạm thời (Demo/NFR) | Sử dụng một giấy phép trả phí cung cấp Converter |
Widget tải nhưng các yêu cầu của nó trả về 404 | AddConverterWidget() chưa được gọi, hoặc basePath không phải là '/DocImage.axd' | Gọi AddConverterWidget(); đặt basePath: '/DocImage.axd' |
| Một tải lên lớn hiển thị trang lỗi IIS thay vì thông báo của widget | maxRequestLength / maxAllowedContentLength dưới mức MaxUploadMb | Tăng giới hạn Web.config lên trên MaxUploadMb |
open trả lời 403 Converting this file type requires the Dicom capability license. | Một tải lên DICOM, và giấy phép không cung cấp Dicom | Sử dụng một giấy phép cung cấp Dicom |
run trả lời 400 That target format is not available for this file. | Mục tiêu không phải là một trong các allowedTargets của nguồn | Chỉ cung cấp allowedTargets từ convert=open |
run hoặc download trả lời 404 (Upload expired — please re-open the file. từ run) | Cửa sổ 30 phút đã hết, hoặc máy chủ khác trong farm không có tệp tải lên | Mở lại tệp; trong farm, đăng ký AddDoconutDistributedWidgets |
| Widget gặp lỗi khi UI ở nguồn khác | Các endpoint không hỗ trợ CORS | Phục vụ UI từ cùng nguồn, hoặc dùng reverse-proxy cho các đường dẫn Doconut |
| Giao diện không áp dụng | Các biến được đặt trên một phần tử cha hoặc trên một phần tử bên trong mount; quy tắc .dcw của widget đặt chúng trên mount | Nhắm vào chính mount: #doconut-convert.dcw hoặc #doconut-convert |
Ghi chú khung
So với các gói ASP.NET Core, gói này chỉ khác ở phần hosting; API, hợp đồng endpoint, script widget và các quy tắc cấp phép vẫn giống nhau.
- Đăng ký nằm trong
Application_Start, thông quaDoconutHost.Initialize, thay vìbuilder.Services.AddDoconut. Các dịch vụ nhưAddDoconutDistributedWidgetsđược đưa vào đối số thứ hai của nó. - Endpoints được phục vụ bởi
DocImage.axdvà script bởiDoconutResourceModule, cả hai đều đăng ký trongWeb.config, thay vìUseDoconut()vàUseDoconutResources(). Widget cầnbasePath: '/DocImage.axd'. - Lỗi khởi động xuất hiện dưới dạng một
500trống trên mỗi yêu cầu, với lý do trong nhật ký sự kiện Windows. - Tải lên được ASP.NET đọc toàn bộ trước khi Doconut thấy chúng, vì vậy các giới hạn IIS phải lớn hơn
MaxUploadMb. - Trang Web Forms không được chặn trong quá trình chuyển đổi; xem Trong Web Forms.
- Chỉ dành cho Windows, giống như phần còn lại của gói .NET Framework.
Trang này có hữu ích không?