本页包含两种迁移：在 .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
Setup	构造 `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + 注入 `Viewer`
License	静态 `Viewer.DoconutLicense(path)` + 每个插件的 `SetLicensePlugin(...)`	`options.LicensePath` / `LicenseContent` / `LicenseStream` — 单一许可证，插件文件自动发现
Open	`viewer.OpenDocument(...)`（同步）	`await viewer.OpenDocumentAsync(...)`
Close	`viewer.CloseDocument()` 或 `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` 不是 `IDisposable`
Lifetime	`Viewer` 实现 `IDisposable`，持有打开的文档	`Viewer` 是无状态的；会话在缓存中通过 token 存在
Converter	`viewer.Converter` 属性	Converter 插件 (`AddPlugin<ConverterPlugin>()`) + `DocumentConverter` 服务
Config classes	`Doconut.Configs.View.*` 命名空间	全部位于 `Doconut` 命名空间
Middleware	手动处理程序绑定	`app.UseDoconutResources()` + `app.UseDoconut()`

一个典型的前后对比：

text

// .NET 6（旧 API，作对比展示 — 在 .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 注入，许可证在 AddDoconut() 中配置一次
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

从 .NET Framework 4.7（Web Forms）迁移

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。
将 viewer.Converter 的使用替换为 Converter 插件注册 + DocumentConverter。
重新测试安全路径：现在默认安全需要 AddSession()/UseSession()（在 minimal-API 应用中还需 AddDistributedMemoryCache()）。