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:

csharp
// 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.RegisterProvider là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 = false là mặc định, được viết ra để không ai vô tình thay đổi: DocImage.axd chỉ phục vụ một trang cho phiên ASP.NET đã mở tài liệu.
  • Hai lời gọi IgnoreRoute giữ routing MVC tránh xa DocImage.axd và /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.Shutdown dừ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ả khi Initialize chư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ó:

csharp
// 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ộ:

csharp
// 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:

csharp
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
@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 <%= %>:

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

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

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

javascript
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, onError và phần còn lại được đặt trong đối tượng truyền cho docViewer(...). 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 View riêng biệt. docViewer(...) trả về đối tượng với Zoom, Next và 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ới objViewer.Zoom is not a function khi 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:

csharp
// 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);
}
html
<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?