دو نوع مهاجرت در این صفحه وجود دارد: به‌روزرسانی نسخه بسته در .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
راه‌اندازی	ساخت `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + inject `Viewer`
مجوز	استاتیک `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` به‌ازای افزونه	`options.LicensePath` / `LicenseContent` / `LicenseStream` — یک مجوز، کشف خودکار برای فایل‌های افزونه
باز کردن	`viewer.OpenDocument(...)` (همزمان)	`await viewer.OpenDocumentAsync(...)`
بستن	`viewer.CloseDocument()` یا `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` نیست `IDisposable`
طول عمر	`Viewer` پیاده‌سازی `IDisposable`، سند باز را نگه می‌دارد	`Viewer` بی‌حالت است؛ نشست‌ها در کش تحت توکن‌ها زندگی می‌کنند
مبدل	ویژگی `viewer.Converter`	افزونه مبدل (`AddPlugin<ConverterPlugin>()`) + سرویس `DocumentConverter`
کلاس‌های پیکربندی	فضاهای نام `Doconut.Configs.View.*`	همه در فضای نام `Doconut`
میان‌افزار	سیم‌کشی دستی هندلر	`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)

Viewer نسخه 4.7 یک WebControl است؛ .NET 8 مدل کنترل را با میان‌افزار + سرویس 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 را با ثبت افزونه مبدل + DocumentConverter جایگزین کنید.
مسیر امنیتی را دوباره تست کنید: AddSession()/UseSession() اکنون با امنیت پیش‌فرض لازم هستند (به‌علاوه AddDistributedMemoryCache() در یک برنامه minimal-API).