快速入门
在 MVC 5 或 Web Forms 中渲染您的第一个文档
本指南将一个基于 .NET Framework 4.7.2 的 ASP.NET 应用程序,从已安装的包转化为在浏览器中渲染的文档:Global.asax、一个打开端点、查看器的资源、部件以及连接它们的令牌。它假设已完成来自安装的Web.config 注册——如果缺少DocImage.axd 处理程序和资源模块,下面的内容将无法访问服务器。
在 Global.asax 中组合 Doconut
针对 MVC 5 应用程序的完整 Application_Start:
// Global.asax.cs - 每个工作进程仅构建一次,关闭时释放。
protected void Application_Start()
{
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.UnsafeMode = false; // 页面仅提供给打开文档的会话
});
// MVC only: 保持两个 Doconut 端点不被路由。
RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}
protected void Application_End()
{
Doconut.DoconutHost.Shutdown();
}Encoding.RegisterProvider使某些文档格式使用的传统代码页对进程可用。请在打开第一个文档之前调用一次。UnsafeMode = false是默认设置,明确写出以防止有人意外更改:DocImage.axd仅向打开文档的 ASP.NET 会话提供页面。- 两个
IgnoreRoute调用 将 MVC 路由从DocImage.axd和/doconut-res/*中排除,这些由处理程序和模块提供。Web Forms 应用程序没有 MVC 路由,因此不需要此行。 DoconutHost.Shutdown在应用程序池回收时停止 Doconut 的后台工作并释放其服务。即使Initialize从未运行,调用它也是安全的。
打开文档
打开文档会返回一个不透明的令牌。部件在每个页面请求中都会发送该令牌。
在 MVC 5 中,控制器操作从 DoconutHost.Services 解析 Viewer 服务——MVC 5 不支持构造函数注入:
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
// 令牌是不透明的 - 将其交给查看器,绝不记录或持久化它。
string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
return Json(new { token });
}文档必须在具有会话状态的请求内部打开,因为打开文档会授予当前 ASP.NET 会话访问其页面的权限。MVC 控制器和 Web Forms 页面默认具有会话状态。自定义 IHttpHandler 没有会话状态,除非它实现了 System.Web.SessionState.IRequiresSessionState。如果在没有会话状态的处理程序中打开文档,查看器将在每个页面上显示 “您无权查看此页面。”。
在 Web Forms 中,页面本身可以在其代码隐藏文件中打开文档。OpenDocument 是 OpenDocumentAsync 的同步形式,适用于不使用异步页面的代码隐藏文件:
// Default.aspx.cs
protected string Token;
protected void Page_Load(object sender, EventArgs e)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
Token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
}将令牌视为持有者凭证:切勿记录或持久化它;仅交给部件使用。当文档会话过期时,它将失效——请重新打开文档以获取新的令牌。
引用查看器资源
Viewer.ReferenceCss 和 Viewer.ReferenceScripts 发出 <link> 和 <script> 标签,用于嵌入的资源,按依赖顺序指向 /doconut-res/。该小部件是一个 jQuery 插件,所以 jQuery 必须先加载。
MVC 5. 视图没有 @inject,因此在控制器中生成这些标签并通过 ViewBag 传递它们:
public ActionResult Index()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true
});
ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true
});
return View();
}@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)将这些工作保留在控制器中。MVC 5 在首次提供时编译视图,如果没有额外的编译器包,该编译器只能理解 C# 5 —— 没有 ?.,没有 $"...",没有 nameof。使用这些标签的视图在 Visual Studio 中能够顺利编译,然后在浏览器中返回一个空的 500。
Web Forms. 从代码隐藏文件中公开相同的字符串,并使用 <%= %> 写入它们:
<head>
<%= ViewerCss %>
</head>
<body>
...
<%= ViewerScripts %>
</body>IncludeViewerCss 和 IncludeViewerScripts 是必需的核心。要添加搜索和注释功能区,还需设置 IncludeSearchCss、IncludeAnnotationCss、IncludeSearchScripts、IncludeSearchBar、IncludeAnnotationScripts 和 IncludeAnnotationBar。当许可证未授予相应功能时,这两种方法都会省略相应功能区的文件;查看器本身仍会启动。
将查看器添加到页面
渲染表面是两个嵌套的 div:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>为外层 div 设置真实的高度 —— 查看器会填满其容器并在启动时进行测量。查看器不会绘制自己的工具栏:GotoPage、Next、Zoom、FitType,其余的都是页面绑定到自己按钮上的方法,这些按钮放在查看器旁边:
<nav id="toolbar" aria-label="Document viewer controls">
<button type="button" onclick="objViewer.GotoPage(1)">First</button>
<button type="button" onclick="objViewer.Next(false)">Previous</button>
<button type="button" onclick="objViewer.Next(true)">Next</button>
<button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
<button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
<button type="button" onclick="objViewer.FitType('width')">Fit width</button>
</nav>初始化查看器并显示文档
在加载查看器脚本后,创建小部件,然后将令牌交给它:
var objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: '/', // '/' 表示站点根目录下的 DocImage.axd
ResPath: 'doconut-res/images', // 没有前导 '/'
onViewerReady: function () {
// 页面已可见; 在此隐藏加载指示器
},
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});
fetch('/Document/Open', { method: 'POST' })
.then(function (resp) { return resp.json(); })
.then(function (data) { objViewer.View(data.token); });在 Web Forms 中,如果页面本身打开文档,则最后三行会变成 objViewer.View('<%= Token %>');。
以下四个细节会在没有错误信息的情况下失败:
BasePath: '/'在站点根目录定位DocImage.axd。对于位于虚拟目录中的应用程序,请使用不带斜杠的名称('myapp'请求/myapp/DocImage.axd)。前导斜杠('/myapp')会产生//myapp/DocImage.axd,浏览器会将其视为对另一个主机的请求。ResPath: 'doconut-res/images'—— 图标位于资源根目录下一级文件夹。使用'doconut-res'时,所有图标都会返回 404:没有工具栏图标,也没有加载指示器,而文档本身仍然渲染。前导斜杠会像BasePath那样导致同样的问题。- 回调是选项。
onViewerReady、onError以及其他回调应放在传递给docViewer(...)的对象中。像ctlDoc_ViewerReady这样的全局函数(以查看器命名)永远不会被调用。 - 保留查看器实例,然后单独调用
View。docViewer(...)返回包含Zoom、Next和FitType的对象;View(...)返回其他内容。var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)渲染文档,但在第一次点击工具栏时会因objViewer.Zoom is not a function而失败。
选项名称混合了 camelCase(showThumbs、autoLoad、pageZoom)和 PascalCase(FitType、BasePath、ResPath)。拼写错误的选项会被忽略,小部件会使用默认值。
单行替代方案
对于只需要显示文档且没有自定义工具栏的页面,Viewer.RenderViewer 会编写完整的初始化脚本 —— docViewer(...) 与 BasePath: '/' 和 ResPath: 'doconut-res/images',随后 .View(token)。它仅在此包中存在:
// Default.aspx.cs
protected string ViewerInit;
protected void Page_Load(object sender, EventArgs e)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
string token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
ViewerInit = viewer.RenderViewer("div_ctlDoc", token);
}<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>将 ViewerConfig 作为第三个参数传入,以更改缩放、适配或缩略图面板。由于生成的脚本不保留对查看器的引用,当页面需要自己的工具栏时,请使用上面手写的初始化代码。
关闭文档
当用户离开查看器或打开替代文档时,调用 objViewer.Close(true):它会清除小部件并向 DocImage.axd 发送关闭请求。objViewer.Close() 在不带参数的情况下仅清除小部件。在服务器端,viewer.CloseDocument(token) 会立即移除文档会话,释放其渲染资源,并撤销会话对页面的访问。滑动过期最终会产生相同效果,但显式关闭大型文档可以更快释放内存。
运行它
将 PDF 放置在 ~/files/Sample.pdf,在 IIS Express 中启动站点(在 Visual Studio 中按 F5),并打开承载小部件的页面。首个页面会渲染,左侧显示缩略图。如果未渲染,请参阅 故障排除。
未授权时的功能
缺少许可证不会抛出错误。查看器仍会正常渲染,但每页都会带有评估水印。请参阅 许可证设置 了解 Doconut 在何处查找您的许可证。
此页面对您有帮助吗?