الترقية من التكامل الكلاسيكي .NET 6

Doconut لديه تكاملان مميزان لـ .NET 6. يمكنهما استخدام نفس اسم الحزمة Doconut.NET6، لذا يجب تحديد الجيل من خلال واجهات البرمجة في التطبيق قبل تغيير الحزم أو الإعدادات الأولية أو التراخيص أو موارد المتصفح.

أي تكامل .NET 6 تستخدم؟

إذا ظهرت كلا العمودين في نفس التطبيق، اعتبر الترحيل غير مكتمل. لا تقم بإرسال رمز مستند واحد عبر الموارد أو الوسطاء من الجيل الآخر.

لماذا قد لا يخبرك اسم حزمة NuGet

كلا الجيلين تم إصدارهما تحت معرف الحزمة Doconut.NET6. لذا فإن إشارة الحزمة أو ملف القفل أو ملف .nupkg المخزن لا يحدد واجهة البرمجة المستضيفة بمفرده. سجّل نسخة الحزمة الدقيقة وتفحص Program.cs، وإنشاء الـ Viewer، وفتح المستند، ونصوص المتصفح معًا.

الإصدار الحالي الذي تم تدقيقه لهذا الدليل هو Doconut.NET6 26.7.0. حزمها العامة الاختيارية هي Doconut.NET6.Converter و Doconut.NET6.Dicom، المثبتة على نفس نسخة الإصدار كالحزمة الأساسية.

قبل الترحيل

1. أنشئ فرعًا ونسخة احتياطية قابلة للنشر من التطبيق الحالي.
2. سجّل النسخ الدقيقة للحزمة الأساسية والحزمة الإضافية.
3. قم بجرد كل تعيين DocImage.axd، واستدعاء new Viewer(...)، واستدعاء تحميل الترخيص، والسكريبت المنسوخ من Doconut، وإجراء شريط الأدوات المخصص، ونقطة النهاية لفتح المستند.
4. احفظ ملفات .lic الحالية وأسرار النشر خارج نظام التحكم بالمصدر.
5. اجمع مجموعة ممثلة من مستندات PDF، Office، الصور، CAD، البريد الإلكتروني، DICOM، القابلة للبحث، المحمية بكلمة مرور، والمُعَلَّمَة.
6. سجّل مهلة الجلسة الحالية، وسلوك الأمان، والخطوط، وإعدادات المنصة.

قم بترحيل بيئة واحدة قبل تعديل الإنتاج. يغيّر التكامل الحالي عمر الخدمة، وتوجيه الطلبات، وملكية الجلسة، وتوصيل موارد العميل.

توافق الحزمة والترخيص

استبدل أو حدّث الحزمة الأساسية عمدًا؛ لا تعتمد على معرف الحزمة المتطابق لاختيار الواجهة البرمجية الجديدة. الأمر الافتراضي يثبت أحدث إصدار ثابت:

dotnet add package Doconut.NET6

لترحيل قابل للتكرار إلى الإصدار المدقق في هذا الدليل، مرّر النسخة كخيار منفصل:

dotnet add package Doconut.NET6 --version 26.7.0

احتفظ بكل ملحق Doconut بنفس نسخة الحزمة الأساسية. يقوم التكامل الحالي بتحميل التراخيص مرة واحدة أثناء AddDoconut()، باستخدام أولوية التحميل التالية:

LicenseStream > LicenseContent > LicensePath > automatic discovery

الاكتشاف التلقائي يبحث عن ملفات Doconut.Viewer.lic وملفات المصاحبة Doconut.Viewer.<Capability>.lic. استدعاء كلاسيكي إلى Viewer.DoconutLicense(...) أو Viewer.SetLicensePlugin(...) ليس آلية بدء تشغيل حالية. انقل الترخيص إلى DoconutOptions، واحفظ الملفات المصاحبة معًا عند استخدام الاكتشاف التلقائي، وأعد التشغيل بعد تغيير الترخيص، وتحقق من القدرات عبر IDoconutLicenseService.

لا تفترض أن وجود ترخيص ملحق قديم يثبت الأهلية لبناء ملحق حالي. اختبر Viewer وSearch وAnnotation وConverter وDICOM بشكل منفصل باستخدام القطع الصادرة المعتمدة.

بدء التشغيل وحقن الاعتماديات

التطبيقات الكلاسيكية تنشئ Viewer باستخدام ذاكرة التخزين المؤقت لـ ASP.NET واعتمادات وصول الطلب:

