安装

将 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:

powershell
Install-Package Doconut.NETFramework

或者,在 SDK 样式项目中:

bash
dotnet add package Doconut.NETFramework

未指定版本的命令会安装最新的稳定版。若要固定本文档所述的版本,请传入版本号:

powershell
Install-Package Doconut.NETFramework -Version 26.10.0
bash
dotnet 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 提供。

添加两者以及它们依赖的设置:

xml
<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 中释放:

csharp
// 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 接受以下可设置属性。每个属性都是可选的。

属性默认值描述
UnsafeModefalse当 false 时,DocImage.axd 仅向打开文档的 ASP.NET 会话提供页面。当 true 时,任何携带该令牌的请求都会被提供。保持 false 即可。
ShowDoconutInfofalse当 true 时,未携带 token 的 DocImage.axd 请求会返回版本横幅,而不是 404。可用于快速检查;在生产环境中请关闭。
ResourcesPath"/doconut-res"资源模块提供嵌入式脚本、样式和图标的路径。仅在同时更改查看器的 ResPath 和任何 MVC IgnoreRoute 时才修改此项。
LicensePath""许可证文件的完整路径。为空表示继续查找下一个来源,然后使用自动发现。
LicenseContent""原始许可证内容——来自环境变量、密钥存储或数据库。
LicenseStreamnull许可证作为流,在启动时读取一次。
MiddlewarePath"/doconut"此包不使用。页面端点是 Web.config 中声明的 DocImage.axd 处理程序,无论此值设置为何。仍会进行验证:必须以 / 开头且不同于 ResourcesPath。
ResetLicensefalse此包不使用。许可证在 DoconutHost.Initialize 时读取一次;更换许可证文件后请回收应用程序池。
MaxConcurrentEditorSessions200活动编辑器会话(使用 DocOptions.EditMode 打开的文档)的最大数量。超过此数量时,最久未使用的空闲编辑器会话将被关闭。普通查看器会话不计入。0 或负值表示无限制。
EditorSnapshotEveryOps50在启用编辑器持久化 (AddDoconutEditorPersistence) 时,每 N 次记录的更改对实时文档进行快照。0 或负值表示在会话期间不进行快照。持久化关闭时此设置无效。

当设置了多个许可证来源时,LicenseStream 优先于 LicenseContent,后者优先于 LicensePath,最后才是自动发现——参见 许可证设置。

csharp
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 处理程序。

后续步骤

  • 快速入门 — 在 MVC 5 或 Web Forms 中打开文档并在浏览器中渲染。
  • 许可证设置 — Doconut 查找许可证文件的位置。

此页面对您有帮助吗?