Có hai loại di chuyể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 khung 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 phạm vi 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 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 xoay quanh DI và bất đồng bộ. Bảng ánh xạ:

Mối quan tâm	.NET 6 / Standard 2.0	.NET 8
Setup	Khởi tạo `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + inject `Viewer`
License	Tĩnh `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` per plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — one license, auto-discovery for plugin files
Open	`viewer.OpenDocument(...)` (đồng bộ)	`await viewer.OpenDocumentAsync(...)`
Close	`viewer.CloseDocument()` hoặc `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` is not `IDisposable`
Lifetime	`Viewer` triển khai `IDisposable`, giữ tài liệu đang mở	`Viewer` là không trạng thái; các phiên làm việc 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`
Config classes	Không gian tên `Doconut.Configs.View.*`	Tất cả trong không gian tên `Doconut`
Middleware	Kết nối thủ công các handler	`app.UseDoconutResources()` + `app.UseDoconut()`

Một ví dụ điển hình trước/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 4.7 là một WebControl; .NET 8 thay thế mô hình điều khiển bằng middleware + dịch vụ DI:

Control <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[] → API xuất chú thích bất đồng bộ trên Viewer.

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 khung, 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 bất đồng bộ; 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 được yêu cầu với bảo mật mặc định.