Versionnement sémantique (ou SemVer pour faire court) est un schéma de versionnement logiciel qui stipule des numéros de version à trois parties sous la forme <principal>.<secondaire>.<correctif>, comme 1.0.2, avec un suffixe de version bêta optionnel sous la forme -<préversion>, comme dans 1.0.2-beta.

SemVer est sans doute le schéma de versionnement le plus largement utilisé aujourd’hui. Par exemple, à la fois Nuget et npm le recommandent et le supportent, et VS Code <diy6{l’ utilise} également.

Dans la plupart des dépôts GitHub qui utilisent la fonction GitHub Releases pour publier des versions, vous verriez un numéro de version SemVer dans le badge de la dernière version sur la page d’accueil, comme on peut le voir dans la capture d’écran ci-dessous :

J’ai souvent besoin de définir un numéro de version SemVer lors de la construction de projets API ASP.NET Core, puis de le lire ou de le signaler au moment de l’exécution.

Par exemple, si je construis une API minimale avec sa version définie à 1.0.2-beta, cela serait signalé par un point de terminaison /version exposé par l’API, comme illustré dans la capture d’écran ci-dessous provenant de Hoppscotch (c’est un outil similaire à Postman avec la commodité qu’il s’exécute dans le navigateur) :

Vérifier que la version signalée à partir des services déployés, tels que les applications web et les API, est correcte fait partie intégrante de mon pipeline CI/CD et est l’un des tests de smoke que j’utilise pour déterminer si un déploiement a réussi.

Une légère complication lors de la définition d’un numéro de version SemVer sur les assemblées .NET est que .NET utilisait à l’origine des numéros de version à quatre parties comme 1.0.3.212 et les assemblées en ont toujours (l’assemblée est le terme .NET pour unités de code compilées en bytecode .NET, les plus typiques étant les dll et les exe).

L’autre est que .NET n’a pas un mais plusieurs numéros de version légèrement différents qui sont présents dans la même assemblée.

Dans cet article, je vais vous montrer comment contourner ces particularités et apposer un numéro de version SemVer sur une assemblée .NET pendant la compilation. C’est-à-dire sur un compilé .exe ou .dll, et comment le lire en temps d’exécution.

Table des matières

Structure d’un numéro de version SemVer

Considérez un numéro de version SemVer comme 1.0.2 ou 1.0.2-beta. Il a la forme <principal>.<secondaire>.<correctif>–<prépublication>

Ce que signifient les différents composants :

Le composant <major> de la version doit être incrémenté uniquement si la nouvelle version pourrait casser une version existante (la plus récente).

Dans le cas d’une application UI, les clients pourraient être pris pour clients humains. Donc, si la nouvelle version pourrait casser les actifs existants des utilisateurs tels que les définitions de flux de travail, cela nécessiterait d’incrémenter le numéro de version majeure. Dans ce cas, si la version précédente était 1.0.2, la nouvelle version devrait être 2.0.0 (tous les composants inférieurs de la version seraient réinitialisés).

Dans le cas d’une bibliothèque, comme une bibliothèque pakage sur Nuget ou NPM, les clients seraient d’autres codes. Donc, si la nouvelle version pourrait casser le code client existant, c’est-à-dire qu’elle ne serait pas rétrocompatible avec sa propre version précédente, alors à nouveau, c’est le composant <major> qui serait incrémenté.

<minor> est incrémenté si de nouvelles fonctionnalités ont été ajoutées mais que la nouvelle version reste rétrocompatible. Donc, depuis 1.0.2, on passerait à 1.1.0.

<patch> est incrémenté lorsque une nouvelle version doit être publiée même s’il n’y a pas de changement cassant et qu’aucune nouvelle fonctionnalité n’a été ajoutée. Cela pourrait se produire, par exemple, si une correction de bug devait être publiée.

-<prerelease> est un suffixe optionnel. Il est généralement ajouté à un numéro de versionné en trois parties lorsque le logiciel doit être rendu disponible pendant les phases de test préliminaires telles que alpha et bêta. Par exemple, avant de publier généralement la version 1.0.2 de votre logiciel, vous pouvez la rendre disponible à vos testeurs bêta sous la forme 1.0.2-beta.

La composante <prerelease> peut être pratiquement n’importe quelle chaîne de votre choix et la seule exigence est qu’elle soit soit un identifiant alphanumérique tel que beta ou 12 ou alpha2 (aucun caractère autre que des chiffres ou des lettres de l’alphabet) ou plusieurs identifiants alphanumériques séparés par un point (.) par exemple development.version.

Les nombreux numéros de version d’une assembly .NET