// التكامل الكلاسيكي — للتمييز فقط؛ لا تقم بتجميع هذا ضد SDK الحالي.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

التكامل الحالي يسجل Doconut مرة واحدة ويتلقى Viewer من حقن الاعتماديات:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer هو خدمة مؤقتة. مدير جلسة المستند وذاكرة التخزين المؤقت الخاصة به يمتلكان حالة المستند ذات العمر الأطول، وليس كائن Viewer المحقون المحدد.

Middleware وتوجيه الموارد

إزالة الفرع الكلاسيكي MapWhen الذي يكتشف DocImage.axd:

// التكامل الكلاسيكي — إزالته أثناء الانتقال.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

في خط الأنابيب الحالي:

1. استدعِ UseSession() قبل Doconut بينما تكون أمان الجلسة مفعلة؛
2. استدعِ UseDoconutResources() قبل UseDoconut()؛
3. حافظ على ResourcesPath، عناوين URL للموارد المولدة، وResPath الخاص بالعميل متطابقة؛
4. عند تعيين UseDoconut() إلى فرع، حافظ على توافق ذلك الفرع وBasePath الخاص بالعميل.

MiddlewarePath هو تكوين تم التحقق منه؛ لا ينشئ فرعًا في ASP.NET Core بمفرده. استخدم إما خط الأنابيب البسيط في العينة المجمعة أعلاه أو ترتيبًا صريحًا app.Map("/doconut", branch => branch.UseDoconut()) يُستخدم باستمرار من قبل العميل.

إنشاء Viewer وعمره

إزالة ذاكرات التخزين المؤقت المملوكة للتطبيق لكائنات Viewer. حقن Viewer في نقطة النهاية، صفحة Razor، المتحكم، أو خدمة تطبيق ذات نطاق:

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

الرمز المميز المرتجع يحدد جلسة مستند على الخادم. عالجه كبيانات اعتماد حاملة: لا تقم بتسجيله، أو حفظه، أو وضعه في التحليلات.

فتح وإغلاق المستندات

استبدل OpenDocument(...) المتزامن بـ OpenDocumentAsync(...):

// تكامل .NET 6 الحالي: يأتي Viewer من حقن الاعتماديات وفتح المستند غير متزامن.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

الإصدارات الحالية تقبل مسار ملف أو تدفق، تكوين تنسيق اختياري، DocOptions اختياري، ورمز إلغاء. أغلق جلسة الخادم صراحةً عندما لا يحتاج المتصفح إليها:

viewer.CloseDocument(token);

لا تعيد استخدام رمز كلاسيكي بعد الانتقال. افتح كل مستند مرة أخرى عبر API الحالي.

فئات التكوين

API الحالي يفصل بين الاهتمامات:

لا تنقل DocOptions.ImageResolution كعنصر تحكم في العرض. إنه قديم؛ اضبط BaseConfig.ImageResolution في تكوين التنسيق المحدد. راجع جميع الإعدادات الافتراضية بدلاً من افتراض أن التكوين الكلاسيكي له نفس السلوك.

شريط أدوات Viewer، البحث، والتعليق

لا تقم بترحيل السكريبتات القديمة واحدة تلو الأخرى. التطبيقات المرجعية الحالية تُنشئ حزمة صفحة كاملة واحدة:

1. إصدار CSS الخاص بـ Viewer وCSS المرخص للبحث/التعليق باستخدام ReferenceCss؛
2. عرض شريط أدوات Viewer المملوك للتطبيق؛
3. عرض searchBarMount، annBarMount، والملحق المطلوب لـ Viewer؛
4. إصدار سكريبتات Viewer والوحدات المرخصة باستخدام ReferenceScripts؛
5. تحميل viewerToolbar.js الخاص بالتطبيق؛
6. تهيئة كائن واحد objViewer؛
7. تهيئة أشرطة البحث والتعليق المرخصة؛
8. استدعاء attach(objViewer) على كل شريط؛
9. فتح المستند واستدعاء objViewer.View(token).

البحث والتعليق هما وحدات مرفقة بنفس Viewer، وليس أشرطة أدوات مستقلة. شريط الأدوات الرئيسي يخص تطبيق المضيف؛ أشرطة البحث والتعليق مدمجة، موارد مقيدة بالقدرات.

