安装
将 Doconut 添加到您的 .NET Framework 4.7.2 Web 应用程序
Doconut.NETFramework 在 .NET Framework 4.7.2 的经典 ASP.NET 应用程序中托管 Doconut 查看器 — IIS 或 IIS Express,MVC 5 或 Web Forms。设置包括三部分:NuGet 包、在 Web.config 中的两个注册以及在 Global.asax 中的一个调用。本页涵盖全部三项;快速入门 然后在页面上放置文档。
要求
- Web 项目目标为 .NET Framework 4.7.2 或更高版本。4.7 项目无法使用此包;请先重新定位。
- 站点运行在 集成管道(IIS 和 IIS Express 应用程序池的默认设置)中。
- 服务器运行 Windows。此包仅限 Windows。
本页覆盖 Doconut.NETFramework 26.9.0 及更高版本。26.8.0 及更早版本针对 .NET Framework 4.7,使用不同的 API;该线路已停止。跨越此界限的现有应用程序更新请参见 迁移。
安装包
从 Package Manager Console:
Install-Package Doconut.NETFramework或者,在 SDK 样式项目中:
dotnet add package Doconut.NETFramework未指定版本的命令会安装最新的稳定版。若要固定本文档所述的版本,请传入版本号:
Install-Package Doconut.NETFramework -Version 26.10.0dotnet add package Doconut.NETFramework --version 26.10.0渲染引擎已嵌入包中:无需引用、复制或部署单独的引擎程序集。可选功能作为独立的包提供——例如 Doconut.NETFramework.Converter 和 Doconut.NETFramework.Dicom ——且每个都需要相应的许可证(参见 插件系统)。
配置 Web.config
Doconut 提供两种请求,IIS 通过 Web.config 路由两者:
DocImage.axd— 查看器的页面、缩略图、搜索和注释端点,由Doconut.DocImageHandler提供。/doconut-res/*— 查看器自身的脚本、样式表和图标,嵌入程序集并由Doconut.DoconutResourceModule提供。
添加两者以及它们依赖的设置:
<configuration>
<system.web>
<!-- 仅限 MVC 5:Razor 在运行时编译视图,并且需要 netstandard 外观。 -->
<compilation targetFramework="4.7.2">
<assemblies>
<add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
</assemblies>
</compilation>
<!-- maxRequestLength 的单位是 KILOBYTES:200 MB。 -->
<httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
<!-- 将 .cshtml 和 .aspx 文件读取为 UTF-8,而不是服务器的 ANSI 代码页。 -->
<globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
</system.web>
<system.webServer>
<security>
<requestFiltering>
<!-- maxAllowedContentLength 的单位是 BYTES:同样的 200 MB。 -->
<requestLimits maxAllowedContentLength="209715200" />
</requestFiltering>
</security>
<modules runAllManagedModulesForAllRequests="true">
<add name="DoconutResourceModule" type="Doconut.DoconutResourceModule, Doconut" />
</modules>
<handlers>
<add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd"
type="Doconut.DocImageHandler, Doconut" />
</handlers>
</system.webServer>
</configuration>每行都防止一种不会抛出异常的失败:
verb="GET,HEAD,POST"— 保持HEAD。查看器会对第 1 页发送HEAD请求以检测动画图像。若缺少该动词,IIS 会在处理程序运行前返回404:文档仍然显示,但动画检测永不工作,浏览器控制台充满 404。runAllManagedModulesForAllRequests="true"—/doconut-res/*.js、.css和.png看起来像静态文件,IIS 会在资源模块看到之前将它们交给静态文件处理程序。结果是查看器没有脚本或图标。<globalization fileEncoding="utf-8">— 页面文件若以 UTF-8(无字节顺序标记)保存,则会被服务器的 ANSI 代码页读取,导致每个非 ASCII 字符在浏览器中被双重编码(破折号显示为—)。文件在磁盘上是正确的,页面仍声明<meta charset="utf-8">。netstandard程序集 (MVC 5) — Razor 在首次请求时编译视图,使用自己的引用列表,其中不包含此外观层。任何超出普通成员访问的动态视图都会因CS0012而失败,并返回空的500,仅导致触发它的页面出错。编译器错误仅出现在 Windows 事件日志(来源 ASP.NET)中。Web Forms 应用程序不需要此行。- 上传限制 — ASP.NET 在任何处理程序运行之前读取整个请求体,因此超过这些限制的上传会被 IIS 用其错误页面拒绝。保持
maxRequestLength(千字节)和maxAllowedContentLength(字节)同步,并高于用户打开或上传的最大文件。
另外两个设置也很重要,且通常已经正确:
- 会话状态保持开启 — 默认情况下,页面仅提供给打开文档的 ASP.NET 会话,因此站点不得设置
<sessionState mode="Off" />。参见 会话与安全。 - 绑定重定向 — 保持 NuGet 写入
Web.config的<runtime>绑定重定向。在 SDK 样式项目中,从生成的bin\<YourApp>.dll.config复制它们,因为经典 ASP.NET 只从Web.config读取重定向。若重定向指向bin\中缺失的版本,应用程序将在启动时因空的500而停止。
在 Global.asax 中注册 Doconut
System.Web 中没有构建器和中间件管道。Doconut 由 DoconutHost.Initialize 在 Application_Start 中一次性组成于每个工作进程,并由 DoconutHost.Shutdown 在 Application_End 中释放:
// Global.asax.cs
protected void Application_Start()
{
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
});
}
protected void Application_End()
{
Doconut.DoconutHost.Shutdown();
}DoconutHost.Initialize 构建处理程序、资源模块以及您自己的代码使用的服务。您的代码通过 DoconutHost.Services 访问它们(参见 DoconutHost)。只有第一次调用会进行配置;第二次调用会被忽略。在 MVC 应用程序中,还需将两个 Doconut 路径排除在路由之外——快速入门 展示了完整的 Application_Start。
所有选项
DoconutOptions 接受以下可设置属性。每个属性都是可选的。
| 属性 | 默认值 | 描述 |
|---|---|---|
UnsafeMode | false | 当 false 时,DocImage.axd 仅向打开文档的 ASP.NET 会话提供页面。当 true 时,任何携带该令牌的请求都会被提供。保持 false 即可。 |
ShowDoconutInfo | false | 当 true 时,未携带 token 的 DocImage.axd 请求会返回版本横幅,而不是 404。可用于快速检查;在生产环境中请关闭。 |
ResourcesPath | "/doconut-res" | 资源模块提供嵌入式脚本、样式和图标的路径。仅在同时更改查看器的 ResPath 和任何 MVC IgnoreRoute 时才修改此项。 |
LicensePath | "" | 许可证文件的完整路径。为空表示继续查找下一个来源,然后使用自动发现。 |
LicenseContent | "" | 原始许可证内容——来自环境变量、密钥存储或数据库。 |
LicenseStream | null | 许可证作为流,在启动时读取一次。 |
MiddlewarePath | "/doconut" | 此包不使用。页面端点是 Web.config 中声明的 DocImage.axd 处理程序,无论此值设置为何。仍会进行验证:必须以 / 开头且不同于 ResourcesPath。 |
ResetLicense | false | 此包不使用。许可证在 DoconutHost.Initialize 时读取一次;更换许可证文件后请回收应用程序池。 |
MaxConcurrentEditorSessions | 200 | 活动编辑器会话(使用 DocOptions.EditMode 打开的文档)的最大数量。超过此数量时,最久未使用的空闲编辑器会话将被关闭。普通查看器会话不计入。0 或负值表示无限制。 |
EditorSnapshotEveryOps | 50 | 在启用编辑器持久化 (AddDoconutEditorPersistence) 时,每 N 次记录的更改对实时文档进行快照。0 或负值表示在会话期间不进行快照。持久化关闭时此设置无效。 |
当设置了多个许可证来源时,LicenseStream 优先于 LicenseContent,后者优先于 LicensePath,最后才是自动发现——参见 许可证设置。
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.ResourcesPath = "/doconut-res"; // viewer 的 JS/CSS/图片 的提供位置
options.UnsafeMode = false; // 保持会话安全
options.ShowDoconutInfo = false;
});
// 此处不能使用页面端点:它是 Web.config 中声明的 DocImage.axd 处理程序。后续步骤
此页面对您有帮助吗?