Di chuyển từ tích hợp .NET 6 cổ điển

Doconut có hai tích hợp .NET 6 riêng biệt. Chúng có thể sử dụng cùng một tên gói Doconut.NET6, vì vậy hãy xác định thế hệ từ các API trong ứng dụng trước khi thay đổi gói, khởi động, giấy phép hoặc tài nguyên trình duyệt.

Bạn đang sử dụng tích hợp .NET 6 nào?

Nếu cả hai cột xuất hiện trong cùng một ứng dụng, coi việc di chuyển là chưa hoàn chỉnh. Đừng gửi một token tài liệu qua tài nguyên hoặc middleware của thế hệ còn lại.

Tại sao tên gói NuGet có thể không cho bạn biết

Cả hai thế hệ đều được phát hành dưới ID gói Doconut.NET6. Do đó, một tham chiếu gói, tệp lock, hoặc .nupkg đã lưu trong bộ nhớ đệm không xác định được API đang sử dụng. Ghi lại phiên bản gói chính xác và kiểm tra Program.cs, cách khởi tạo viewer, mở tài liệu và các script trình duyệt cùng nhau.

Phiên bản hiện tại được kiểm toán cho hướng dẫn này là Doconut.NET6 26.7.0. Các gói công cộng tùy chọn của nó là Doconut.NET6.Converter và Doconut.NET6.Dicom, được cố định ở cùng phiên bản phát hành với gói lõi.

Trước khi bạn di chuyển

1. Tạo một nhánh và bản sao lưu có thể triển khai của ứng dụng hiện tại.
2. Ghi lại phiên bản chính xác của gói lõi và các plugin.
3. Kiểm kê mọi ánh xạ DocImage.axd, lời gọi new Viewer(...), lời gọi tải giấy phép, script Doconut đã sao chép, hành động thanh công cụ tùy chỉnh và endpoint mở tài liệu.
4. Bảo quản các tệp .lic hiện tại và bí mật triển khai bên ngoài hệ thống kiểm soát mã nguồn.
5. Thu thập một tập hợp đại diện gồm các tài liệu PDF, Office, hình ảnh, CAD, email, DICOM, có thể tìm kiếm, được bảo vệ bằng mật khẩu và có chú thích.
6. Ghi lại thời gian chờ phiên hiện tại, hành vi bảo mật, phông chữ và cài đặt nền tảng.

Di chuyển một môi trường trước khi thay đổi môi trường production. Tích hợp hiện tại thay đổi vòng đời dịch vụ, định tuyến yêu cầu, quyền sở hữu phiên và việc cung cấp tài nguyên cho client.

Tương thích gói và giấy phép

Thay thế hoặc cập nhật gói lõi một cách có chủ đích; không dựa vào ID gói giống nhau để chọn API mới. Lệnh mặc định sẽ cài đặt phiên bản ổn định mới nhất:

dotnet add package Doconut.NET6

Để thực hiện di chuyển có thể tái tạo tới phiên bản được kiểm toán trong hướng dẫn này, truyền phiên bản dưới dạng tùy chọn riêng:

dotnet add package Doconut.NET6 --version 26.7.0

Giữ mọi plugin Doconut ở cùng phiên bản với gói lõi. Tích hợp hiện tại tải giấy phép một lần trong quá trình AddDoconut(), sử dụng thứ tự ưu tiên sau:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Quá trình tự động sẽ tìm các tệp Doconut.Viewer.lic và các tệp đi kèm Doconut.Viewer.<Capability>.lic. Một lời gọi cổ điển tới Viewer.DoconutLicense(...) hoặc Viewer.SetLicensePlugin(...) không phải là cơ chế khởi động hiện tại. Di chuyển giấy phép vào DoconutOptions, giữ các tệp đi kèm cùng nhau khi sử dụng tự động phát hiện, khởi động lại sau khi thay đổi giấy phép, và xác minh các khả năng thông qua IDoconutLicenseService.

Đừng cho rằng sự tồn tại của giấy phép plugin cũ chứng minh quyền sử dụng cho bản dựng plugin hiện tại. Kiểm tra Viewer, Search, Annotation, Converter và DICOM riêng biệt với các artefact phát hành đã được phê duyệt.

Khởi động và tiêm phụ thuộc

