Hướng dẫn: Mở tài liệu với Trình xem Doconut được tiêm trong .NET 8

Giới thiệu

Các ví dụ Doconut cũ có thể tạo Viewer trực tiếp với các đối số cache, HTTP-context và license-path. Điều đó không phải là mô hình tích hợp .NET 8 hiện tại. AddDoconut() đăng ký Viewer với dependency injection, và các endpoint của ứng dụng nhận dịch vụ thay vì gọi constructor.

Các thành phần máy chủ trừu tượng truyền một token phiên không trong suốt tới bề mặt xem tài liệu

Bài hướng dẫn này tuân theo luồng yêu cầu hiện tại: đăng ký các dịch vụ và middleware, phát các tài nguyên trình xem nhúng, mở tài liệu bằng OpenDocumentAsync, trả về một token phiên không trong suốt, và truyền token đó tới widget trình duyệt.

1. Cài đặt và đăng ký Doconut

Thêm gói .NET 8:

dotnet add package Doconut.NET8

Đăng ký Doconut và các dịch vụ phiên ASP.NET:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});

builder.Services.AddSession();

Kết nối middleware theo thứ tự yêu cầu. Middleware tài nguyên phải chạy trước middleware tài liệu cuối cùng:

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath điều phối cấu hình nhưng không tự tạo nhánh ASP.NET. Đường dẫn /doconut đã được ánh xạ phải khớp với BasePath của widget.

2. Thêm bề mặt trình xem và tài nguyên

Trình xem trình duyệt Doconut là một plugin jQuery. Trong một trang Razor, tiêm Viewer và yêu cầu nó phát các thẻ tài nguyên theo thứ tự phụ thuộc:

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery = true,
    IncludeViewerScripts = true
}))

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

Khởi tạo widget với các đường dẫn khớp với đăng ký trên máy chủ:

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    pageZoom: 100,
    FitType: 'width',
    BasePath: '/doconut',
    ResPath: '/doconut-res/images',
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Việc viết hoa chữ cái trong các tùy chọn là quan trọng. Sử dụng các tên được hiển thị bởi phiên bản đã cài đặt thay vì chuẩn hoá chúng thành một kiểu duy nhất.

3. Tiêm Viewer và mở tài liệu

Viewer được đăng ký như một dịch vụ transient. Giải quyết nó thông qua tiêm endpoint, tiêm constructor, hoặc cơ chế tương đương trong ứng dụng ASP.NET Core của bạn.

app.MapPost("/api/open", async (
    Viewer viewer,
    CancellationToken ct) =>
{
    string token = await viewer.OpenDocumentAsync(
        "wwwroot/files/Sample.pdf",
        ct: ct);

    return Results.Ok(new { token });
});

Đối với việc tải lên, cung cấp một stream và một FileInfo mà phần mở rộng xác định định dạng nguồn:

app.MapPost("/api/open-upload", async (
    IFormFile file,
    Viewer viewer,
    CancellationToken ct) =>
{
    await using var stream = file.OpenReadStream();
    string token = await viewer.OpenDocumentAsync(
        stream,
        new FileInfo(file.FileName),
        ct: ct);

    return Results.Ok(new { token });
});

Xác thực kích thước tải lên, phần mở rộng và quyền truy cập trước khi mở nội dung do người dùng cung cấp. Không chuyển tên tệp đã gửi thành đường dẫn máy chủ.

Lấy endpoint mở và chuyển token trả về cho objViewer.View:

fetch('/api/open', { method: 'POST' })
    .then(response => {
        if (!response.ok) throw new Error('The document could not be opened.');
        return response.json();
    })
    .then(data => objViewer.View(data.token))
    .catch(error => console.error(error));

Xem token như một chứng chỉ bearer cho một phiên tài liệu trực tiếp:

Không ghi log hoặc lưu trữ nó.
Chỉ trả về cho client được ủy quyền.
Không để lộ đường dẫn tệp nguồn.
Mở lại tài liệu khi phiên hết hạn.
Đóng phiên khi tài liệu không còn cần thiết.

5. Đóng các phiên phía máy chủ một cách có chủ đích

Mã client có thể gọi objViewer.Close() khi người dùng rời khỏi trình xem. Các quy trình máy chủ cũng có thể thu hồi một token đã biết một cách rõ ràng:

app.MapPost("/api/close", (string token, Viewer viewer) =>
{
    viewer.CloseDocument(token);
    return Results.NoContent();
});

Việc đóng rõ ràng đặc biệt hữu ích cho tài liệu lớn. Hết hạn phiên vẫn là phương án dự phòng, không phải thay thế cho việc quản lý vòng đời ứng dụng dự đoán được.

6. Thêm các mô-đun tùy chọn chỉ sau khi phần lõi hoạt động

Tìm kiếm và chú thích gắn vào cùng một viewer đã được khởi tạo. Thêm CSS, script, mount, kiểm tra giấy phép và callbacks vòng đời của chúng chỉ sau khi luồng cơ bản thành công:

AddDoconut + session services
    -> UseSession
    -> UseDoconutResources
    -> mapped UseDoconut branch
    -> viewer resources and mount
    -> initialize docViewer
    -> OpenDocumentAsync
    -> objViewer.View(token)

Thứ tự này giữ cho các lỗi render lõi tách biệt khỏi cấu hình mô-đun tùy chọn.

Những lỗi thường gặp khi di chuyển

Mẫu cũ hoặc không đúng	Hướng .NET 8 hiện tại
`new Viewer(cache, accessor, licensePath)`	Tiêm `Viewer` sau `AddDoconut()`
Các lời gọi tải giấy phép tĩnh trong mã yêu cầu	Cấu hình đầu vào giấy phép trong `AddDoconut()`
Các ví dụ `OpenDocument(...)` đồng bộ	Sử dụng `OpenDocumentAsync(...)`
Một CDN trình xem bên ngoài hoặc tự tạo	Phát tài nguyên nhúng bằng `ReferenceCss` và `ReferenceScripts`
API JavaScript chung `init()`	Khởi tạo `$('#div_ctlDoc').docViewer(...)`
Lưu trữ token trình xem	Lưu trữ ID tài liệu của bạn; xem token như tạm thời

Sử dụng tài liệu chính thức của tài liệu Doconut và kiểm tra các ví dụ với phiên bản gói đã cài đặt trước khi áp dụng chúng vào mã sản xuất.