الترقيم الدلالي (أو SemVer اختصارًا) هو نظام ترقيم إصدارات البرمجيات الذي يحدد أرقام إصدارات مكونة من ثلاثة أجزاء على هيئة <الرئيسي>.<ال ثانوي>.<ال patch>، مثل 1.0.2، مع سابقة إصدار اختيارية على هيئة -<السابقة>، كـ 1.0.2-beta.

ربما يكون SemVer هو أكثر نظام ترقيم مستخدم اليوم. على سبيل المثال، كلا من Nuget و npm يوصي ويقوم بدعمه، و VS Code يستخدمه أيضًا.

في معظم مستودعات GitHub التي تستخدم ميزة إصدارات GitHub لنشر الإصدارات، سترى رقم إصدار SemVer في شعار الإصدار الأخير على الصفحة الرئيسية، كما يمكن رؤيته في اللقطة أدناه:

أحتاج بشكل متكرر إلى إعداد رقم إصدار SemVer عند بناء مشاريع واجهات برمجة تطبيقات ASP.NET Core، ثم قراءته أو إبلاغه أثناء التشغيل.

على سبيل المثال، إذا قمت ببناء واجهة برمجة تطبيقات بسيطة وضبط إصدارها على 1.0.2-بيتا، ستعرض هذه المعلومات من خلال نهاية /version التي يقدمها واجهة البرمجة، كما هو موضح في اللقطة أدناه من hoppscotch (هذا هو أداة مشابهة لـ Postman سهلة الاستخدام وتعمل داخل المتصفح):

التحقق من صحة الإصدار الذي يتم الإبلاغ عنه من الخدمات الم triểnخة، مثل تطبيقات الويب وواجهات البرمجة، هو جزء أساسي من مسار التوصيل المستمر الخاص بي وأحد اختبارات الدخان التي أستخدمها لتحديد ما إذا كان التطوير ناجحًا.

هناك تعقيد بسيط عند إعداد رقم إصدار SemVer على تجمعات .NET هو أن .NET استخدم في الأصل أرقام إصدار رباعية مثل 1.0.3.212 وما زالت التجمعات تحتوي على هذه الأرقام (التجمع هو مصطلح .NET لـ وحدات الكود الم 编ية إلى بيتكود .NET، وأكثر هذه الوحدات شيوعًا هي ملفات dll وexe).

الأخرى هي أن .NET لا يحتوي على رقم إصدار واحد فقط، بل على العديد من الأرقام المختلفة قليلاً التي توجد في نفس التجمع.

في هذا المقال، سأريكم كيفية التحاشي هذه الغرابة ووضع رقم إصدار SemVer على تجمع .NET أثناء البناء. أي، على ملفات .exe أو .dll الم 编ية، وكيفية قراءته أثناء التشغيل.

جدول المحتويات

هيكل رقم إصدار SemVer

تخيل رقم إصدار SemVer مثل 1.0.2 أو 1.0.2-beta. لديه الصيغة <الرئيسي>.<ال ثانوي>.<ال patch>–<ال إصدار التجريبي>

هذا ما تعنيه المكونات المختلفة:

المكون <major> من رقم الإصدار سيتم زيادته فقط إذا كان الإصدار الجديد سيقوم بكسر إصدار موجود (أحدث).

في حالة تطبيق واجهة المستخدم، قد يُقصد بالعملاء العملاء البشريين. لذا إذا كان الإصدار الجديد سيقوم بكسر الأصول الموجودة للمستخدمين مثل تعريف تدفق العمل،这将 يستدعي زيادة رقم الإصدار الرئيسي. في هذه الحالة، إذا كان الإصدار السابق هو 1.0.2، فإن الإصدار الجديد يجب أن يكون 2.0.0 (جميع المكونات الأدنى من رقم الإصدار سيتم إعادة تعيينها).

في حالة مكتبة، مثل حزمة مكتبة في Nuget أو NPM، فإن العملاء سيكونوا كودًا آخر. لذا إذا كان الإصدار الجديد سيقوم بكسر كود العميل الموجود، أي لن يكون متوافقًا مع الإصدار السابق الخاص به، فإن مكون <major> سيتم زيادته مرة أخرى.

