إدارة تحديثات التبعية في مشروع Microsoft .NET الخاص بك

مكتمل

عاجلا أم آجلا، تريد التحديث إلى إصدار جديد من مكتبة. ربما تم تعليم إحدى الوظائف على أنها مهملة، أو ربما هناك ميزة جديدة في إصدار لاحق من الحزمة التي تستخدمها.

ضع في اعتبارك ما يلي قبل محاولة تحديث المكتبة:

• نوع التحديث: ما نوع التحديث المتوفر؟ هل هو إصلاح عاجل للأخطاء؟ هل هو إضافة ميزة جديدة تحتاج إليها؟ هل يكسر التعليمات البرمجية الخاصة بك؟ يمكنك الاتصال بنوع التحديث باستخدام نظام يُسمى إصدارًا دلاليًا. الطريقة التي يتم بها التعبير عن رقم إصدار المكتبة تتصل بالمطورين بنوع التحديث الذي يتعاملون معه.
• ما إذا كان المشروع قد تم تكوينه بشكل صحيح: يمكنك تكوين مشروع .NET بحيث تحصل فقط على أنواع التحديثات التي تريدها. يمكنك إجراء تحديث فقط إذا كان هناك نوع معين من التحديثات متوفر. نُوصي باتباع هذا الأسلوب، لأنك لن تخاطر بمواجهة أي مفاجآت.
• مشاكل الأمان: تتضمن إدارة تبعيات المشروع بمرور الوقت أن تكون على دراية بالمشكلات التي قد تحدث. على سبيل المثال، تنشأ المشاكل عند اكتشاف نقاط الضعف. من الناحية المثالية، يتم إصدار التصحيحات التي يمكنك تنزيلها. تساعدك أداة Microsoft .NET Core في تشغيل تدقيق على مكتباتك لمعرفة ما إذا كان لديك حزم يجب تحديثها. كما تُساعدك على اتخاذ الإجراء المناسب لإصلاح المشكلة.

استخدام إصدار دلالي

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

• الإصدار الرئيسي: الرقم الموجود في أقصى اليسار. على سبيل المثال، هو في 11.0.0. يعني التغيير في هذا الرقم أنه يمكنك توقع "التغييرات العاجلة" في التعليمات البرمجية الخاصة بك. قد تحتاج إلى إعادة كتابة جزء من التعليمات البرمجية خاصتك.
• الإصدار الثانوي: الرقم الأوسط. على سبيل المثال، هو في 21.2.0. يعني تغيير هذا الرقم أنه تمت إضافة الميزات. يجب أن تظل تعليماتك البرمجية تعمل. عادة ما يكون قبول التحديث آمنا.
• الإصدار التصحيحي: الرقم الموجود في أقصى اليمين. على سبيل المثال، هو في 31.2.3. يعني التغيير في هذا الرقم أنه تم تطبيق تغيير يعمل على إصلاح شيء ما في التعليمات البرمجية التي يجب أن تعمل. قبول التحديث يجب أن يكون آمنًا.

يوضح هذا الجدول كيفية تغيير رقم الإصدار لكل نوع من الإصدارات:

نوع	ماذا يحدث
الإصدار الرئيسي	1.0.0 التغييرات التي تم إجراؤها على 2.0.0
الإصدار الثانوي	1.1.1 التغييرات التي تم إجراؤها على 1.2.0
الإصدار التصحيحي	1.0.1 التغييرات التي تم إجراؤها على 1.0.2

تستخدم العديد من الشركات والمطورين هذا النظام. إذا كنت تنوي نشر الحزم ودفعها إلى سجل NuGet، يتوقع منك اتباع الإصدار الدلالي. حتى لو قمت فقط بتنزيل الحزم من سجل NuGet، فإنك تتوقع أن تتبع هذه الحزم الإصدار الدلالي.

قد تؤدي التغييرات التي تطرأ على حزمة إلى حدوث مخاطر، بما في ذلك مخاطر أن يضر خطأ ما بعملك. قد تتطلب بعض المخاطر أن تُعيد كتابة جزء من التعليمات البرمجية. تستغرق إعادة كتابة التعليمات البرمجية وقتًا وتكلف مالًا.

نهج التحديث

بصفتك مطور .NET، يمكنك توصيل سلوك التحديث الذي تريده إلى .NET. فكر في التحديث من حيث المخاطر. فيما يلي بعض الأساليب:

• الإصدار الرئيسي: لا أمانع التحديث إلى الإصدار الأخير بمجرد صدوره. من جانبي، أقبل حقيقة أنني بحاجة إلى تغيير التعليمات البرمجية.
• الإصدار الثانوي: لا أمانع أن تُضاف ميزة جديدة. لا أوافق على مُقاطعة التعليمات البرمجية.
• الإصدار التصحيحيالإصلاح العاجل للأخطاء هي التحديثات الوحيدة التي أوافق عليها.

