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ệnKhi 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

powershell
Install-Package Doconut.NETFramework.Converter

Để cố định plugin vào phiên bản mà tài liệu này mô tả:

powershell
Install-Package Doconut.NETFramework.Converter -Version 26.10.0

Giữ 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.

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

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.

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épKhởi độngKế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ảnBắt đầuSạch — watermarked: false
Giấy phép tạm thời hoạt động (Demo/NFR)Bắt đầuChuyể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 đầuChuyể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ảnApplication_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.

csharp
// 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);
csharp
// 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);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// 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:

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

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:

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

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

Khô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:

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 đọ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:

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.

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.axd từ Web.config.
  • Script và các endpoint là độc lập. Module tài nguyên phục vụ doconutConverter.js bấ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ời 404.

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:

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>

Nhúng nó

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) 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ọnKiểuMặc địnhGhi chú
basePathstring/doconutURL điểm cuối. Đặt '/DocImage.axd' trên gói này
resPathstring/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ó
maxUploadMbnumber25Chỉ kiểm tra trước phía client; máy chủ thực thi giới hạn của riêng nó
licenseUrlstring | nullnullBiến thông báo watermark trên màn hình kết quả thành một liên kết
labelsobject{}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

CallbackKhi nàoDữ liệu
onReady()Widget đã hiển thị màn hình thả của nó—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open succeedsToken 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 succeedsPhả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ạiphase 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:

javascript
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ày

Nhã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óaMặc định tiếng Anh
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.

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

css
#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ẫnMục đíchPhả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ồn200 — { token, pages, sourceExt, allowedTargets }
POST /DocImage.axd?token=<token>&convert=run&target=<ext>Chuyển đổi nguồn đã tải lên sang target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET /DocImage.axd?convert=download&token=<downloadToken>Phát luồng tệp đã chuyển đổi200 — 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ẫnTrạng tháiKhiThân
any404Widget không được bật (AddConverterWidget() chưa bao giờ được gọi)status only
any405Phương thức sai (open/run yêu cầu POST, download yêu cầu GET)status only
open400Không phải tải lên multipartExpected a multipart file upload.
open400Không có tệp, hoặc tệp rỗngNo file uploaded.
open400Kiểu không thể chuyển đổiThis file type cannot be converted.
open403Kiể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.
open413Tải lên vượt quá MaxUploadMb (nhưng không vượt quá giới hạn IIS)File is too large.
run400Token không hợp lệ (không phải GUID)Invalid token.
run400Một target không thể phân tích thành ConversionTargetUnknown target format.
run400Mục tiêu không có trong allowedTargetsThat target format is not available for this file.
run404Tải lên đã hết hạn hoặc chưa bao giờ được mởUpload expired — please re-open the file.
open, run500Xử lý thất bạiMột thông điệp đã được làm sạch
download400 / 404Token tải xuống không hợp lệ, không biết hoặc đã hết hạnstatus only

Một vòng tròn hoàn chỉnh với fetch:

javascript
// 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

  1. Cài đặt plugin bên cạnh gói lõi, ở cùng phiên bản: Install-Package Doconut.NETFramework.Converter.
  2. Thêm tệp giấy phép. Đặt Doconut.Viewer.Converter.lic trong cùng thư mục với Doconut.Viewer.lic.
  3. Đặt giới hạn tải lên. MaxUploadMb trong AddConverterWidget là giới hạn mà Doconut áp dụng; giữ maxRequestLength và maxAllowedContentLength trong Web.config ở mức cao hơn (xem Giới hạn tải lên), và maxUploadMb của widget bằng với nó.
  4. Không bao giờ chặn khi chuyển đổi trong Web Forms (xem Trong Web Forms).
  5. Giải phóng kết quả chuyển đổi. Luồng ConvertAsync trả 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:

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";   // 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 Ttl sau khi được ghi; việc đọc không kéo dài thời gian này.
  • FarmKey phả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ột ArgumentException khi RootPath thiếu hoặc FarmKey ngắn hơn 32 byte.
  • Đặt RootPath tớ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

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

Đượ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

csharp
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ứngNguyên nhânCá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 ở ConvertAsyncSử 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 đầuTruyề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 DicomSử dụng một giấy phép cung cấp Dicom
Kết quả có dấu watermarkGiấ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ề 404AddConverterWidget() 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 widgetmaxRequestLength / maxAllowedContentLength dưới mức MaxUploadMbTă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 DicomSử 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ồnChỉ 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ênMở lại tệp; trong farm, đăng ký AddDoconutDistributedWidgets
Widget gặp lỗi khi UI ở nguồn khácCác endpoint không hỗ trợ CORSPhụ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ụngCá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 mountNhắ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 qua DoconutHost.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.axd và script bởi DoconutResourceModule, cả hai đều đăng ký trong Web.config, thay vì UseDoconut() và UseDoconutResources(). Widget cần basePath: '/DocImage.axd'.
  • Lỗi khởi động xuất hiện dưới dạng một 500 trố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?