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 từ thế hệ khác.

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 đã được lưu trong bộ nhớ đệm không xác định API lưu trữ một cách riêng lẻ. Ghi lại phiên bản gói chính xác và kiểm tra Program.cs, việc tạo Viewer, 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 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 có.
2. Ghi lại phiên bản gói lõi và plugin chính xác.
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 ngoài hệ thống kiểm soát nguồn.
5. Ghi lại 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 có, 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à việc cung cấp tài nguyên cho khách hàng.

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 cài đặt phiên bản ổn định mới nhất:

dotnet add package Doconut.NET6

Để có một quá trình 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 như một 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 này:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Quá trình khám phá tự động tìm kiế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 tới DoconutOptions, giữ các tệp đi kèm cùng nhau khi sử 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 giả định 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 truyền thống tạo Viewer với bộ nhớ đệm ASP.NET và các phụ thuộc request-accessor:

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

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ụ 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 tồn tại 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 truyền thống phát hiện DocImage.axd:

// Classic integration — remove during the cutover.
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 một cách 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 cho 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(...):

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
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 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 truyền thống sau khi chuyển đổi. Mở lại mỗi tài liệu thông 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 tiếp tục sử dụng DocOptions.ImageResolution làm điều khiển kết xuất. Nó đã lỗi thời; hãy đặt BaseConfig.ImageResolution trên cấu hình riêng cho định dạng. Xem xét tất cả các mặc định thay vì giả định một cấu hình truyền thống có cùng hành vi.

Thanh công cụ Viewer, Tìm kiếm và Ghi 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 Search/Annotation có giấy phép bằng ReferenceCss;
2. kết xuất thanh công cụ Viewer do ứng dụng sở hữu;
3. kết xuất searchBarMount, annBarMount, và phần gắn Viewer yêu cầu;
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 được 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 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. 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 ràng buộc tài liệu với các token mờ và các phiên được lưu trong bộ nhớ đệm. Với UnsafeMode = false mặc định, 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.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 duyệt khác.

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

Kiểm tra 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/đoạn script của Viewer và tất cả các yêu cầu hình ảnh trang theo các đường dẫn đã chọn;
• mở tài liệu, điều hướng, thu phóng, hình thu nhỏ, in ấn, và đóng một cách rõ ràng;
• Tìm kiếm trên tài liệu có chứa 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, khung và hoạt ảnh DICOM; 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 khi phiên hết hạn;
• di động, chế độ tối, và đường dẫn reverse-proxy sản xuất.

Kế hoạch phục hồi

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 việc phục hồi an toàn sẽ chuyển 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 cắt chuyển, tài liệu:

• khe triển khai hoặc artefact được sử dụng cho việc phục hồ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 smoke được dùng để quyết định phục hồi;
• người 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ó sẵn tại Hướng dẫn cài đặt Legacy .NET 6. Gateway tích hợp Classic mới giải thích các tín hiệu nhận dạng tương tự và liên kết lại với hướng dẫn di chuyển này.

Giữ URL lịch sử trong dấu trang và các ticket hỗ trợ trong khi các cài đặt cổ điển vẫn cò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.