دو نوع مهاجرت در این صفحه وجود دارد: به‌روزرسانی نسخه بسته در .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(...)` (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)

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() اکنون با امنیت پیش‌فرض ضروری هستند.