Verzování
Softwarová knihovna se zřídka dokončí ve verzi 1.0. Dobré knihovny se v průběhu času vyvíjejí, přidávají funkce, opravuje chyby a vylepšuje výkon. Je důležité, abyste mohli vydávat nové verze knihovny .NET bez přerušení stávajících uživatelů.
Zásadní změny
Informace o zpracování zásadních změn mezi verzemi naleznete v tématu Zásadní změny.
Čísla verzí
Knihovna .NET má mnoho způsobů, jak zadat verzi. Nejdůležitější jsou tyto verze:
Verze balíčku NuGet
verze balíčku NuGet se zobrazí na NuGet.org a ve správci balíčků NuGet sady Visual Studio a při použití balíčku se přidá do zdrojového kódu. Verze balíčku NuGet je číslo verze, které uživatelé běžně uvidí, a když mluví o verzi knihovny, kterou používají, na ni budou odkazovat. Verze balíčku NuGet je používána NuGetem a nemá žádný vliv na chování při běhu aplikace.
<PackageVersion>1.0.0-alpha1</PackageVersion>
Identifikátor balíčku NuGet v kombinaci s verzí balíčku NuGet slouží k identifikaci balíčku v NuGetu. Například Newtonsoft.Json
+ 11.0.2
. Balíček s příponou je předem připravený balíček a má speciální chování, které je ideální pro testování. Další informace najdete v tématu předběžné verze balíčků.
Vzhledem k tomu, že verze balíčku NuGet je nejviditelnější verzí pro vývojáře, je vhodné ji aktualizovat pomocí sémantické správy verzí (SemVer). SemVer označuje význam změn mezi verzemi a pomáhá vývojářům učinit informované rozhodnutí při výběru verze, kterou chcete použít. Například přechod z 1.0
na 2.0
značí, že existují potenciálně zásadní změny.
✔️ Zvažte použití SemVer 2.0.0 k verzi balíčku NuGet.
✔️ Použijte verzi balíčku NuGet ve veřejné dokumentaci, protože se jedná o číslo verze, které uživatelé běžně uvidí.
✔️ Při vydání nestabilního balíčku je třeba zahrnout předběžnou příponu. (Další informace o označení rozhraní API ve verzi Preview nebo experimentální najdete v tématu rozhraní API verze Preview.)
Uživatelé se musí přihlásit k získání předběžných balíčků, aby pochopili, že balíček není úplný.
Verze sestavení
Verze sestavení je to, co modul CLR používá za běhu k výběru verze sestavení, která se má načíst. Výběr sestavení pomocí správy verzí se vztahuje pouze na sestavení se silným názvem.
<AssemblyVersion>1.0.0.0</AssemblyVersion>
.NET Framework CLR vyžaduje přesnou shodu pro načtení sestavení se silným názvem. Například Library1, Version=1.0.0.0
byl zkompilován s odkazem na Newtonsoft.Json, Version=11.0.0.0
. Rozhraní .NET Framework načte pouze tuto přesnou verzi 11.0.0.0
. Aby bylo možné za běhu načíst jinou verzi, musí být do konfiguračního souboru aplikace .NET přidáno přesměrování vazby.
Silné pojmenování v kombinaci s verzí sestavení umožňuje striktní načítání verzí sestavení. I když silné jmenné identifikátory knihovny přinášejí několik výhod, často vedou k výjimkám při běhu, kdy nelze najít sestavení, a vyžaduje přesměrování vazby v app.config
nebo web.config
k opravě. V .NET (Core) je načítání sestavení uvolněnější. Modul běhového prostředí .NET (Core) automaticky načte sestavení s vyšší verzí při spuštění.
✔️ ZVAŽTE pouze zahrnutí hlavní verze v AssemblyVersion.
Například Knihovna 1.0 a Knihovna 1.0.1 oba mají AssemblyVersion
1.0.0.0
, zatímco Knihovna 2.0 má AssemblyVersion2.0.0.0
. Když se verze sestavení mění méně často, dochází ke snížení přesměrování vazeb.
✔️ ZVAŽTE zachování hlavního čísla verze AssemblyVersion a verze balíčku NuGet v synchronizaci.
AssemblyVersion je součástí některých informačních zpráv zobrazených uživateli, například název sestavení a názvy kvalifikovaných typů sestavení ve zprávách výjimek. Udržování vztahu mezi verzemi poskytuje vývojářům další informace o tom, jakou verzi používají.
❌ NEMAJÍ pevnou verzi AssemblyVersion.
I když se beze změny AssemblyVersion vyhne nutnosti přesměrování vazby, znamená to, že do globální mezipaměti sestavení (GAC) lze nainstalovat pouze jednu verzi sestavení. Také aplikace, které odkazují na sestavení v GAC, přestanou fungovat, pokud jiná aplikace aktualizuje sestavení GAC zásadními změnami.
Verze souboru sestavení
Verze souboru sestavení se používá k zobrazení verze souboru ve Windows a nemá žádný vliv na chování za běhu. Nastavení této verze je volitelné. Je viditelný v dialogovém okně Vlastnosti souboru v Průzkumníku Windows:
<FileVersion>11.0.2.21924</FileVersion>
✔️ ZVAŽTE zahrnout číslo sestavení z kontinuální integrace jako revizi pro AssemblyFileVersion.
Například vytváříte projekt verze 1.0.0 a číslo sestavení kontinuální integrace je 99, takže assemblyFileVersion je 1.0.0.99.
✔️ Použijte formát Major.Minor.Build.Revision
pro verzi souboru.
I když rozhraní .NET verzi souboru nikdy nepoužívá, Systém Windows očekává, že verze souboru bude ve formátu
Major.Minor.Build.Revision
. Upozornění se vyvolá, pokud verze tento formát nedodržuje.
Informační verze pro sestavení
Informační verze sestavení slouží k zaznamenání dalších informací o verzi a nemá žádný vliv na chování modulu runtime. Nastavení této verze je volitelné. Pokud používáte Source Link, tato verze bude nastavena během sestavení s verzí balíčku NuGet a verzí systému správy zdrojového kódu. Například 1.0.0-beta1+204ff0a
zahrnuje hash potvrzení zdrojového kódu, ze kterého bylo sestavení vytvořeno. Další informace najdete v odkazu na zdroj .
<InformationalVersion>The quick brown fox jumped over the lazy dog.</InformationalVersion>
Poznámka
Starší verze sady Visual Studio vyvolají upozornění na sestavení, pokud tato verze neodpovídá formátu Major.Minor.Build.Revision
. Upozornění je možné bezpečně ignorovat.
❌ VYHNĚTE se nastavení informační verze sestavení sami.
Povolit SourceLink automaticky generovat verzi obsahující NuGet a metadata správy zdrojového kódu.