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

نقل تطبيق Doconut.NET6 موجود إلى حقن الاعتمادات الحالي وواجهة برمجة التطبيقات غير المتزامنة

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

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

إذا كان المشروع يحتوي على…الجيل
app.MapWhen(... "DocImage.axd" ...)قديم / كلاسيكي
new Viewer(_cache, _accessor, ...)قديم / كلاسيكي
Viewer.DoconutLicense(...) أو Viewer.SetLicensePlugin(...)قديم / كلاسيكي
منسوخة يدوياً docViewer.js, documentLinks.js, أو docViewer.UI.jsقديم / كلاسيكي
builder.Services.AddDoconut(...)التكامل الحالي
app.UseDoconutResources() بالإضافة إلى app.UseDoconut()التكامل الحالي
Viewer مُزود بواسطة حقن الاعتماداتالتكامل الحالي
await viewer.OpenDocumentAsync(...)التكامل الحالي

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

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

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

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

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

bash
dotnet add package Doconut.NET6

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

bash
dotnet add package Doconut.NET6 --version 26.9.0

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

text
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 واعتمادات مستخرج الطلب:

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

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

csharp
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.

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

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

csharp
// تكامل كلاسيكي — إزالة أثناء التحويل.
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 في نقطة نهاية، صفحة Razor، مُتحكم، أو خدمة تطبيق ذات نطاق:

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

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

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

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

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

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

csharp
viewer.CloseDocument(token);

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

فئات التكوين

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

الاهتمامالنوع الحالي
مسارات الوسيط، الترخيص، تسجيل الإضافاتDoconutOptions
كلمة المرور، مهلة، أمان، علامة مائيةDocOptions
عرض التنسيق و DPIPdfConfig, WordConfig, ExcelConfig, وأنواع أخرى من BaseConfig
الإعدادات الافتراضية لأداة المتصفحViewerConfig أو خيارات JavaScript المكافئة
CSS والسكريبتات المُولَّدةCssConfig وScriptConfig

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

شريط أدوات المشاهد، البحث، والتعليقات التوضيحية

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

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

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

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

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

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

csharp
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:

csharp
builder.Services.AddDistributedMemoryCache(); // حالة الجلسة تحتاج إلى ذاكرة مؤقتة (MVC/Razor Pages يضيف واحدة بالفعل)
builder.Services.AddSession();
app.UseSession();

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

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

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

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

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

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

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

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

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

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

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

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

هل كانت هذه الصفحة مفيدة؟