Các ứng dụng cổ điển tạo Viewer với bộ nhớ đệm ASP.NET và các phụ thuộc request‑accessor:

// Tích hợp cổ điển — chỉ để so sánh; không biên dịch đoạn này với SDK hiện tại.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

Tích hợp hiện tại đăng ký Doconut một lần và nhận Viewer từ tiêm phụ thuộc:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer là một dịch vụ tạm thời. Trình quản lý phiên tài liệu và bộ nhớ đệm của nó sở hữu trạng thái tài liệu lâu hơn, không phải thể hiện Viewer được tiêm cụ thể.

Middleware và định tuyến tài nguyên

Xóa nhánh MapWhen cổ điển phát hiện DocImage.axd:

// Tích hợp cổ điển — loại bỏ trong quá trình chuyển đổi.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

Trong pipeline hiện tại:

1. gọi UseSession() trước Doconut khi bảo mật phiên được bật;
2. gọi UseDoconutResources() trước UseDoconut();
3. giữ ResourcesPath, các URL tài nguyên được tạo, và ResPath của client đồng bộ;
4. khi ánh xạ UseDoconut() tới một nhánh, giữ nhánh đó và BasePath của client đồng bộ.

MiddlewarePath là cấu hình đã được xác thực; nó không tự tạo một nhánh ASP.NET Core. Sử dụng hoặc pipeline đơn giản trong mẫu biên dịch ở trên hoặc một cấu hình rõ ràng app.Map("/doconut", branch => branch.UseDoconut()) được khách hàng sử dụng nhất quán.

Xây dựng và vòng đời Viewer

Xóa các bộ nhớ đệm do ứng dụng sở hữu của các đối tượng Viewer. Tiêm Viewer vào một endpoint, trang Razor, controller, hoặc dịch vụ ứng dụng có phạm vi:

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Token trả về xác định một phiên tài liệu phía máy chủ. Xử lý nó như một chứng chỉ bearer: không ghi log, không lưu trữ, và không đưa vào phân tích.

Mở và đóng tài liệu

Thay thế OpenDocument(...) đồng bộ bằng OpenDocumentAsync(...):

// Tích hợp .NET 6 hiện tại: Viewer được lấy từ DI và việc mở tài liệu là bất đồng bộ.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Các overload hiện tại chấp nhận đường dẫn tệp hoặc stream, cấu hình định dạng tùy chọn, DocOptions tùy chọn, và token hủy. Đóng phiên máy chủ một cách rõ ràng khi trình duyệt không còn cần nữa:

viewer.CloseDocument(token);

Không tái sử dụng token cổ điển sau khi chuyển đổi. Mở lại mỗi tài liệu qua API hiện tại.

Các lớp cấu hình

API hiện tại tách biệt các mối quan tâm:

Không mang DocOptions.ImageResolution tiếp tục như điều khiển render. Nó đã lỗi thời; đặt BaseConfig.ImageResolution trên cấu hình riêng của định dạng. Xem lại tất cả các mặc định thay vì giả định một cấu hình cổ điển có cùng hành vi.

Thanh công cụ Viewer, Tìm kiếm và Chú thích

Không di chuyển các script cũ từng cái một. Các ứng dụng tham chiếu hiện tại tạo thành một gói trang hoàn chỉnh:

1. phát ra CSS của Viewer và CSS có giấy phép cho Search/Annotation bằng ReferenceCss;
2. kết xuất thanh công cụ Viewer thuộc ứng dụng;
3. kết xuất searchBarMount, annBarMount, và phần mount Viewer cần thiết;
4. phát ra script Viewer và các module có giấy phép bằng ReferenceScripts;
5. tải viewerToolbar.js của ứng dụng;
6. khởi tạo một objViewer;
7. khởi tạo các Ribbon Search và Annotation có giấy phép;
8. gọi attach(objViewer) trên mỗi Ribbon;
9. mở tài liệu và gọi objViewer.View(token).

Search và Annotation là các module gắn vào cùng một Viewer, không phải các thanh công cụ độc lập. Thanh công cụ chính thuộc về ứng dụng chủ; các Ribbon Search và Annotation được nhúng, là các tài nguyên có giới hạn khả năng.

Xóa các tệp cổ điển được sao chép thủ công như documentLinks.js và docViewer.UI.js chỉ sau khi trang hiện tại hoạt động với các tài nguyên được phát ra bởi ReferenceCss và ReferenceScripts.

