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 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. Khô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. Vì vậy một tham chiếu gói, tệp lock, hoặc .nupkg đã lưu không tự động xác định API đang dùng. Hãy 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, cách mở tài liệu, và các script trình duyệt cùng nhau.

Bản phát hành 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 ghim vào cùng phiên bản phát hành với gói lõi.

Trước khi di chuyển

1. Tạo một nhánh và sao lưu có thể triển khai của ứng dụng hiện có.
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à các bí mật triển khai ngoài hệ thống kiểm soát nguồn.
5. Thu thập một tập hợp đại diện 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 sản xuất. 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à cách cung cấp tài nguyên phía 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 một quá trình di chuyển có thể tái tạo tới bản phát hành đã đượ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 AddDoconut(), sử dụng thứ tự ưu tiên sau:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Khám phá tự động sẽ tìm các tệp Doconut.Viewer.lic và các tệp đồng hành Doconut.Viewer.<Capability>.lic. Một lời gọi cổ điển tới Viewer.DoconutLicense(...) hoặc Viewer.SetLicensePlugin(...) không còn 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 đồng hành cùng nhau khi dùng khám phá tự động, khởi động lại sau khi thay đổi giấy phép, và xác minh các khả năng qua IDoconutLicenseService.

Đừng cho rằng sự tồn tại của một giấy phép plugin cũ chứng minh quyền sử dụng cho một 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à dependency injection

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

// Tích hợp cổ điển — chỉ để đối chiếu; 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ừ dependency injection:

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

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

Viewer là một dịch vụ transient. Trình quản lý phiên tài liệu và bộ nhớ cache của nó sở hữu trạng thái tài liệu lâu dài 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 — xóa 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 sinh ra, và ResPath phía client đồng bộ;
4. khi ánh xạ UseDoconut() vào một nhánh, giữ nhánh đó và BasePath phí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 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 client sử dụng nhất quán.

Khởi tạo Viewer và vòng đời

Xóa các cache thuộc về ứng dụng của các đối tượng Viewer. Tiêm Viewer vào một endpoint, trang Razor, controller, hoặc dịch vụ scoped của ứng dụng:

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 server. 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 dữ liệu.

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, một cấu hình định dạng tùy chọn, DocOptions tùy chọn, và một cancellation token. Đóng phiên server một cách rõ ràng khi trình duyệt không còn cần nữa:

viewer.CloseDocument(token);

Đừ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:

Đừng mang DocOptions.ImageResolution sang phía trước như một điều khiển render. Nó đã lỗi thời; hãy đặt BaseConfig.ImageResolution trên cấu hình định dạng cụ thể. Xem lại mọi giá trị mặc định thay vì cho rằng cấu hình cổ điển có cùng hành vi.

Thanh công cụ Viewer, Search và Annotation

Đừ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 ghép một gói trang hoàn chỉnh:

1. phát ra CSS Viewer và CSS Search/Annotation có giấy phép bằng ReferenceCss;
2. render thanh công cụ Viewer thuộc sở hữu ứng dụng;
3. render searchBarMount, annBarMount, và mount Viewer bắt buộc;
4. phát ra script Viewer và module có giấy phép bằng ReferenceScripts;
5. tải script 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 host; các Ribbon Search và Annotation là tài nguyên được gắn cờ theo 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 thức license‑static 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 các khả năng plugin đã đăng ký khi khởi động. Converter và DICOM là các plugin .NET 6 đã phát hành. Search và Annotation thông thường là các tính năng có giấy phép tích hợp sẵn, không phải các gói AddPlugin<TPlugin>().

Phiên và bảo mật tài liệu

Tích hợp hiện tại gắn tài liệu với các token mờ và các phiên được cache. Với UnsafeMode = false mặc định, UseDoconut() thêm bảo mật truy cập tài liệu và host phải cấu hình session ASP.NET:

builder.Services.AddSession();
app.UseSession();

Giữ DocOptions.IsSecured = true trừ khi một thiết kế đã được xem xét yêu cầu ngược lại. Không bao giờ sử dụng UnsafeMode = true như một lối tắt di chuyển. Kiểm tra các yêu cầu không có token, token sai định dạ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 các ticket truy cập và chi tiết vận chuyển. Các API này không bắt buộc cho một quá trình di chuyển đơn node bình thường.

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

Ít nhất, xác minh:

• khởi động ứng dụng với giấy phép production và mọi plugin đã đăng ký;
• CSS/Script Viewer và tất cả các yêu cầu ảnh trang dưới các đường dẫn đã chọn;
• mở tài liệu, điều hướng, thu phóng, thumbnail, in, và đóng rõ ràng;
• Search 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ỉ ảnh;
• tải, lưu, xuất Annotation và kiểm soát khả năng;
• khám phá mục tiêu Converter, đầu ra, tải về, và trạng thái watermark;
• các trang, khung, và animation DICOM; metadata 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 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;
• mobile, chế độ tối, và đường dẫn reverse‑proxy production.

Kế hoạch rollback

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

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

• slot hoặc artefact triển khai được dùng cho rollback;
• ảnh hưởng tới database/cache, nếu có;
• cách các phiên tài liệu đang hoạt động sẽ bị vô hiệu hoá;
• health check và tài liệu smoke được dùng để quyết định rollback;
• người có thể khôi phục bộ gói và cấu hình trước đó.

Tài liệu cổ điển

Phiên bản cổ điển đã dịch vẫn khả dụng tại Hướng dẫn cài đặt .NET 6 cổ điển. Cổng Gateway tích hợp cổ điển 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 bookmark và ticket hỗ trợ trong khi các cài đặt cổ điển vẫn còn tồn tại. Nó mô tả một thế hệ khác và không được chuyển hướng tới API hiện tại.