Có hai loại di chuyển được trình bày 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 bộ):

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 dải này, việc mở sẽ bị chặn — OpenDocumentAsync ném LicenseException (fail-fast); nó không quay lại watermark, và IsVersionValid sẽ trả về false. Gia hạn, thay thế file .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 tra 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 quanh DI và async. Bảng ánh xạ:

Yếu tố	.NET 6 / Standard 2.0	.NET 8
Cài đặt	Construct `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + inject `Viewer`
Giấy phép	Static `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` per plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — one license, auto-discovery for plugin files
Mở	`viewer.OpenDocument(...)` (synchronous)	`await viewer.OpenDocumentAsync(...)`
Đóng	`viewer.CloseDocument()` or `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` is not `IDisposable`
Vòng đời	`Viewer` implements `IDisposable`, holds the open document	`Viewer` is stateless; sessions live in the cache under tokens
Bộ chuyển đổi	`viewer.Converter` property	The Converter plugin (`AddPlugin<ConverterPlugin>()`) + the `DocumentConverter` service
Lớp cấu hình	`Doconut.Configs.View.*` namespaces	All in the `Doconut` namespace
Middleware	Manual handler wiring	`app.UseDoconutResources()` + `app.UseDoconut()`

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

text

// .NET 6 (old API, shown for contrast — not valid on .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 injected, license configured once in AddDoconut()
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

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

Viewer phiên bản 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 div widget và endpoint của bạn trả về token (Quick Start minh họa 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 / các 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.

Hãy lên kế hoạch 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.