本页包含两种迁移：在 .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 围绕依赖注入（DI）和异步重新设计。对应关系如下：

关注点	.NET 6 / Standard 2.0	.NET 8
设置	Construct `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + inject `Viewer`
许可证	Static `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` per plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — one license, auto-discovery for plugin files
打开	`viewer.OpenDocument(...)` (synchronous)	`await viewer.OpenDocumentAsync(...)`
关闭	`viewer.CloseDocument()` or `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` is not `IDisposable`
生命周期	`Viewer` implements `IDisposable`, holds the open document	`Viewer` is stateless; sessions live in the cache under tokens
转换器	`viewer.Converter` property	The Converter plugin (`AddPlugin<ConverterPlugin>()`) + the `DocumentConverter` service
配置类	`Doconut.Configs.View.*` namespaces	All in the `Doconut` namespace
中间件	Manual handler wiring	`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) 迁移

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

<doconut:DocViewer runat=server> 控件消失——页面只保留部件 div 对，并由你的端点返回 token（快速入门展示了该模式）。
静态许可证方法 → DoconutOptions 许可证来源。
同步 OpenDocument → await OpenDocumentAsync。
Viewer.ReferenceScripts() / ReferenceCss() 在两种环境中都存在——.NET 8 版本接受 ScriptConfig/CssConfig 对象，并受许可证限制。
控件属性（ShowThumbs, PageZoom, FixedZoom, …）→ 在 ViewerConfig / docViewer JS 选项中使用相同名称。
返回 byte[] 的导出方法 → Viewer 上的异步标注导出 API。
将此迁移视为对托管层的重写，概念保持不变：open → token → widget。

命名说明

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

迁移检查清单

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