转换器插件
将文档转换为 45 种目标格式
Converter 插件将 Doconut 转变为文档转换服务。它提供了公共 DocumentConverter 外观背后的引擎,并且(可选)通过 DocImage.axd 提供一个可直接嵌入的小部件,因此您可以从 C#、从小部件或从您自行编写的前端进行文档转换。
| 表面 | 使用场景 |
|---|---|
DocumentConverter (C#) | 您在服务器上进行转换,不涉及浏览器 |
嵌入式小部件 (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 相同的文件夹中;它会与查看器许可证一起读取。
注册插件
每个插件的注册方式相同:在 DoconutHost.Initialize 中使用 AddPlugin<TPlugin>(),并从 Application_Start 调用。
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});这就是 C# 外观所需的全部。小部件及其 HTTP 端点是一个单独的可选项,AddConverterWidget()(参见 嵌入式小部件)。
插件需要一个授予 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 事件日志(来源 ASP.NET)中。它会因没有许可证、旧版 TRIAL 文件、缺少 Converter 的许可证以及在版本窗口之外使用的付费许可证而抛出异常。临时 Demo/NFR 许可证是被接受的。参见 许可证设置。
许可与水印
| 许可证状态 | 启动时 | 转换输出 |
|---|---|---|
付费查看器许可证授予 Converter,且在其版本窗口内 | 启动 | 干净 — watermarked: false |
| 有效的临时(Demo/NFR)许可证 | 启动 | 转换,带有评估水印 — watermarked: true |
| 已过期的临时(Demo/NFR)许可证 | 启动 | 转换,带有评估水印 — watermarked: true |
没有许可证、旧版 TRIAL 文件、缺少 Converter 的许可证,或在版本窗口之外的付费许可证 | Application_Start 抛出异常;每个请求返回空的 500 | — |
DocumentConverter 外观和小部件的 ?convert=run 处理程序遵循相同的规则。可以在购买前使用评估许可证进行端到端的集成构建和测试——仅输出字节会变化。
DICOM 源(.dcm,.ima)同样需要 Dicom 能力。若没有它,ConvertAsync 会抛出一个 LicenseException(Converting '.dcm' requires the Dicom capability license.),而小部件的 open 返回 403。
从 C# 使用
每次转换都会返回一个定位在 0 的可查找 MemoryStream。DocumentConverter 是无状态的:可以在需要的任何地方从 DoconutHost.Services 解析它并自由复用。
// 从 DoconutHost.Services 解析 DocumentConverter;其构造函数是 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,保存要转换回 Word 文档的 HTML,例如 WordToHtmlAsync 的结果。
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);两个容易出错的细节:流重载上的 sourceExtension 必须包含前导点(".xlsx",而不是 "xlsx"),否则无法解析。并且尽管名称如此,WordToHtmlAsync 返回的是 Task<Stream>,而不是 Task<string> —— HTML 文档(图像以 Base64 嵌入)以流的形式到达,和其他所有结果一样。
调用方拥有转换返回的 MemoryStream,并应在复制或返回后进行释放(MVC 的 File(stream, …) 会为您释放)。不要自行构造或释放 DocumentConverter —— 它的构造函数是内部的。
在 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 页面在单线程请求上下文中运行。ConvertAsync 在完成后会在该上下文中恢复,因此同步等待它的页面 —— .Result、.Wait()、.GetAwaiter().GetResult() —— 会占用转换所需的线程。请求永不返回。 浏览器一直转圈,IIS 没有记录任何日志,站点的其余部分仍然正常工作,所以看起来像是转换慢而不是死锁。
将页面标记为 Async="true" 并将转换作为页面异步任务运行:
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// Web Forms: @Page 指令需要 Async="true",并且转换作为页面异步任务运行。
// 相反地对其进行阻塞(.Result、.Wait()、.GetAwaiter().GetResult())会导致请求死锁:
// 它永远不会返回,也没有任何日志记录。
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();
}
}));
}如果在 @Page 指令中缺少 Async="true",RegisterAsyncTask 将被静默忽略。进行 await 后,使用页面的 Context;HttpContext.Current 可以在此处被 null。
目标格式
ConversionTarget(命名空间 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、web document、DICOM)都有各自允许的目标。转换 DICOM 源(.dcm、.ima)还需要一个授予 Dicom 能力的许可证;其目标包括 Pdf、Png、Jpeg、Bmp、Tiff 和 Gif。不要将此枚举硬编码为 UI 的目标列表:?convert=open 返回上传文件的 allowedTargets,这应当用于驱动选择器。
可嵌入小部件
启用端点
小部件的 ?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(字节)在 Web.config 中高于 widget 的 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是 ASP.NET Core 端点。在此包中,端点是来自Web.config的DocImage.axd处理程序。- 脚本和端点是独立的。 资源模块会提供
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 选择器或元素,如果未找到挂载点则抛出错误,并返回一个句柄。小部件上传文件,显示第 1 页的预览,让用户从 allowedTargets 中选择一个,进行转换,在可能时预览结果,并提供下载。
选项
| 选项 | 类型 | 默认值 | 备注 |
|---|---|---|---|
basePath | string | /doconut | 端点 URL。请在此包上设置 '/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]; // 来自您自己的 File <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,以及用于 --dcw-font 的系统 UI 字体。
构建您自己的前端
该小部件是 DocImage.axd 上此 HTTP 合约的客户端。路由在调用 AddConverterWidget() 之前会返回 404。错误会携带 JSON 正文 { "error": "..." },除非表格中标注为“仅状态”。未知的 ?convert= 值会返回 400。
| 路由 | 目的 | 成功响应 |
|---|---|---|
POST /DocImage.axd?convert=open(multipart,单文件) | 上传并打开源文档 | 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")——这与 ConvertAsync 的 sourceExtension 参数相反。allowedTargets 列出小写的目标名称("pdf"、"html",…);将其中之一作为 target 传入,匹配时不区分大小写。open 使用 multipart 正文中的第一个文件。
resultToken 为 null,而 resultPages 为 0,当结果无法预览时。downloadName 为源文件名加上目标的扩展名。
预览图像使用标准查看器图像路由 /DocImage.axd?token={token}&page=1&thumb=1&width={px},并使用来自 open 的 token 或来自 run 的 resultToken。小部件请求 width=240。
上传的源文件在最后一次读取后会保留 30 分钟;此后,run 会返回 404,文件必须重新打开。转换完成后,downloadToken 获得其自己的 30 分钟窗口。resultToken 是用于预览结果的普通查看器令牌;当结果可以预览时,其值与 downloadToken 相同。
| 路由 | 状态 | 何时 | 正文 |
|---|---|---|---|
| any | 404 | 小部件未启用(AddConverterWidget() 从未被调用) | 仅状态 |
| any | 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 | 一个无法解析为 ConversionTarget 的 target | 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);
}这些端点是 同源 的:此版本不支持 CORS。请将您的 UI 和小部件脚本部署在与 Doconut 相同的源下,或在您的 UI 源下对处理程序和资源路径进行反向代理。
生产环境
- 安装插件 与核心包并排,使用相同版本:
Install-Package Doconut.NETFramework.Converter. - 添加许可证文件。 将
Doconut.Viewer.Converter.lic放在与Doconut.Viewer.lic相同的文件夹中. - 设置上传上限。
MaxUploadMb在AddConverterWidget中是 Doconut 强制的限制;保持maxRequestLength和maxAllowedContentLength在Web.config中高于它(参见 上传限制),并使小部件的maxUploadMb等于它. - 永不在 Web 表单中阻塞转换(参见 在 Web 表单中).
- 处理转换结果。
ConvertAsync返回的流是池化的;释放它会将其缓冲区返回到池中.
Web 农场
小部件将每个上传及其结果保存在提供 open 的服务器内存中。若负载均衡器未使用粘性会话,后续的 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 bytes,在每个服务器上保持一致
// store.Ttl = TimeSpan.FromMinutes(30); // 上传保留多长时间(默认)
}));- 单个服务器不需要任何操作:如果不调用此方法,将使用内存存储。
- 上传和结果在共享存储上静态加密(AES-256,先加密后 MAC),每个文件绑定到其令牌,因此一个令牌永远无法读取另一个令牌的文件。
- 在共享存储上,上传或结果在写入后会保留
Ttl;读取它不会延长此时间窗口。 FarmKey必须至少 32 字节且在每台服务器上保持一致。从机密存储加载它;绝不硬编码。注册时如果缺少RootPath或FarmKey短于 32 字节会抛出ArgumentException。- 将
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 在 outputFormat 为 ConversionTarget.Doc 时写入 .doc 文件,其他任何值则写入 .docx 文件。
ConversionTarget
在 目标格式 中列出的 45 种输出格式。
ConverterWidgetOptions
public sealed class ConverterWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
}通过 DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null) 设置,它返回 DoconutOptions,以便可以链式调用。
故障排除
| 症状 | 原因 | 解决方案 |
|---|---|---|
每个请求在添加插件后返回空的 500;Windows 事件日志(来源 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 未注册 | 在 DoconutHost.Initialize 中添加 AddPlugin<ConverterPlugin>() |
| Web Forms 转换永不返回 | 页面在 ConvertAsync 上阻塞 | 使用 Async="true" 和 RegisterAsyncTask |
| 流转换提示格式不受支持 | sourceExtension 没有前导点 | 传递 ".xlsx",而不是 "xlsx" |
ConvertAsync 抛出 Converting '.dcm' requires the Dicom capability license. | 一个 DICOM 源,且许可证未授予 Dicom | 使用授予 Dicom 的许可证 |
| 输出带有水印 | 许可证是临时的(演示/非正式授权) | 使用授予 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 之一 | 仅提供来自 convert=open 的 allowedTargets |
run 或 download 返回 404(来自 run 的 Upload expired — please re-open the file.) | 30 分钟窗口已过,或集群中的另一台服务器没有该上传文件 | 重新打开文件;在集群中,注册 AddDoconutDistributedWidgets |
| 当 UI 位于不同源时小部件失败 | 端点未提供 CORS 支持 | 从相同源提供 UI,或对 Doconut 路径进行反向代理 |
| 主题未生效 | 变量被设置在祖先元素或挂载内部的元素上;小部件自己的 .dcw 规则在挂载上设置它们 | 直接定位挂载本身:#doconut-convert.dcw 或 #doconut-convert |
框架说明
与 ASP.NET Core 包相比,此包仅在托管方式上有所不同;API、端点契约、小部件脚本和许可规则保持一致。
- 注册 位于
Application_Start,通过DoconutHost.Initialize,而不是builder.Services.AddDoconut。诸如AddDoconutDistributedWidgets的服务放在其第二个参数中。 - 端点 由
DocImage.axd提供,脚本由DoconutResourceModule提供,二者均在Web.config中注册,而不是UseDoconut()和UseDoconutResources()。小部件需要basePath: '/DocImage.axd'。 - 启动失败 表现为每个请求返回空的
500,原因记录在 Windows 事件日志中。 - 上传 在 Doconut 处理之前会被 ASP.NET 完全读取,因此 IIS 限制必须高于
MaxUploadMb。 - Web Forms 页面不得在转换上阻塞;参见 在 Web Forms 中。
- 仅限 Windows,与 .NET Framework 包的其余部分相同。
此页面对您有帮助吗?