Bắt đầu nhanh
Hiển thị tài liệu đầu tiên của bạn trong MVC 5 hoặc Web Forms
Hướng dẫn này đưa một ứng dụng ASP.NET trên .NET Framework 4.7.2 từ gói đã cài đặt đến một tài liệu được hiển thị trong trình duyệt: Global.asax, một điểm cuối mở, các tài nguyên của trình xem, widget, và token kết nối chúng. Nó giả định các đăng ký Web.config từ Cài đặt đã có sẵn — nếu không có trình xử lý DocImage.axd và mô-đun tài nguyên, không có gì ở dưới có thể tiếp cận máy chủ.
Soạn Doconut trong Global.asax
Một Application_Start đầy đủ cho một ứng dụng MVC 5:
// Global.asax.cs - tạo một lần cho mỗi tiến trình worker, giải phóng khi tắt.
protected void Application_Start()
{
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.UnsafeMode = false; // một trang chỉ được phục vụ cho phiên đã mở tài liệu
});
// Chỉ MVC: giữ hai endpoint Doconut khỏi routing.
RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}
protected void Application_End()
{
Doconut.DoconutHost.Shutdown();
}Encoding.RegisterProviderlàm cho các trang mã legacy mà một số định dạng tài liệu sử dụng có sẵn cho quá trình. Gọi nó một lần, trước khi tài liệu đầu tiên được mở.UnsafeMode = falselà mặc định, được viết ra để không ai vô tình thay đổi:DocImage.axdchỉ phục vụ một trang cho phiên ASP.NET đã mở tài liệu.- Hai lời gọi
IgnoreRoutegiữ routing MVC tránh xaDocImage.axdvà/doconut-res/*, mà trình xử lý và mô-đun phục vụ. Ứng dụng Web Forms không có route MVC và không cần dòng này. DoconutHost.Shutdowndừng công việc nền của Doconut và giải phóng các dịch vụ của nó khi pool ứng dụng được tái tạo. Có thể gọi an toàn ngay cả khiInitializechưa bao giờ chạy.
Mở một tài liệu
Mở một tài liệu sẽ trả về một token không trong suốt. Widget gửi token đó cùng với mỗi yêu cầu trang.
Trong MVC 5, một hành động controller giải quyết dịch vụ Viewer từ DoconutHost.Services — MVC 5 không có tiêm constructor cho nó:
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
// Token là không trong suốt - chuyển nó cho viewer, không bao giờ ghi log hoặc lưu trữ nó.
string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
return Json(new { token });
}Tài liệu phải được mở trong một yêu cầu có trạng thái session, vì việc mở nó là cách cấp quyền truy cập các trang cho phiên ASP.NET hiện tại. Các controller MVC và trang Web Forms mặc định có trạng thái session. Một IHttpHandler tùy chỉnh không có, trừ khi nó triển khai System.Web.SessionState.IRequiresSessionState. Mở một tài liệu từ một trình xử lý mà không có nó, và trình xem sẽ hiển thị "Bạn không được phép xem trang này." trên mỗi trang.
Trong Web Forms, trang tự nó có thể mở tài liệu trong code-behind. OpenDocument là dạng đồng bộ của OpenDocumentAsync, dành cho code-behind không sử dụng các trang bất đồng bộ:
// 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"));
}Xử lý token như một chứng chỉ bearer: không bao giờ ghi log hoặc lưu trữ nó; chỉ chuyển nó cho widget. Nó sẽ ngừng hoạt động khi phiên tài liệu hết hạn — mở lại tài liệu để nhận token mới.
Tham chiếu các tài sản của trình xem
Viewer.ReferenceCss và Viewer.ReferenceScripts phát ra các thẻ <link> và <script> cho các tài sản nhúng, theo thứ tự phụ thuộc, trỏ tới /doconut-res/. Widget là một plugin jQuery, vì vậy jQuery được đưa lên trước.
MVC 5. Các view không có @inject, vì vậy tạo các thẻ trong controller và truyền chúng qua 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)Giữ công việc đó trong controller. MVC 5 biên dịch các view khi chúng được phục vụ lần đầu, và nếu không có gói biên dịch bổ sung, trình biên dịch đó chỉ hiểu C# 5 — không có ?., không có $"...", không có nameof. Một view sử dụng chúng sẽ biên dịch sạch sẽ trong Visual Studio, sau đó trả về một 500 trống trong trình duyệt.
Web Forms. Tiết lộ các chuỗi giống nhau từ code-behind và ghi chúng bằng <%= %>:
<head>
<%= ViewerCss %>
</head>
<body>
...
<%= ViewerScripts %>
</body>IncludeViewerCss và IncludeViewerScripts là phần cốt lõi bắt buộc. Để thêm các ribbon Tìm kiếm và Ghi chú, cũng đặt IncludeSearchCss, IncludeAnnotationCss, IncludeSearchScripts, IncludeSearchBar, IncludeAnnotationScripts và IncludeAnnotationBar. Cả hai phương pháp đều bỏ qua các tệp của một ribbon khi giấy phép không cho phép tính năng đó; trình xem vẫn khởi động.
Thêm trình xem vào một trang
Bề mặt render là hai div lồng nhau:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Đặt cho div bên ngoài một chiều cao thực — trình xem sẽ lấp đầy container của nó và đo kích thước khi khởi động. Trình xem không tự vẽ thanh công cụ của mình: GotoPage, Next, Zoom, FitType và phần còn lại là các phương thức mà trang của bạn gắn vào các nút của mình, đặt bên cạnh trình xem:
<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>Khởi tạo trình xem và hiển thị tài liệu
Sau các script của trình xem, tạo widget, sau đó truyền cho nó token:
var objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: '/', // '/' có nghĩa là DocImage.axd tại gốc site
ResPath: 'doconut-res/images', // không có '/' ở đầu
onViewerReady: function () {
// các trang đã hiển thị; ẩn chỉ báo tải ở đây
},
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); });Trong Web Forms, nơi trang mở tài liệu trực tiếp, ba dòng cuối cùng trở thành objViewer.View('<%= Token %>');.
Bốn chi tiết ở đây sẽ thất bại mà không có thông báo lỗi:
BasePath: '/'địa chỉDocImage.axdở gốc site. Đối với một ứng dụng trong thư mục ảo, sử dụng tên của nó mà không có dấu gạch chéo ('myapp'yêu cầu/myapp/DocImage.axd). Một dấu gạch chéo đầu tiên ('/myapp') tạo ra//myapp/DocImage.axd, mà trình duyệt đọc như một yêu cầu tới máy chủ khác.ResPath: 'doconut-res/images'— các biểu tượng nằm một thư mục dưới gốc tài nguyên. Với'doconut-res', mọi biểu tượng trả về 404: không có glyph thanh công cụ và không có vòng quay tải, trong khi tài liệu vẫn được render. Một dấu gạch chéo đầu tiên phá vỡ nó theo cùng cách nhưBasePath.- Callbacks là các tùy chọn.
onViewerReady,onErrorvà phần còn lại được đặt trong đối tượng truyền chodocViewer(...). Một hàm toàn cục có tên giống với trình xem, nhưctlDoc_ViewerReady, sẽ không bao giờ được gọi. - Giữ lại trình xem, sau đó gọi
Viewriêng biệt.docViewer(...)trả về đối tượng vớiZoom,NextvàFitType;View(...)trả về một thứ khác.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)render tài liệu, sau đó thất bại vớiobjViewer.Zoom is not a functionkhi nhấn thanh công cụ đầu tiên.
Tên tùy chọn hỗn hợp camelCase (showThumbs, autoLoad, pageZoom) và PascalCase (FitType, BasePath, ResPath). Một tùy chọn bị viết sai sẽ bị bỏ qua, và widget sẽ sử dụng mặc định.
Giải pháp một dòng
Đối với một trang chỉ cần hiển thị tài liệu, không có thanh công cụ riêng, Viewer.RenderViewer viết toàn bộ script khởi tạo — docViewer(...) với BasePath: '/' và ResPath: 'doconut-res/images', sau đó .View(token). Nó chỉ tồn tại trong gói này:
// 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 %>Cung cấp một ViewerConfig làm đối số thứ ba để thay đổi mức thu phóng, cách hiển thị vừa vặn, hoặc bảng thu nhỏ. Vì script được tạo không giữ bất kỳ tham chiếu nào đến trình xem, hãy sử dụng đoạn khởi tạo viết tay ở trên khi trang của bạn cần thanh công cụ riêng.
Đóng tài liệu
Gọi objViewer.Close(true) khi người dùng rời khỏi trình xem hoặc mở một trình xem thay thế: nó sẽ xóa widget và gửi yêu cầu đóng tới DocImage.axd. objViewer.Close() không có đối số sẽ chỉ xóa widget. Trên máy chủ, viewer.CloseDocument(token) loại bỏ phiên tài liệu ngay lập tức, giải phóng tài nguyên render và rút quyền truy cập của phiên vào các trang của nó. Thời gian hết hạn trượt cuối cùng cũng làm điều tương tự, nhưng việc đóng các tài liệu lớn một cách rõ ràng sẽ giải phóng bộ nhớ sớm hơn.
Chạy nó
Đặt một tệp PDF tại ~/files/Sample.pdf, khởi động site trong IIS Express (F5 trong Visual Studio), và mở trang chứa widget. Trang đầu tiên sẽ được render, với các hình thu nhỏ ở phía bên trái. Nếu không, xem Khắc phục sự cố.
Những gì bạn nhận được khi không có giấy phép
Thiếu giấy phép không gây lỗi. Trình xem vẫn render bình thường, nhưng mỗi trang đều có dấu watermark đánh giá. Xem Cài đặt giấy phép để biết Doconut tìm giấy phép của bạn ở đâu.
Trang này có hữu ích không?