الترحيل من التكامل الكلاسيكي .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 واعتمادات وصول الطلب:

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

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

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

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

الوسيط وتوجيه الموارد

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

// Classic integration — remove during the cutover.
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(...):

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
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.AddSession();
app.UseSession();

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

تضيف تطبيقات المرجع الموزعة تذاكر الوصول وتفاصيل النقل. هذه الـ APIs ليست مطلوبة لترحيل عقدة واحدة عادي.

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

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

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

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

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

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

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

الوثائق القديمة

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

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