Versionarea si bibliotecile .NET

• 26.01.2021
• 4 minute de citit

In acest articol

O biblioteca software este rareori completa in versiunea 1.0. Bibliotecile bune evolueaza in timp, adaugand caracteristici, remediind erori si imbunatatind performanta. Este important sa puteti lansa noi versiuni ale unei biblioteci .NET, oferind valoare suplimentara cu fiecare versiune, fara a rupe utilizatorii existenti.

Modificari de rupere

Pentru informatii despre gestionarea modificarilor de rupere intre versiuni, consultati Breaking changes.

Numere de versiune

O biblioteca .NET are multe modalitati de a specifica o versiune. Aceste versiuni sunt cele mai importante:

Versiunea pachetului NuGet

Versiunea pachetului NuGet este afisata pe NuGet.org, managerul de pachete Visual Studio NuGet si se adauga la codul sursa atunci cand pachetul este utilizat. Versiunea pachetului NuGet este numarul de versiune pe care il vor vedea in mod obisnuit utilizatorii si se vor referi la aceasta atunci cand vorbeste despre versiunea unei biblioteci pe care o folosesc. Versiunea pachetului NuGet este utilizata de NuGet si nu are niciun efect asupra comportamentului de rulare.

<PackageVersion> 1.0.0-alpha1 </PackageVersion>

Identificatorul pachetului NuGet combinat cu versiunea pachetului NuGet este utilizat pentru a identifica un pachet in NuGet. De exemplu, Newtonsoft.Json + 11.0.2. Un pachet cu sufix este un pachet de pre-lansare si are un comportament special care il face ideal pentru testare. Pentru mai multe informatii, consultati Pachetele de pre-lansare.

Deoarece versiunea pachetului NuGet este cea mai vizibila versiune pentru dezvoltatori, este o idee buna sa o actualizati folosind Semantic Versioning (SemVer). SemVer indica semnificatia schimbarilor dintre lansare si ajuta dezvoltatorii sa ia o decizie in cunostinta de cauza atunci cand aleg ce versiune sa utilizeze. De exemplu, trecerea de la 1.0 la 2.0 indica faptul ca exista modificari potentiale.

✔️ Luati in considerare utilizarea SemVer 2.0.0 pentru a va versiona pachetul NuGet.

✔️ Folositi versiunea pachetului NuGet in documentatia publica, deoarece este numarul versiunii pe care utilizatorii il vor vedea in mod obisnuit.

✔️ NU includeti un sufix pre-lansare atunci cand eliberati un pachet nestabil.

Utilizatorii trebuie sa opteze pentru obtinerea pachetelor pre-lansare, astfel incat vor intelege ca pachetul nu este complet.

Versiunea de asamblare

Versiunea de asamblare este ceea ce CLR foloseste in timpul rularii pentru a selecta versiunea unui ansamblu de incarcat. Selectarea unui ansamblu utilizand versiuni se aplica numai ansamblurilor cu un nume puternic.

<AssemblyVersion> 1.0.0.0 </AssemblyVersion>

.NET Framework CLR solicita o potrivire exacta pentru a incarca un ansamblu puternic. De exemplu, Library1, Version = 1.0.0.0 a fost compilat cu o referinta la Newtonsoft.Json, Version = 11.0.0.0. .NET Framework va incarca doar acea versiune exacta 11.0.0.0. Pentru a incarca o versiune diferita in timpul rularii, trebuie adaugata o redirectionare obligatorie in fisierul de configurare al aplicatiei .NET.

Denumirea puternica combinata cu versiunea de asamblare permite incarcarea stricta a versiunii de asamblare. In timp ce denumirea puternica a unei biblioteci are o serie de avantaje, de multe ori rezulta exceptii in timp de executie ca un ansamblu nu poate fi gasit si necesita corectii de redirectionare obligatorii in app.config sau web.config. In .NET Core, incarcarea ansamblului este mai relaxata. Runtime-ul .NET Core incarca automat ansamblurile cu o versiune superioara in timpul rularii.

✔️ Luati in considerare includerea doar a unei versiuni majore in versiunea Assembly.

De exemplu, Biblioteca 1.0 si Biblioteca 1.0.1 au ambele o versiune AssemblyVersion de 1.0.0.0, in timp ce Biblioteca 2.0 are AssemblyVersion de 2.0.0.0. Cand versiunea de asamblare se modifica mai rar, reduce redirectionarile de legare.

✔️ Luati in considerare pastrarea sincronizata a versiunii majore a versiunii AssemblyVersion si a versiunii pachetului NuGet.

AssemblyVersion este inclus in unele mesaje informationale afisate utilizatorului, de exemplu, numele ansamblului si numele de tip calificat de asamblare in mesajele de exceptie. Mentinerea unei relatii intre versiuni ofera dezvoltatorilor mai multe informatii despre versiunea pe care o utilizeaza.

❌ NU aveti o versiune de asamblare fixa.

In timp ce o versiune AssemblyVersion neschimbata evita nevoia de redirectionari de legare, inseamna ca numai o versiune unica a ansamblului poate fi instalata in cache-ul Global Assembly (GAC). De asemenea, aplicatiile care fac referire la ansamblul din GAC se vor intrerupe daca o alta aplicatie actualizeaza ansamblul GAC cu modificari de rupere.

Versiunea fisierului de asamblare

Versiunea de fisier de asamblare este utilizata pentru a afisa o versiune de fisier in Windows si nu are niciun efect asupra comportamentului in timpul rularii. Setarea acestei versiuni este optionala. Este vizibil in dialogul Proprietati fisier din Windows Explorer:

<FileVersion> 11.0.2.21924 </FileVersion>

✔️ Luati in considerare includerea unui numar de constructie de integrare continua ca versiune AssemblyFileVersion.

De exemplu, construiti versiunea 1.0.0 a proiectului dvs., iar numarul de constructie de integrare continua este 99, astfel incat AssemblyFileVersion este 1.0.0.99.

✔️ Folositi formatul Major.Minor.Build.Revision pentru versiunea fisierului.

In timp ce versiunea de fisier nu este folosita niciodata de .NET, Windows se asteapta ca versiunea de fisier sa fie in format Major.Minor.Build.Revision. Se avertizeaza daca versiunea nu urmeaza acest format.

Versiune informativa de asamblare

Versiunea informationala de asamblare este utilizata pentru a inregistra informatii suplimentare despre versiune si nu are niciun efect asupra comportamentului de executie. Setarea acestei versiuni este optionala. Daca utilizati Source Link, aceasta versiune va fi setata pe versiunea build cu versiunea pachetului NuGet plus o versiune de control sursa. De exemplu, 1.0.0-beta1 + 204ff0a include hash-ul commit al codului sursa din care a fost construit ansamblul. Pentru mai multe informatii, consultati Link sursa.

<InformationalVersion> Vulpea bruna si rapida a sarit peste cainele lenes. </InformationalVersion>

❌ EVITATI sa setati singur versiunea informationala de asamblare.

Permiteti SourceLink sa genereze automat versiunea care contine NuGet si metadatele de control sursa.