Comme l’article d’Andrew Lock sur la versionning .NET l’explique, une assembly .NET n’a pas un mais plusieurs numéros de version différents :

  • AssemblyVersion : Il s’agit d’un numéro de version à quatre parties, par exemple, 1.0.2.0. Il est utilisé par le runtime lors du chargement des assemblies liées.

  • FileVersion : Il s’agit du numéro de version signalé pour un fichier .dll dans l’Explorateur de fichiers Windows lorsque vous faites un clic droit sur l’assembly et sélectionnez Propriétés.

  • VersionInformationnelle : Encore un numéro de version, et comme FileVersion, il peut être vu dans la boîte de dialogue Propriétés si vous faites un clic droit sur l’assemblage sous Windows et sélectionnez Propriétés. Cela peut contenir des chaînes de caractères et pas seulement des entiers et des points comme AssemblyVersion et FileVersion sont limités.

  • VersionPaquet : Si le projet est un paquet Nuget, ce serait le numéro de version du paquet dont fait partie l’assemblage.

Toutes ces numéros de version sont émis dans l’assemblage pendant la compilation en tant que métadonnées. Vous pouvez les voir si vous inspectez l’assemblage avec JetBrains dotPeek (gratuit) ou Red gate Reflector (payant) ou similaire.

FileVersion et VersionInformationnelle peuvent également être vus dans l’onglet Détails de la boîte de dialogue Propriétés qui apparaît lorsque vous faites un clic droit sur le fichier d’assemblage dans l’Explorateur de fichiers Windows et sélectionnez Propriétés :

Dans la capture d’écran ci-dessus, « Product version » est le titre pour InformationalVersion tandis que « File version » est le titre pour FileVersion.

Des quatre types de numéros de version décrits ci-dessus, seuls les trois premiers s’appliquent à n’importe quel assemblage (c’est-à-dire que l’assemblage fait ou ne fait pas partie d’un paquet Nuget).

Parmi ceux-ci, AssemblyVersion ajoute toujours un 0 à la quatrième place si vous essayez de définir une version SemVer qui n’a que trois chiffres (plus un suffixe prerelease optionnel). Par exemple, si vous essayez de définir une version SemVer de 1.0.2-beta pendant la construction et puis lire la valeur AssemblyVersion au moment de l’exécution dans l’assemblage, elle serait 1.0.2.0.

FileVersion fait la même chose, comme le montre la capture d’écran ci-dessus.

InformationalVersion est le seul numéro de version qui serait exactement défini à la version serveur que vous avez définie pendant la construction, comme le montre la capture d’écran ci-dessus.

Par conséquent, InformationalVersion est la version qui devrait être lue au moment de l’exécution pour récupérer la version SemVer de l’assemblage.

Comment Définir un Numéro de Version SemVer

Il y a deux choses que vous devez faire pour définir un numéro de version SemVer sur un assemblage pendant la construction.

Premièrement, dans un élément <PropertyGroup> dans le fichier csproj du projet, ajoutez l’élément <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion> :

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

Comme décrit dans cette question, cela garantit que InformationalVersion est exactement configuré sur le numéro de version SemVer que nous avons spécifié et qu’aucun +<code hash> n’est ajouté à la fin.

Deuxièmement, passez le numéro de version comme valeur de la propriété Version transmise à la commande dotnet build par exemple :

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

Cela définirait InformationalVersion dans l’assemblée compilée (fichier .exe ou .dll) sur 1.0.2-beta.

Accessoirement, cela définirait également AssemblyVersion et FileVersion (un 0 supplémentaire serait ajouté à la fin de 1.0.2), mais nous ne sommes pas intéressés par ceux-ci.

Notez que plutôt que de passer l’argument Version sur la ligne de commande, vous pouvez définir la propriété MS Build <Version>1.0.2-beta</Version> dans un élément <PropertyGroup> dans le fichier csproj. Cependant, passer une valeur du paramètre Version à dotnet build est plus simple car le fichier csproj n’a pas besoin d’être modifié à chaque incrément du numéro de version. Cela est utile dans les pipelines de CI/CD. De plus, par défaut, les fichiers csproj n’ont aucune propriété liée au versionnement.

Comment lire la version SemVer d’une assembly au moment de l’exécution

Le code qui lit InfromationalVersion au moment de l’exécution est comme suit :

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

Dans mes API minimales, pour ajouter un point de terminaison /version comme je l’ai montré dans la section Introduction ci-dessus, je place l’extrait ci-dessus dans Program.cs, puis j’ajoute l’extrait suivant immédiatement après. Notez que l’ensemble doit apparaître avant builder.Build() soit appelé :

//cet objet de type anonyme sera 
//être sérialisé en JSON dans le corps de la réponse
//quand il sera renvoyé par un handler
var objVersion = new { Version = version ?? "" };

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

Après builder.Build() est appelé, je crée le gestionnaire pour le point de terminaison /version:

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

Maintenant, lorsque j’exécute le projet API et que j’appelle le point de terminaison /version, je récupère le numéro de version dans un objet JSON dans le corps de la réponse HTTP:

{
  "version": "1.0.2-beta"
}

C’est ce que la capture d’écran de Hoppscotch dans l’introduction a montré.

Conclusion

Cet article vous a montré comment définir un numéro de version SemVer dans vos assemblages, bibliothèques ou applications .NET.

Il vous a également montré comment lire le numéro de version à l’exécution.