<minor> يُزيد إذا تم إضافة ميزات جديدة ولكن الإصدار الجديد لا يزال متوافقًا مع الإصدارات السابقة. لذا من 1.0.2 ستنقل إلى 1.1.0.

<patch> يُزيد عندما يكون هناك حاجة إلى إصدار جديد حتى لو لم يحدث أي تغيير مكسر ولم تتم إضافة أي وظيفة جديدة. قد يحدث هذا، على سبيل المثال، إذا كان هناك إصلاح خطأ يجب إطلاقه.

-<prerelease> هو تذييل اختياري. يُضاف عادةً إلى رقم الإصدار الثلاثي عندما يحتاج البرنامج إلى التاحة أثناء مراحل الاختبار قبل الإصدار مثل الألفا والبيتا. على سبيل المثال، قبل إطلاق الإصدار 1.0.2 من برامجك بشكل عام، يمكنك تقديمها للمستخدمين التجريبيين كـ 1.0.2-beta.

الجزء <prerelease> يمكن أن يكون أي سلسلة من اختيارك، والشرط الوحيد هو أن يكون إما معرفًا أحرفيًا أو رقميًا مثل beta أو 12 أو alpha2 (لا حروف أو أرقام أخرى غير الأحرف والأرقام) أو معرفات أحرفية أو رقمية متعددة مفصولة بنقطة (.) مثل development.version.

أعداد إصدارات تجمع .NET

كما يشرح أندرو لوك في مقاله عن إصدارات .NET، فإن تجمع .NET يحتوي ليس على إصدار واحد بل على عدة إصدارات مختلفة:

  • إصدار التجمع: هذا هو رقم الإصدار الأربعاء، مثل 1.0.2.0. يتم استخدامه بواسطة Runtime عند تحميل التجمعات المرتبطة.

  • إصدار الملف: هذا هو رقم الإصدار الذي يتم الإبلاغ عنه لملف .dll في مستكشف الملفات في Windows عند النقر بزر الماوس الأيمن على التجمع واختيار الخصائص.

  • الإصدار المعلوماتي: إصدار آخر، ومثل FileVersion، يمكن رؤيته في حوار الخصائص إذا قمت بالنقر بزر الماوس الأيمن على المجموعة في Windows واختيار الخصائص. يمكن أن يحتوي على سلاسل نصية وليس فقط أرقام وأقواس مثل AssemblyVersion وFileVersion محددين.

  • إصدار الحزمة: إذا كان المشروع حزمة Nuget، سيكون هذا هو رقم إصدار الحزمة التي تكون المجموعة جزءًا منها.

جميع هذه الأرقام الإصدارية يتم إصدارها في المجموعة أثناء التجميع كبيانات وصفية. يمكنك رؤيتها إذا قمت بفحص المجموعة باستخدام JetBrains dotPeek (مجاني) أو Red gate Reflector (ليس مجاني) أو مشابهة.

FileVersion وInformationalVersion يمكن أيضًا رؤيتهما في علامة التفاصيل من حوار الخصائص الذي يظهر عند النقر بزر الماوس الأيمن على ملف المجموعة في مستكشف Windows واختيار الخصائص:

في اللقطة الشاشة العلوية، “إصدار المنتج” هو العنوان لمعلومات الإصدار (“InformationalVersion”) بينما “إصدار الملف” هو العنوان لـ “FileVersion”.

من الأنواع الأربعة لإصدارات الأرقام المذكورة أعلاه، تنطبق فقط الثلاثة الأولى على أي تجميع (أي سواء كان التجمع جزءًا من حزمة Nuget أم لا).

من هذه الثلاثة، يقوم AssemblyVersion دائمًا بإضافة 0 في المكان الرابع إذا حاولت تعيين إصدار SemVer يحتوي فقط على ثلاثة أرقام ( بالإضافة إلى لاحقة الإصدار التجريبي الاختيارية). على سبيل المثال، إذا حاولت تعيين إصدار SemVer يساوي 1.0.2-beta أثناء البناء، ثم قراءة قيمة AssemblyVersion في الوقت التشغيل في التجمع، ستكون 1.0.2.0.