قم بإزالة الملفات الكلاسيكية المنسوخة يدويًا مثل documentLinks.js و docViewer.UI.js فقط بعد أن تعمل الصفحة الحالية مع الموارد الصادرة عن ReferenceCss و ReferenceScripts.

تسجيل الإضافة

الطرق التقليدية الثابتة لتراخيص الإضافات لا تقوم بتسجيل الإضافات الحالية. قم بتثبيت وتسجيل كل حزمة صادرة صراحةً:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() يتحقق من قدرات الإضافات المسجلة عند بدء التشغيل. Converter و DICOM هما إضافات .NET 6 صادرة. البحث العادي والتعليقات التوضيحية هما ميزات مرخصة مدمجة، وليسا حزم AddPlugin<TPlugin>().

أمان الجلسة والوثيقة

التكامل الحالي يربط المستندات برموز مميزة غير شفافة وجلسات مخزنة مؤقتًا. مع الإعداد الافتراضي UnsafeMode = false، يضيف UseDoconut() أمان وصول المستند ويجب على المضيف تكوين جلسة ASP.NET:

builder.Services.AddDistributedMemoryCache(); // session state needs a cache (MVC/Razor Pages already add one)
builder.Services.AddSession();
app.UseSession();

احتفظ بـ DocOptions.IsSecured = true ما لم يتطلب تصميم مراجع ذلك بخلاف ذلك. لا تستخدم أبداً UnsafeMode = true كاختصار للترحيل. اختبر الطلبات بدون رمز مميز، أو رمز مميز غير صالح، أو رمز مميز منتهي الصلاحية، ورمز مميز من جلسة متصفح مختلفة.

تضيف تطبيق الإشارة الموزعة (Distributed reference application) تذاكر الوصول وتفاصيل النقل. تلك الواجهات البرمجية غير مطلوبة لترحيل عقدة واحدة عادي.

اختبار الترحيل

على الأقل، تحقق من:

• تشغيل التطبيق مع الترخيص الإنتاجي وكل إضافة مسجلة؛
• CSS/سكريبتات العارض وجميع طلبات صور الصفحات تحت المسارات المختارة؛
• فتح المستند، التنقل، التكبير، الصور المصغرة، الطباعة، والإغلاق الصريح؛
• البحث في مستند يحتوي على نص وحالة عدم إمكانية البحث في ملف يحتوي على صور فقط؛
• تحميل التعليقات التوضيحية، الحفظ، التصدير، وتقييد القدرة؛
• اكتشاف هدف المحول، الإخراج، التحميل، وحالة العلامة المائية؛
• صفحات DICOM، الإطارات، والرسوم المتحركة؛ لا تتوفر بيانات تعريف تقنية .NET 6؛
• المستندات المحمية بكلمة مرور، الخطوط المخصصة، النص غير اللاتيني، وإعدادات المهلات المكوّنة؛
• رفض الرموز المميزة عبر الجلسات وسلوك الجلسة المنتهية؛
• الهواتف المحمولة، الوضع الداكن، ومسار الوكيل العكسي للإنتاج.

خطة الاسترجاع

احتفظ بقطعة النشر الكلاسيكية، الحزم المطابقة، ملفات الترخيص، والموارد المتصفح المنسوخة معًا. استرجاع آمن يبدل الجيل الكامل للتطبيق؛ لا يخلط خادمًا كلاسيكيًا مع السكريبتات الحالية أو خادمًا حاليًا مع استدعاءات DocImage.axd الكلاسيكية.

قبل التحويل، وثّق:

• فتحة النشر أو القطعة المستخدمة للاسترجاع؛
• تأثير قاعدة البيانات/الذاكرة المؤقتة، إن وجد؛
• كيف سيتم إبطال جلسات المستند النشطة؛
• فحص الصحة ومستند الاختبار المستخدم لتقرير الاسترجاع؛
• من يمكنه استعادة مجموعة الحزم والإعدادات السابقة.

وثائق سابقة

يبقى الدليل الكلاسيكي المترجم متاحًا في إعداد .NET 6 القديم. الـ بوابة التكامل الكلاسيكي الجديد يشرح نفس إشارات التعريف ويربط مرة أخرى إلى دليل الترحيل هذا.

احتفظ بعنوان URL التاريخي في العلامات المرجعية وتذاكر الدعم بينما لا تزال تثبيتات الكلاسيك موجودة. فهو يوثق جيلًا مختلفًا ولا يتم إعادة توجيهه إلى API الحالي.