故障排除
诊断常见错误
许多 System.Web 故障不会抛出可见的异常:页面返回空的 500,图标出现 404,或请求永不返回。此页面按您观察到的情况组织。引用的消息是 Doconut 产生的原始文本。
一目了然的症状
| 您看到的情况 | 最可能的原因 | 解决方案 |
|---|---|---|
每个 请求返回空的 500 | 在 Application_Start 中出现异常:插件缺少许可证、选项无效、农场配置不完整——或绑定重定向指向的版本不在 bin\ 中 | Windows 事件日志,Application,来源 ASP.NET。参见 启动失败 |
某些 MVC 页面返回空的 500 | Razor 在运行时编译视图: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)。常见的如下:
缺少许可证的插件:
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 文件会导致插件无任何功能。
无效选项:
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 会话从未获得该文档的授权。请按以下顺序检查:
- 打开时使用了会话状态。 MVC 控制器和 Web Forms 页面都有会话状态。自定义
IHttpHandler用于打开文档时必须实现System.Web.SessionState.IRequiresSessionState,否则它没有可授予的会话。 - 会话状态已开启。
<sessionState mode="Off" />拒绝所有页面。 - Cookie 能到达处理程序。 小部件的同源请求会携带
ASP.NET_SessionId;脚本、服务器到服务器的调用或不带 Cookie 的跨域页面则不会。 - Web 农场: 打开时绑定浏览器(
DocOptions.BrowserId),页面传递票据(objViewer.View(token, access));每个节点使用相同的签名密钥。
该拒绝响应是一张状态码为 200 的图片,约 2 KB。仅检查状态码的监控会将其计为一个页面。
未找到文档会话。请重新打开文档。
令牌已过期(滑动窗口,DocOptions.TimeOut,默认 60 分钟),文档已关闭,或者——在单服务器环境下——应用程序池已回收。回收会在计划时间、每次 Web.config 编辑以及池的空闲超时后(IIS 默认 20 分钟)发生。请重新打开文档以获取新令牌。
打开文档失败
LicenseException,原因被拒 — 找到了许可证文件但被拒绝(签名无效、被篡改、列入黑名单,或构建版本超出许可证的版本窗口)。打开被阻止,而不是加水印。
LicenseException:
This document type requires the 'Dicom' plugin license.该扩展仅由插件(此处为 DICOM)处理。插件已注册,但没有许可证再授予其功能——通常是站点启动后已过期的临时许可证。请安装授予该功能的许可证。
FormatNotSupportedException — 没有查看器(内置、插件或自定义)声明支持该扩展。DoconutOptions.RegisterViewer 可以为您自己的格式添加一个。
InvalidDataException — 内容损坏或与其扩展名不匹配(如重命名文件)。在打开之前请验证上传的文件。
InvalidOperationException:
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)。
旧版文档渲染为乱码 — 在启动时一次性注册代码页编码:
// 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 事件日志条目。
此页面对您有帮助吗?