故障排除

诊断常见错误

许多 System.Web 故障不会抛出可见的异常:页面返回空的 500,图标出现 404,或请求永不返回。此页面按您观察到的情况组织。引用的消息是 Doconut 产生的原始文本。

一目了然的症状

您看到的情况最可能的原因解决方案
每个 请求返回空的 500在 Application_Start 中出现异常:插件缺少许可证、选项无效、农场配置不完整——或绑定重定向指向的版本不在 bin\ 中Windows 事件日志,Application,来源 ASP.NET。参见 启动失败
某些 MVC 页面返回空的 500Razor 在运行时编译视图:netstandard 外观缺失于 <compilation>,或视图使用了高于 5 的 C#(?.、$"..."、nameof)添加外观(安装);将逻辑从视图移至控制器
页面显示 —、… 或类似字符,而不是破折号和重音符号没有字节顺序标记的页面文件会使用服务器的 ANSI 代码页读取<globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
浏览器控制台显示 404,针对 HEAD /DocImage.axd?...&page=1处理程序注册时缺少 HEAD 动词verb="GET,HEAD,POST" 在处理程序上
文档可以渲染,但工具栏图标和加载指示器缺失ResPath 指向资源根,或以 / 开头ResPath: 'doconut-res/images'
/doconut-res/... 请求返回 404资源模块未注册,runAllManagedModulesForAllRequests 已关闭,或 MVC 路由捕获了路径<modules> 条目,以及 routes.IgnoreRoute("doconut-res/{*pathInfo}")
查看器报告 The viewer handler could not be reached (no response).BasePath 以 / 开头('/myapp' 变为 //myapp/…,另一个主机)BasePath: '/' 位于站点根目录;'myapp' 位于虚拟目录中
查看器报告 Please make sure your middleware is configured.DocImage.axd 返回了 404:处理程序不在 Web.config 中,MVC 路由捕获,或 BasePath 指向其他位置<handlers> 条目、routes.IgnoreRoute("{resource}.axd/{*pathInfo}") 和 BasePath
每个页面显示 You Are Not Authorized To View This Page.文档在没有会话状态的请求中打开,会话状态已关闭,或会话 Cookie 未能到达 DocImage.axd参见 未授权
Web Forms 转换永不返回页面在 ConvertAsync 处阻塞——死锁Async="true" + RegisterAsyncTask(转换插件)
每个页面都有评估水印未找到许可证——它不在 <site root>\wwwroot 中许可证设置
小部件加载,但其第一次操作返回 404小部件未启用,或其 basePath 未设置为 '/DocImage.axd'options.Add…Widget(),以及 basePath: '/DocImage.axd'
站点启动或回收后,第一个文档需要一分钟或更久;后续文档加载很快文档引擎在首次打开时加载,且实时防病毒在加载时进行扫描预热站点并保持池运行——参见 启动后第一个文档
大文件上传时显示 IIS 错误页面上传超过 maxRequestLength(KB)或 maxAllowedContentLength(字节)将两者的限制提升至大于您最大的文件或小部件上限

启动失败

在 Application_Start 中抛出的异常不会传递到浏览器:每个请求返回空的 500,且 IIS 日志没有有用信息。该异常记录在 Windows 事件日志(事件查看器 → Windows 日志 → Application,来源 ASP.NET)。常见的如下:

缺少许可证的插件:

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.

插件的 Doconut.Viewer.<Capability>.lic 必须位于 wwwroot,与 Doconut.Viewer.lic 相邻。缺少许可证以及旧版 TRIAL 文件会导致插件无任何功能。

无效选项:

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

无法加载的程序集。 ASP.NET 在应用启动时会加载 bin\ 中的所有程序集,因此 Web.config 中指向缺失于 bin\ 的版本的绑定重定向会导致整个站点停止。请复制 NuGet 生成的重定向(对于 SDK 风格的项目,来自 bin\<YourApp>.dll.config),而不是手动编辑,并在包更新后再次复制它们。

您无权查看此页面。

页面被拒绝,因为请求的 ASP.NET 会话从未获得该文档的授权。请按以下顺序检查:

  1. 打开时使用了会话状态。 MVC 控制器和 Web Forms 页面都有会话状态。自定义 IHttpHandler 用于打开文档时必须实现 System.Web.SessionState.IRequiresSessionState,否则它没有可授予的会话。
  2. 会话状态已开启。 <sessionState mode="Off" /> 拒绝所有页面。
  3. Cookie 能到达处理程序。 小部件的同源请求会携带 ASP.NET_SessionId;脚本、服务器到服务器的调用或不带 Cookie 的跨域页面则不会。
  4. Web 农场: 打开时绑定浏览器(DocOptions.BrowserId),页面传递票据(objViewer.View(token, access));每个节点使用相同的签名密钥。

该拒绝响应是一张状态码为 200 的图片,约 2 KB。仅检查状态码的监控会将其计为一个页面。

未找到文档会话。请重新打开文档。

令牌已过期(滑动窗口,DocOptions.TimeOut,默认 60 分钟),文档已关闭,或者——在单服务器环境下——应用程序池已回收。回收会在计划时间、每次 Web.config 编辑以及池的空闲超时后(IIS 默认 20 分钟)发生。请重新打开文档以获取新令牌。

打开文档失败

LicenseException,原因被拒 — 找到了许可证文件但被拒绝(签名无效、被篡改、列入黑名单,或构建版本超出许可证的版本窗口)。打开被阻止,而不是加水印。

LicenseException:

text
This document type requires the 'Dicom' plugin license.

该扩展仅由插件(此处为 DICOM)处理。插件已注册,但没有许可证再授予其功能——通常是站点启动后已过期的临时许可证。请安装授予该功能的许可证。

FormatNotSupportedException — 没有查看器(内置、插件或自定义)声明支持该扩展。DoconutOptions.RegisterViewer 可以为您自己的格式添加一个。

InvalidDataException — 内容损坏或与其扩展名不匹配(如重命名文件)。在打开之前请验证上传的文件。

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

DocumentConverter 已在未注册 Converter 插件的情况下解决。

输出异常

页面带有水印 — 未找到许可证,或临时许可证已过期。在有效的临时许可证下,仅插件输出会加水印。未覆盖此版本的许可证不会加水印:打开时会抛出 LicenseException。在 IIS 下,许可证必须放在站点根目录下的 wwwroot(AppContext.BaseDirectory\wwwroot),而不是放在 bin\。检查 IDoconutLicenseService(License.IsLicenseFileFound、IsExpired、IsVersionValid、License.RejectionMessage)。

旧版文档渲染为乱码 — 在启动时一次性注册代码页编码:

csharp
// Global.asax.cs, Application_Start - 在 DoconutHost.Initialize 之前。
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

字体错误或被替换 — 服务器缺少文档所需的字体。没有 Office 的 Windows Server 的字体远少于开发机器。请安装这些字体,或将 FontFolders(在 WordConfig 和 PptConfig 上)指向包含这些字体的文件夹。

图像标注在查看器中显示,但导出时出现 “Image blocked” 框 — 图像的主机使用私有或回环地址,服务器拒绝获取。参见 注释。

功能在评估版可用,生产环境中无效

有效的临时许可证授予所有功能;您购买的许可证仅授予已购买的功能。如果缺少某项功能,其搜索或标注文件将不会生成,已注册的插件会在启动时阻止站点运行。部署前请将 IsCapabilityGranted(...) 与您使用的每个功能进行比较。

搜索未找到任何内容(或太少)

  • 对于 PDF,在打开文档时未启用 AllowSearch —— 默认使用 false。Word、Excel 和 PowerPoint 也提供相同的开关。
  • 内容是扫描的或仅为图像,因此没有可匹配的文本层。
  • HTML 和 Microsoft Project(MPP)在默认设置下不可搜索:设置 DefaultRender = false 使其通过带文本的 PDF 投影进行渲染。
  • objViewer.CanSearch() 在初始化后是 false:解析的格式没有搜索路径。这与 Search 许可证是分开的;请两者都检查。
  • 页面读取 objViewer.Search(...) 的返回值——计数在其第三个参数(回调函数)中返回。

仍然卡住?

使用 快速入门 中的最小化设置复现问题。如果在那里也能复现,请联系支持并提供文档、您的 Global.asax.cs、Web.config 的 Doconut 部分,以及(如果有的话)Windows 事件日志条目。

此页面对您有帮助吗?