Đăng ký plugin

Các phương pháp cấp phép plugin tĩnh cổ điển không đăng ký các plugin hiện tại. Cài đặt và đăng ký từng gói đã phát hành một cách rõ ràng:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() xác thực khả năng của các plugin đã đăng ký khi khởi động. Converter và DICOM là các plugin .NET 6 đã phát hành. Tìm kiếm bình thường và Ghi chú là các tính năng có giấy phép tích hợp, không phải các gói AddPlugin<TPlugin>().

Bảo mật phiên và tài liệu

Việc tích hợp hiện tại gắn tài liệu với các token không trong suốt và các phiên được lưu trong bộ nhớ đệm. Với mặc định UnsafeMode = false, UseDoconut() thêm bảo mật truy cập tài liệu và máy chủ phải cấu hình phiên ASP.NET:

builder.Services.AddDistributedMemoryCache(); // trạng thái phiên cần một bộ nhớ đệm (MVC/Razor Pages đã thêm sẵn)
builder.Services.AddSession();
app.UseSession();

Giữ DocOptions.IsSecured = true trừ khi thiết kế đã xem xét yêu cầu ngược lại. Không bao giờ sử dụng UnsafeMode = true như một cách tắt gọn cho việc di chuyển. Kiểm tra các yêu cầu không có token, token bị hỏng, token đã hết hạn, và token từ một phiên trình duyệt khác.

Ứng dụng tham chiếu Distributed thêm vé truy cập và chi tiết truyền tải. Các API đó không bắt buộc đối với việc di chuyển đơn nút bình thường.

Kiểm thử quá trình di chuyển

Ít nhất, hãy xác minh:

• khởi động ứng dụng với giấy phép sản xuất và mọi plugin đã đăng ký;
• CSS/script của Viewer và tất cả các yêu cầu trang‑hình ảnh dưới các đường dẫn đã chọn;
• mở tài liệu, điều hướng, phóng to/thu nhỏ, hình thu nhỏ, in và đóng rõ ràng;
• Tìm kiếm trên tài liệu có văn bản và trạng thái không thể tìm kiếm của tệp chỉ có hình ảnh;
• Tải, lưu, xuất Ghi chú và kiểm soát khả năng;
• Khám phá mục tiêu Converter, đầu ra, tải xuống và trạng thái watermark;
• Các trang DICOM, khung và hoạt ảnh; siêu dữ liệu kỹ thuật .NET 6 không khả dụng;
• tài liệu được bảo vệ bằng mật khẩu, phông chữ tùy chỉnh, văn bản không phải Latin, và thời gian chờ đã cấu hình;
• từ chối token giữa các phiên và hành vi phiên đã hết hạn;
• điện thoại di động, chế độ tối, và đường dẫn reverse‑proxy sản xuất.

Kế hoạch quay lại

Giữ nguyên các artefact triển khai cổ điển, các gói tương ứng, tệp giấy phép và tài nguyên trình duyệt đã sao chép cùng nhau. Một quá trình quay lại an toàn sẽ chuyển đổi toàn bộ thế hệ ứng dụng; nó không trộn một máy chủ cổ điển với các script hiện tại hoặc một máy chủ hiện tại với các cuộc gọi DocImage.axd cổ điển.

Trước khi chuyển đổi, hãy ghi lại:

• khe triển khai hoặc artefact được sử dụng cho việc quay lại;
• tác động đến cơ sở dữ liệu/bộ nhớ đệm, nếu có;
• cách các phiên tài liệu đang hoạt động sẽ bị vô hiệu hoá;
• kiểm tra sức khỏe và tài liệu kiểm tra nhanh được dùng để quyết định quay lại;
• ai có thể khôi phục bộ gói và cấu hình trước đó.

Tài liệu kế thừa

Hướng dẫn cổ điển đã được dịch vẫn còn sẵn tại Cài đặt .NET 6 Kế thừa. Cổng tích hợp Cổ điển mới giải thích các tín hiệu nhận dạng tương tự và liên kết trở lại hướng dẫn di chuyển này.

Giữ URL lịch sử trong dấu trang và phiếu hỗ trợ trong khi các cài đặt cổ điển vẫn tồn tại. Nó ghi lại một thế hệ khác và không được chuyển hướng tới API hiện tại.