دو نوع مهاجرت در این صفحه وجود دارد: به‌روزرسانی نسخه بسته در داخل .NET 8، و انتقال یک ادغام از یک چارچوب Doconut قدیمی (.NET 6، .NET Standard 2.0، .NET Framework 4.7) به API .NET 8.

به‌روزرسانی نسخه بسته

بسته را به‌روز کنید (و هر بسته افزونه — نسخه‌ها را هم‌راستا نگه دارید):

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 را دوباره پین نکنید (برای خطاهای دقیق ناشی از کاهش نسخه، بخش عیب‌یابی را ببینید).
یک تست سریع (Smoke-test) برای هر خانواده فرمت که استفاده می‌کنید، انجام دهید.

مهاجرت از .NET 6 / .NET Standard 2.0

API .NET 8 بازطراحی شده‌ای حول DI و async است. نگاشت زیر:

مورد	.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(...)` (همزمان)	`await viewer.OpenDocumentAsync(...)`
بستن	`viewer.CloseDocument()` or `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` نیست `IDisposable`
طول عمر	`Viewer` implements `IDisposable`, holds the open document	`Viewer` بدون حالت است؛ جلسات در کش زیر توکن‌ها زندگی می‌کنند
مبدل	`viewer.Converter` property	افزونه Converter (`AddPlugin<ConverterPlugin>()`) + سرویس `DocumentConverter`
کلاس‌های پیکربندی	`Doconut.Configs.View.*` namespaces	همه در فضای نام `Doconut`
میدلور	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)

Viewer نسخه 4.7 یک WebControl است؛ .NET 8 مدل کنترل را با middleware + سرویس DI جایگزین می‌کند:

کنترل <doconut:DocViewer runat=server> ناپدید می‌شود — صفحه جفت div ویجت را میزبانی می‌کند و نقطه انتهایی شما توکن را برمی‌گرداند (Quick Start الگو را نشان می‌دهد).
متدهای استاتیک مجوز → منابع مجوز DoconutOptions.
همزمان OpenDocument → await OpenDocumentAsync.
Viewer.ReferenceScripts() / ReferenceCss() در هر دو جهان وجود دارد — نسخه‌های .NET 8 ScriptConfig/CssConfig را می‌پذیرند و تحت مجوز هستند.
ویژگی‌های کنترل (ShowThumbs, PageZoom, FixedZoom, …) → همان نام‌ها در ViewerConfig / گزینه‌های JS docViewer.
متدهای خروجی که byte[] برمی‌گردانند → APIهای خروجی‌نویسی async روی Viewer.

این مورد را به‌عنوان بازنویسی لایه میزبانی حول یک مفهوم بدون تغییر برنامه‌ریزی کنید: باز کردن → توکن → ویجت.

نکته نام‌گذاری

در تمام چارچوب‌ها کلاس Viewer است — اگر DocumentViewer را در قطعات قدیمی یا مقالات شخص ثالث پیدا کنید، آن نوع هرگز در SDK وجود نداشته است.

فهرست بررسی مهاجرت

بسته‌ها را تعویض کنید؛ نسخه‌های بسته‌های افزونه را هم‌راستا کنید.
تنظیمات مجوز را به AddDoconut() منتقل کنید؛ فراخوانی‌های استاتیک مجوز را حذف کنید.
فراخوانی‌های باز کردن را async کنید؛ Dispose/CloseDocument بدون پارامتر را با CloseDocument(token) جایگزین کنید.
استفاده از viewer.Converter را با ثبت افزونه Converter + DocumentConverter جایگزین کنید.
مسیر امنیتی را دوباره تست کنید: AddSession()/UseSession() اکنون با امنیت پیش‌فرض ضروری هستند.