故障排除

诊断常见错误

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

一目了然的症状

您看到的情况最可能的原因解决方案
每个请求返回空的 500在 Application_Start 中出现异常：插件缺少许可证、选项无效、农场配置不完整——或绑定重定向指向的版本不在 bin\ 中Windows 事件日志，Application，来源 ASP.NET。参见 启动失败
某些 MVC 页面返回空的 500Razor 在运行时编译视图：netstandard 外观缺失于 <compilation>，或视图使用了高于 C# 5 的语言特性（?.、$"..."、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 插件的情况下解析。

输出异常

页面带有水印 —— 未找到许可证，或已过期，或不适用于此版本。 在 IIS 下，许可证必须放在站点根目录 (AppContext.BaseDirectory\wwwroot) 下的 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：解析的格式没有搜索路径。这与搜索许可证分开；请两者都检查。
  • 页面读取 objViewer.Search(...) 的返回值 —— 计数在其第三个参数（回调函数）中返回。

仍然卡住？

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

此页面对您有帮助吗？