إذا كنت تُدير مشروع Microsoft .NET جديدًا أو أصغر، يُمكنك تحمُّل أن تكون غير قادر على كيفية تحديد استراتيجية التحديث. على سبيل المثال، يمكنك دومًا التحديث إلى أحدث إصدار. بالنسبة إلى المشاريع الأكثر تعقيدًا، هناك فارق بسيط، ولكن سنترك هذا لوحدة مُستقبلية.

بشكل عام، كلما كانت التبعية التي تقوم بتحديثها أصغر، قل عدد التبعيات التي تحتوي عليها وكلما زادت احتمالية سهولة عملية التحديث.

تكوين ملف المشروع للتحديث

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

نطاقات الإصدار هي رمز خاص يمكنك استخدامه للإشارة إلى نطاق معين من الإصدارات التي تريد حلها.

الرمز	القاعدة المُطبقة	‏‏الوصف
1.0	س >= 1.0	الإصدار الأدنى، شامل
(1.0,)	س > 1.0	الإصدار الأدنى، حصري
[1.0]	س == 1.0	مطابقة الإصدار الدقيق
(,1.0]	س ≤ 1.0	الإصدار الأقصى، شامل
(,1.0)	س < 1.0	الإصدار الأقصى، حصري
[1.0,2.0]	1.0 ≤ × ≤ 2.0	النطاق الدقيق، شامل
(1.0,2.0)	1.0 < س < 2.0	النطاق الدقيق، حصري
[1.0,2.0)	1.0 ≤ × < 2.0	مزيج بين الإصدار الأدنى الشامل والإصدار الأقصى الحصري
(1.0)	غير صالح	غير صالح

يدعم NuGet أيضا استخدام رمز إصدار عائم للأجزاء الرئيسية والثانوية والتصحيحية واللاحقة التجريبية من الرقم. هذا الرمز هو علامة النجمة (*). على سبيل المثال، مواصفات الإصدار 6.0.* تقول "استخدم أحدث إصدار 6.0.x." في مثال آخر، 4.* تعني "استخدام أحدث إصدار 4.x." يؤدي استخدام إصدار عائم إلى تقليل التغييرات التي تطرأ على ملف المشروع مع مواكبة أحدث إصدار من التبعية.

إشعار

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

عندما تستخدم إصدارًا حُرًا، يحل NuGet أحدث إصدار من الحزمة التي تتطابق مع نمط الإصدار. في المثال التالي، تحصل 6.0.* على أحدث إصدار من الحزمة التي تبدأ بـ 6.0. هذا الإصدار هو 6.0.1.

فيما يلي بعض الأمثلة التي يُمكن تكوينها لإصدار رئيسي أو ثانوي أو تصحيح:

<!-- Accepts any version 6.1 and later. -->
<PackageReference Include="ExamplePackage" Version="6.1" />

<!-- Accepts any 6.x.y version. -->
<PackageReference Include="ExamplePackage" Version="6.*" />
<PackageReference Include="ExamplePackage" Version="[6,7)" />

<!-- Accepts any later version, but not including 4.1.3. Could be
     used to guarantee a dependency with a specific bug fix. -->
<PackageReference Include="ExamplePackage" Version="(4.1.3,)" />

<!-- Accepts any version earlier than 5.x, which might be used to prevent pulling in a later
     version of a dependency that changed its interface. However, we don't recommend this form because determining the earliest version can be difficult. -->
<PackageReference Include="ExamplePackage" Version="(,5.0)" />

<!-- Accepts any 1.x or 2.x version, but not 0.x or 3.x and later. -->
<PackageReference Include="ExamplePackage" Version="[1,3)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and later. -->
<PackageReference Include="ExamplePackage" Version="[1.3.2,1.5)" />

العثور عن الحزم القديمة وتحديثها

يدرج الأمر dotnet list package --outdated حزمًا قديمة. يُمكن أن يساعدك هذا الأمر في معرفة متى تتوفر إصدارات أحدث من الحزم. فيما يلي إخراج نموذجي من الأمر:

Top-level Package      Requested   Resolved   Latest
> Humanizer            2.7.*       2.7.9      2.8.26

فيما يلي معاني أسماء الأعمدة في الإخراج:

• Requested: الإصدار أو نطاق الإصدار الذي حددته.
• Resolved: الإصدار الفعلي الذي تم تنزيله للمشروع الذي يطابق الإصدار المحدد.
• Latest: أحدث إصدار متوفر للتحديث من NuGet.

سير العمل المُقترح هو تشغيل الأوامر التالية بالترتيب التالي:

1. شغّل dotnet list package --outdated. يدرج هذا الأمر جميع الحزم القديمة. ويقدم معلومات في الأعمدة Requested، وResolved، وLatest.
2. شغّل dotnet add package <package name>. إذا قمت بتشغيل هذا الأمر، فإنه يحاول التحديث إلى أحدث إصدار. اختياري، يمكنك تمرير --version=<version number/range>.