Hai cách di chuyển xuất hiện trên trang này: nâng cấp phiên bản gói trong .NET 8, và di chuyển một tích hợp từ một framework Doconut cũ hơn (.NET 6, .NET Standard 2.0, .NET Framework 4.7) lên API .NET 8.

Nâng cấp phiên bản gói

Cập nhật gói (và bất kỳ gói plugin nào — giữ các phiên bản đồng nhất):

bash

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Dicom

Kiểm tra cửa sổ giấy phép. Một giấy phép bao phủ một dải phiên bản. Nếu phiên bản mới nằm ngoài phạm vi, việc mở sẽ bị chặn — OpenDocumentAsync ném LicenseException (fail-fast); nó không quay lại watermark, và IsVersionValid chuyển false. Gia hạn, thay thế .lic, và khởi động lại ứng dụng để AddDoconut() tải giấy phép mới.
Biên dịch lại và để NuGet khôi phục các phiên bản phụ thuộc đã khai báo — không gắn lại System.Text.Json hoặc System.Drawing.Common (xem phần Khắc phục sự cố để biết các lỗi chính xác khi hạ cấp).
Thực hiện kiểm thử nhanh một tài liệu cho mỗi họ định dạng bạn sử dụng.

Di chuyển từ .NET 6 / .NET Standard 2.0

API .NET 8 được thiết kế lại xoay quanh DI và async. Bảng ánh xạ:

Mối quan tâm	.NET 6 / Standard 2.0	.NET 8
Cài đặt	Khởi tạo `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + tiêm `Viewer`
Giấy phép	Tĩnh `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` cho mỗi plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — một giấy phép, tự động khám phá các tệp plugin
Mở	`viewer.OpenDocument(...)` (đồng bộ)	`await viewer.OpenDocumentAsync(...)`
Đóng	`viewer.CloseDocument()` hoặc `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` là không `IDisposable`
Thời gian tồn tại	`Viewer` thực thi `IDisposable`, giữ tài liệu đang mở	`Viewer` không có trạng thái; các phiên tồn tại trong bộ nhớ cache dưới các token
Converter	thuộc tính `viewer.Converter`	Plugin Converter (`AddPlugin<ConverterPlugin>()`) + dịch vụ `DocumentConverter`
Lớp cấu hình	không gian tên `Doconut.Configs.View.*`	Tất cả trong không gian tên `Doconut`
Middleware	Kết nối xử lý thủ công	`app.UseDoconutResources()` + `app.UseDoconut()`

Một ví dụ điển hình trước/sau:

text

// .NET 6 (API cũ, được hiển thị để so sánh — không hợp lệ trên .NET 8)
using var viewer = new Viewer(cache, httpContextAccessor, "wwwroot/Doconut.Viewer.lic");
var token = viewer.OpenDocument(path, new PdfConfig { AllowSearch = true }, new DocOptions());

csharp

// .NET 8 — Viewer được tiêm, giấy phép được cấu hình một lần trong AddDoconut()
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Di chuyển từ .NET Framework 4.7 (Web Forms)

Viewer 4.7 là một WebControl; .NET 8 thay thế mô hình điều khiển bằng middleware + một dịch vụ DI:

Điều khiển <doconut:DocViewer runat=server> biến mất — trang sẽ chứa cặp widget div và endpoint của bạn trả về token (Quick Start hiển thị mẫu).
Các phương thức giấy phép tĩnh → nguồn giấy phép DoconutOptions.
OpenDocument đồng bộ → await OpenDocumentAsync.
Viewer.ReferenceScripts() / ReferenceCss() tồn tại trong cả hai môi trường — các phiên bản .NET 8 nhận các đối tượng ScriptConfig/CssConfig và được kiểm soát bằng giấy phép.
Các thuộc tính điều khiển (ShowThumbs, PageZoom, FixedZoom, …) → cùng tên trên ViewerConfig / tùy chọn JS docViewer.
Các phương thức xuất trả về byte[] → các API xuất chú thích bất đồng bộ trên Viewer.

Lên kế hoạch cho phần này như một việc viết lại lớp hosting quanh một khái niệm không thay đổi: mở → token → widget.

Ghi chú về đặt tên

Trong tất cả các framework, lớp là Viewer — nếu bạn thấy DocumentViewer trong các đoạn mã cũ hoặc bài viết của bên thứ ba, kiểu đó chưa bao giờ tồn tại trong SDK.

Danh sách kiểm tra di chuyển

Thay đổi các gói; đồng bộ phiên bản gói plugin.
Di chuyển cấu hình giấy phép vào AddDoconut(); xóa các lời gọi giấy phép tĩnh.
Biến các lời gọi mở thành async; thay thế Dispose/CloseDocument không tham số bằng CloseDocument(token).
Thay thế việc sử dụng viewer.Converter bằng việc đăng ký plugin Converter + DocumentConverter.
Kiểm tra lại đường bảo mật: AddSession()/UseSession() hiện đã bắt buộc với bảo mật mặc định (cộng thêm AddDistributedMemoryCache() trong ứng dụng minimal-API).