安装

将 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 项目无法使用此包，请先重新定位目标框架。
  • 站点必须运行在 integrated pipeline（IIS 与 IIS Express 应用程序池的默认模式）中。

本页针对 Doconut.NETFramework 26.9.0 及以后 版本进行说明。26.8.0 及更早版本面向 .NET Framework 4.7，使用不同的 API，已不再维护。跨版本升级的细节请参见 迁移。

安装包

从包管理器控制台执行：

powershell
Install-Package Doconut.NETFramework

或在 SDK 风格的项目中使用：

bash
dotnet add package Doconut.NETFramework

渲染引擎已嵌入在包中：无需额外引用、复制或部署独立的引擎程序集。可选功能以独立的包形式提供，例如 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 only: Razor compiles views at run time and needs the netstandard facade. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength is in KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Read .cshtml and .aspx files as UTF-8, not as the server's ANSI code page. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength is in BYTES: the same 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。查看器会对第一页发送 HEAD 请求以检测动画图像。如果缺少该动词，IIS 会在处理程序运行前返回 404：文档仍能显示，但动画检测失效，浏览器控制台会充满 404 错误。
  • runAllManagedModulesForAllRequests="true" — /doconut-res/*.js、.css、.png 看起来像静态文件，若不启用此设置，IIS 会先交给静态文件处理程序，导致查看器缺少脚本和图标。
  • <globalization fileEncoding="utf-8"> — 页面文件若以 UTF-8（无 BOM）保存，否则会使用服务器的 ANSI 代码页读取，导致所有非 ASCII 字符在浏览器中被双重编码（例如长破折号显示为 —）。文件本身是正确的，页面仍声明 <meta charset="utf-8">。
  • netstandard 程序集（MVC 5） — Razor 在首次请求时编译视图，其引用列表不包含此 facade。任何超出普通成员访问的动态视图都会因 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 中一次性在工作进程中组成，并在 Application_End 中通过 DoconutHost.Shutdown 释放：

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

PropertyDefaultDescription
UnsafeModefalse为 false 时，DocImage.axd 只向打开文档的 ASP.NET 会话提供页面。为 true 时，任何携带 token 的请求都会被服务。请保持 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 时读取一次；更换许可证文件后请回收应用池。

当设置了多个许可证来源时，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 如何查找您的许可证文件。

此页面对您有帮助吗？