本页包含两种迁移：在 .NET 8 中 升级包版本，以及 将旧的 Doconut 框架（.NET 6、.NET Standard 2.0、.NET Framework 4.7）上的集成迁移到 .NET 8 API。

升级包版本

更新包（以及任何插件包——保持版本一致）：

bash

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

检查许可证窗口。 许可证覆盖一个版本范围。如果新版本超出该范围，打开操作会被阻止——OpenDocumentAsync 会抛出 LicenseException（快速失败）；它不会回退为水印，且 IsVersionValid 会返回 false。请续订许可证，替换 .lic 文件，并重新启动应用程序，使 AddDoconut() 加载新的许可证。
重新构建并让 NuGet 恢复声明的依赖版本——不要重新固定 System.Text.Json 或 System.Drawing.Common（有关降级导致的具体错误，请参阅故障排除）。
对您使用的每种格式族进行一次冒烟测试。

从 .NET 6 / .NET Standard 2.0 迁移

.NET 8 API 围绕依赖注入和异步重新设计。对应关系如下：

关注点	.NET 6 / Standard 2.0	.NET 8
设置	构造 `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + 注入 `Viewer`
许可证	静态 `Viewer.DoconutLicense(path)` + 对每个插件调用 `SetLicensePlugin(...)`	`options.LicensePath` / `LicenseContent` / `LicenseStream` — 单一许可证，插件文件自动发现
打开	`viewer.OpenDocument(...)`（同步）	`await viewer.OpenDocumentAsync(...)`
关闭	`viewer.CloseDocument()` or `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` 不是 `IDisposable`
生命周期	`Viewer` 实现 `IDisposable`，并持有打开的文档	`Viewer` 是无状态的；会话存放在基于 token 的缓存中
转换器	`viewer.Converter` 属性	Converter 插件 (`AddPlugin<ConverterPlugin>()`) + `DocumentConverter` 服务
配置类	`Doconut.Configs.View.*` 命名空间	全部位于 `Doconut` 命名空间中
中间件	手动处理程序绑定	`app.UseDoconutResources()` + `app.UseDoconut()`

一个典型的前后对比：

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 });

从 .NET Framework 4.7（Web Forms）迁移

.NET 4.7 的 Viewer 是一个 WebControl；.NET 8 用中间件 + DI 服务取代了控件模型：

<doconut:DocViewer runat=server> 控件消失——页面只保留 widget 的 div 对，并且您的端点返回 token（快速入门展示了该模式）。
静态许可证方法 → DoconutOptions 许可证来源。
同步的 OpenDocument → await OpenDocumentAsync。
Viewer.ReferenceScripts() / ReferenceCss() 在两个版本中都存在——.NET 8 版本接受 ScriptConfig/CssConfig 对象，并受许可证限制。
控件属性（ShowThumbs、PageZoom、FixedZoom，……）→ 在 ViewerConfig 或 docViewer JS 选项中使用相同的名称。
返回 byte[] 的导出方法 → Viewer 上的异步注释导出 API。

将此迁移视为对宿主层的重写，概念保持不变：打开 → token → widget。

命名说明

在所有框架中，类名都是 Viewer —— 如果在旧代码片段或第三方文章中看到 DocumentViewer，该类型在 SDK 中从未存在。

迁移检查清单

替换包；使插件包版本保持一致。
将许可证设置迁移到 AddDoconut() 中；删除静态许可证调用。
将打开调用改为异步；用 CloseDocument(token) 替代 Dispose 或无参数的 CloseDocument。
用 Converter 插件注册以及 DocumentConverter 替换 viewer.Converter 的使用。
重新测试安全路径：现在默认安全需要 AddSession()/UseSession()。