يتم عرض ترحيلين في هذه الصفحة: ترقية نسخة الحزمة داخل .NET 8، ونقل تكامل من إطار Doconut أقدم (.NET 6، .NET Standard 2.0، .NET Framework 4.7) إلى واجهة برمجة تطبيقات .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

واجهة برمجة تطبيقات .NET 8 تم إعادة تصميمها حول DI والبرمجة غير المتزامنة. الخريطة:

الاهتمام	.NET 6 / Standard 2.0	.NET 8
الإعداد	إنشاء `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + حقن `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 (نماذج الويب)

Viewer في الإصدار 4.7 هو 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 / خيارات JavaScript docViewer.
طرق التصدير التي تُعيد byte[] → واجهات برمجة التطبيقات غير المتزامنة لتصدير التعليقات التوضيحية على Viewer.

خطط لهذا الترحيل كإعادة كتابة للطبقة المستضيفة حول مفهوم غير متغير: فتح → رمز → ودجت.

ملاحظة حول التسمية

في جميع الأطر تكون الفئة هي Viewer — إذا وجدت DocumentViewer في مقتطفات قديمة أو مقالات طرف ثالث، فإن هذا النوع لم يكن موجودًا أبدًا في SDK.

قائمة التحقق للترحيل

استبدل الحزم؛ ووافق إصدارات حزم الملحقات.
انقل إعداد الترخيص إلى AddDoconut()؛ احذف استدعاءات الترخيص الثابتة.
اجعل استدعاءات الفتح غير متزامنة؛ استبدل Dispose/CloseDocument بدون معلمات بـ CloseDocument(token).
استبدل استخدامات viewer.Converter بتسجيل ملحق المحول + DocumentConverter.
أعد اختبار مسار الأمان: الآن AddSession()/UseSession() مطلوبان مع الإعدادات الأمنية الافتراضية.