Partage via


Gestion des versions

Une bibliothèque de logiciels est rarement terminée dans la version 1.0. De bonnes bibliothèques évoluent au fil du temps, en ajoutant des fonctionnalités, en corrigeant des bogues et en améliorant les performances. Il est important que vous puissiez publier de nouvelles versions d’une bibliothèque .NET sans briser les utilisateurs existants.

Changements cassants

Pour plus d’informations sur la gestion des modifications avec rupture entre les versions, consultez Modifications avec rupture.

Numéros de version

Une bibliothèque .NET a de nombreuses façons de spécifier une version. Ces versions sont les plus importantes :

Version du package NuGet

La version du package NuGet s’affiche sur NuGet.org et le gestionnaire de package NuGet de Visual Studio, et est ajouté au code source lorsque le package est utilisé. La version du package NuGet est le numéro de version que les utilisateurs voient généralement et ils y font référence lorsqu’ils parlent de la version d’une bibliothèque qu’ils utilisent. La version du package NuGet est utilisée par NuGet et n’a aucun effet sur le comportement d’exécution.

<PackageVersion>1.0.0-alpha1</PackageVersion>

L’identificateur de package NuGet combiné à la version du package NuGet est utilisé pour identifier un package dans NuGet. Par exemple, Newtonsoft.Json + 11.0.2. Un package avec un suffixe est un package de préversion et a un comportement spécial qui le rend idéal pour les tests. Pour plus d’informations, consultez Packages de préversion.

Étant donné que la version du package NuGet est la version la plus visible pour les développeurs, il est judicieux de le mettre à jour à l’aide de l’outil Gestion sémantique de version (SemVer). SemVer indique l’importance des modifications entre les versions et aide les développeurs à prendre une décision éclairée lors du choix de la version à utiliser. Par exemple, le passage de 1.0 à 2.0 indique qu’il existe potentiellement des modifications avec rupture.

✔️ ENVISAGEZ d’utiliser SemVer 2.0.0 pour versionner votre package NuGet.

✔️ Utilisez la version du package NuGet dans la documentation publique, car il s’agit du numéro de version que les utilisateurs verront généralement.

✔️ CE QUE VOUS DEVEZ FAIRE : inclure un suffixe de préversion lors de la publication d’un package non stable. (Pour plus d’informations sur le marquage d’API comme préversion ou expérimentale, consultez API de préversion.)

Les utilisateurs doivent choisir d’obtenir des packages de préversion afin qu’ils comprennent que le package n’est pas terminé.

Version de l’assembly

La version de l’assembly est ce que le CLR utilise au moment de l’exécution pour sélectionner la version d’un assembly à charger. La sélection d’un assembly à l’aide du contrôle de version s’applique uniquement aux assemblys portant un nom fort.

<AssemblyVersion>1.0.0.0</AssemblyVersion>

Le CLR .NET Framework exige une correspondance exacte pour charger un assembly avec un nom fort. Par exemple, Library1, Version=1.0.0.0 a été compilée avec une référence à Newtonsoft.Json, Version=11.0.0.0. .NET Framework charge uniquement cette version exacte 11.0.0.0. Pour charger une autre version au moment de l’exécution, une redirection de liaison doit être ajoutée au fichier de configuration de l’application .NET.

Les noms forts combinés avec la version de l’assembly permet un chargement strict de la version d’assembly. Même si l’utilisation d’un nom fort pour une bibliothèque présente plusieurs avantages, cela génère souvent des exceptions d’exécution indiquant qu’un assembly est introuvable, et nécessite des redirections de liaison dans app.config ou web.config pour corriger le problème. Dans .NET (Core), le chargement des assemblages est plus flexible. Le runtime .NET (Core) charge automatiquement des assemblys avec une version ultérieure au moment de l’exécution.

✔️ ENVISAGEZ d’inclure uniquement une version majeure dans AssemblyVersion.

Par exemple, Library 1.0 et Library 1.0.1 ont tous deux la AssemblyVersion de 1.0.0.0, tandis que Library 2.0 a la AssemblyVersion de 2.0.0.0. Lorsque la version de l'assemblage change moins souvent, cela réduit les redirections de liaison.

✔️ ENVISAGEZ de conserver le numéro de version principal de l’AssemblyVersion et la version du paquet NuGet synchronisés.

La valeur AssemblyVersion est incluse dans certains messages d’information affichées à l’utilisateur, par exemple, le nom de l’assembly et les noms du type d’assembly qualifié dans les messages d’exception. La gestion d’une relation entre les versions fournit plus d’informations aux développeurs sur la version qu’ils utilisent.

❌ CE QUE VOUS DEVEZ ÉVITER : utiliser une valeur AssemblyVersion fixe.

Bien qu’un AssemblyVersion immuable évite la nécessité de redirections de liaison, cela signifie que seule une seule version de l’assembly peut être installée dans le Global Assembly Cache (GAC). En outre, les applications qui font référence à l’assembly dans le GAC s’arrêtent si une autre application met à jour l’assembly GAC avec les dernières modifications.

Version du fichier d’assembly

La version du fichier d’assembly est utilisée pour afficher une version de fichier dans Windows et n’a aucun effet sur le comportement d’exécution. La définition de cette version est facultative. Il est visible dans la boîte de dialogue Propriétés du fichier dans l’Explorateur Windows :

<FileVersion>11.0.2.21924</FileVersion>

Explorateur Windows

✔️ À ENVISAGER : Inclure un numéro de build d’intégration continue en tant que révision AssemblyFileVersion.

Par exemple, vous créez la version 1.0.0 de votre projet, et le numéro de build d’intégration continue est 99. Votre AssemblyFileVersion est donc 1.0.0.99.

✔️ CE QUE VOUS DEVEZ FAIRE : utiliser le format Major.Minor.Build.Revision pour la version du fichier.

Bien que la version du fichier ne soit jamais utilisée par .NET, Windows s’attend à ce que la version du fichier soit au format Major.Minor.Build.Revision. Un avertissement est déclenché si la version ne suit pas ce format.

Version d’informations sur l’assemblage

La version informationnelle de l’assembly est utilisée pour enregistrer des informations de version supplémentaires et n’a aucun effet sur le comportement d’exécution. La définition de cette version est facultative. Si vous utilisez source Link, cette version sera définie sur la build avec la version du package NuGet, ainsi qu’une version de contrôle de code source. Par exemple, 1.0.0-beta1+204ff0a inclut le hachage de validation du code source à partir duquel l’assembly a été généré. Pour plus d’informations, consultez Source Link.

<InformationalVersion>The quick brown fox jumped over the lazy dog.</InformationalVersion>

Remarque

Les versions antérieures de Visual Studio déclenchent un avertissement de build si cette version ne suit pas le format Major.Minor.Build.Revision. L’avertissement peut être ignoré en toute sécurité.

❌ CE QUE VOUS DEVEZ ÉVITER : définir vous-même la version des informations sur l’assembly.

Autoriser SourceLink à générer automatiquement la version contenant les métadonnées nuGet et contrôle de code source.

Précédent suivante