FileVersion يقوم بنفس الشيء، كما هو موضح في اللقطة الشاشة العلوية.

إصدار المعلومات (“InformationalVersion”) هو فقط الرقم الإصداري الذي سيتم تعيينه بالضبط إلى إصدار الخادم الذي قمت بتعيينه أثناء البناء، كما يظهر في اللقطة الشاشة العلوية.

لذلك، إصدار المعلومات هو الإصدار الذي يجب قراءته أثناء التشغيل لاستعادة إصدار SemVer الخاص بالتجمع.

كيفية تعيين رقم إصدار SemVer

هناك شيئان تحتاج إلى القيام به لتعيين رقم إصدار SemVer على تجمع أثناء البناء.

الأول، في عنصر <PropertyGroup> في ملف مشروع csproj، أضف العنصر <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>:

<PropertyGroup>
 ...
 <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion> 
</PropertyGroup>

كما وصف في هذه المشكلة، يضمن هذا أن يتم إعداد InformationalVersion بالضبط إلى رقم الإصدار SemVer الذي حددناه و لا يتم إضافة +<رمز المفتاح> في النهاية.

ثانيًا، قم بتمرير رقم الإصدار كقيمة لخاصية Version الممررة إلى أمر dotnet build مثلًا:

dotnet build --configuration Release -p Version=1.0.2-beta

سيؤدي هذا إلى إعداد InformationalVersion في الملف الم 编د (ملف .exe أو .dll) إلى 1.0.2-beta.

偶然间، سيؤدي ذلك أيضًا إلى إعداد AssemblyVersion و FileVersion (سيتم إضافة 0 إضافية في نهاية 1.0.2)但我们 لسنا مهتمين بهما.

لاحظ أن بدلاً من تمرير argument Version على سطر الأوامر، يمكنك إعداد خاصية MS Build <Version>1.0.2-beta</Version> في عنصر <PropertyGroup> في ملف csproj. ومع ذلك، تمرير قيمة معلمة Version إلى dotnet build أسهل لأن ملف csproj لا يحتاج إلى تعديل في كل مرة يتم increment الإصدار. هذا مفيد في أنظمة تسليمPipeline. كما أن ملفات csproj لا تحتوي بشكل افتراضي على أي خاصية تتعلق بالتعداد.

كيفية قراءة إصدار SemVer لمكتبة عند التشغيل

الcode الذي يقرأ InformationalVersion عند التشغيل هو كما يلي:

string? version = Assembly.GetEntryAssembly()?.
  GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.
  InformationalVersion;

في APIs المينيمالية الخاصة بي، لإضافة نهاية نقطة /version كما هو موضح في قسم المقدمة أعلاه، أضع النص المذكور أعلاه في Program.cs، ثم أضيف النص التالي فورًا بعد ذلك. يرجى ملاحظة أن كل شيء يجب أن يظهر قبل builder.Build() يتم استدعاؤه:

//هذا الكائن من نوع مجهول سيتم
//تسريعها كـ JSON في جسم الرد
//عند عودتها من قبل المعالج
var objVersion = new { Version = version ?? "" };

//OTHER CODE
//var app = builder.Build()

بعد استدعاء builder.Build()، أنشئ معالج نهاية نقطة /version:

app.MapGet("/version", () => objVersion);

الآن عند تشغيل مشروع API واستدعاء نهاية نقطة /version، أحصل على رقم الإصدار في كائن JSON في جسم الرد HTTP:

{
  "version": "1.0.2-beta"
}

هذا ما أظهرته لقطة الشاشة لـ Hoppscotch في المقدمة.

الخاتمة

عرض هذا المقال لك كيفية إعداد رقم إصدار SemVer في تجمعاتك.NET، المكتبات، أو التطبيقات.

كما عرض لك كيفية قراءة رقم الإصدار أثناء التشغيل.