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

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

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

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

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

كلا الجيلين يُوزَّع تحت معرف الحزمة Doconut.NET6. لذلك لا يُحدِّد مرجع الحزمة أو ملف القفل أو ملف .nupkg المستضاف API المضيف بمفرده. سجِّل نسخة الحزمة الدقيقة وتفحص 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. سجِّل مهلة الجلسة الحالية، وسلوك الأمان، والخطوط، وإعدادات المنصة.

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

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

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

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 });
});

الرمز المُرجع يحدد جلسة مستند على الخادم. اعتبره اعتمادًا من نوع Bearer: لا تُسجِّله، ولا تُخزّنه، ولا تضعه في التحليلات.

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

استبدل 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/سكربتات Viewer وكل طلبات صور الصفحة تحت المسارات المختارة؛
• فتح المستند، والتنقل، والتكبير، والصور المصغرة، والطباعة، والإغلاق الصريح؛
• البحث في مستند يحتوي نص وحالة عدم البحث في ملف صورة فقط؛
• تحميل التعليقات، وحفظها، وتصديرها، وتقييد القدرات؛
• اكتشاف هدف Converter، والإخراج، والتنزيل، وحالة العلامة المائية؛
• صفحات DICOM، الإطارات، والرسوم المتحركة؛ لا تتوفر بيانات ميتا تقنية .NET 6؛
• المستندات المحمية بكلمة مرور، الخطوط المخصَّصة، النص غير اللاتيني، والمهلات المُكوَّنة؛
• رفض الرموز عبر الجلسات وسلوك الجلسة المنتهية؛
• التجربة على الهواتف المحمولة، الوضع الداكن، ومسار الوكيل العكسي للإنتاج.

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

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

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

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

الوثائق الكلاسيكية

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

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