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ụ cũ của Doconut có thể tạo Viewer trực tiếp với các đối số cache, HTTP-context và license-path. Đó 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 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ý dịch vụ và middleware, phát ra các tài nguyên trình xem nhúng, mở tài liệu bằng OpenDocumentAsync, trả về một token 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ụ session của 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 Doconut trong trình duyệt là một plugin jQuery. Trong một Razor page, tiêm Viewer và yêu cầu nó phát ra 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 server:

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 các tùy chọn là quan trọng. Sử dụng tên 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ý dưới dạng dịch vụ transient. Giải quyết nó thông qua injection endpoint, injection 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 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. Đừng biến tên tệp đã gửi thành đường dẫn trên server.

Gọi endpoint mở và đưa 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 đang hoạt động:

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 server 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 luồng công việc phía server 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 các tài liệu lớn. Hết hạn phiên vẫn là biện pháp dự phòng, không thay thế cho việc quản lý vòng đời ứng dụng một cách 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à các callback vòng đời 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 các mô-đun tùy chọn.

Các lỗi thường gặp khi di chuyển

Mẫu cũ hoặc không đúng	Hướng đi hiện tại của .NET 8
`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ụ đồng bộ `OpenDocument(...)`	Sử dụng `OpenDocumentAsync(...)`
CDN trình xem bên ngoài hoặc tự tạo	Phát ra 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 của 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 Doconut chính thức và xác minh 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ôi trường sản xuất.