Versionshantering

Ett programvarubibliotek är sällan färdigt i version 1.0. Bra bibliotek utvecklas med tiden, lägger till funktioner, åtgärdar buggar och förbättrar prestanda. Det är viktigt att du kan släppa nya versioner av ett .NET-bibliotek, vilket ger ytterligare värde för varje version, utan att bryta befintliga användare.

Icke-bakåtkompatibla ändringar

Information om hur du hanterar icke-bakåtkompatibla ändringar mellan versioner finns i Icke-bakåtkompatibla ändringar.

Versionsnummer

Ett .NET-bibliotek har många sätt att ange en version. Dessa versioner är de viktigaste:

NuGet-paketversion

NuGet-paketversionen visas på NuGet.org, Visual Studio NuGet-pakethanteraren, och läggs till i källkoden när paketet används. NuGet-paketversionen är det versionsnummer som användarna ofta ser, och de refererar till den när de pratar om versionen av ett bibliotek som de använder. NuGet-paketversionen används av NuGet och har ingen effekt på körningsbeteendet.

<PackageVersion>1.0.0-alpha1</PackageVersion>

NuGet-paketidentifieraren som kombineras med NuGet-paketversionen används för att identifiera ett paket i NuGet. Exempel: Newtonsoft.Json + 11.0.2 Ett paket med ett suffix är ett förhandsversionspaket och har ett särskilt beteende som gör det idealiskt för testning. Mer information finns i Förhandsversionspaket.

Eftersom NuGet-paketversionen är den mest synliga versionen för utvecklare är det en bra idé att uppdatera den med semantisk versionshantering (SemVer). SemVer anger betydelsen av ändringar mellan lanseringar och hjälper utvecklare att fatta ett välgrundat beslut när de väljer vilken version som ska användas. Om du till exempel går från 1.0 till 2.0 indikerar det att det finns potentiellt icke-bakåtkompatibla ändringar.

✔️ ÖVERVÄG att använda SemVer 2.0.0 för att version ditt NuGet-paket.

✔️ Använd NuGet-paketversionen i offentlig dokumentation eftersom det är det versionsnummer som användarna ofta ser.

✔️ Ta med ett suffix för förhandsversionen när du släpper ett icke-stabilt paket.

Användarna måste välja att hämta förhandsversionspaket, så att de förstår att paketet inte är klart.

Sammansättningsversion

Sammansättningsversionen är vad CLR använder vid körning för att välja vilken version av en sammansättning som ska läsas in. Att välja en sammansättning med versionshantering gäller endast för sammansättningar med ett starkt namn.

<AssemblyVersion>1.0.0.0</AssemblyVersion>

.NET Framework CLR kräver en exakt matchning för att läsa in en stark namngiven sammansättning. Kompilerades till exempel Library1, Version=1.0.0.0 med en referens till Newtonsoft.Json, Version=11.0.0.0. .NET Framework läser bara in den exakta versionen 11.0.0.0. Om du vill läsa in en annan version vid körning måste en bindningsomdirigering läggas till i .NET-programmets konfigurationsfil.

Stark namngivning i kombination med sammansättningsversion möjliggör strikt inläsning av sammansättningsversioner. Även om stark namngivning av ett bibliotek har ett antal fördelar, resulterar det ofta i körningsfel som en sammansättning inte kan hittas och kräver bindningsomdirigeringar i app.config eller web.config som ska åtgärdas. I .NET Core är monteringsinläsningen mer avslappnad. .NET Core-körningen läser automatiskt in sammansättningar med en högre version vid körning.

✔️ ÖVERVÄG endast att inkludera en huvudversion i AssemblyVersion.

Bibliotek 1.0 och Bibliotek 1.0.1 har till exempel båda en AssemblyVersion av 1.0.0.0, medan bibliotek 2.0 har AssemblyVersion av 2.0.0.0. När sammansättningsversionen ändras mindre ofta minskar bindningsomdirigeringar.

✔️ ÖVERVÄG att hålla huvudversionsnumret för AssemblyVersion och NuGet-paketversionen synkroniserade.

AssemblyVersion ingår i vissa informationsmeddelanden som visas för användaren, till exempel sammansättningsnamnet och sammansättningskvalificerade typnamn i undantagsmeddelanden. Att upprätthålla en relation mellan versionerna ger mer information till utvecklare om vilken version de använder.

❌ HA INTE en fast AssemblyVersion.

Även om en oföränderlig AssemblyVersion undviker behovet av bindningsomdirigeringar innebär det att endast en enda version av sammansättningen kan installeras i global sammansättningscache (GAC). Dessutom bryts de program som refererar till sammansättningen i GAC om ett annat program uppdaterar GAC-sammansättningen med icke-bakåtkompatibla ändringar.

Sammansättningsfilversion

Sammansättningsfilversionen används för att visa en filversion i Windows och har ingen effekt på körningsbeteendet. Det är valfritt att ange den här versionen. Den visas i dialogrutan Filegenskaper i Utforskaren:

<FileVersion>11.0.2.21924</FileVersion>

✔️ ÖVERVÄG att inkludera ett versionsnummer för kontinuerlig integrering som AssemblyFileVersion-revision.

Du skapar till exempel version 1.0.0 av projektet och versionsnumret för kontinuerlig integrering är 99, så din AssemblyFileVersion är 1.0.0.99.

✔️ Använd formatet Major.Minor.Build.Revision för filversionen.

Även om filversionen aldrig används av .NET förväntar sig Windows att filversionen är i Major.Minor.Build.Revision formatet. En varning utlöses om versionen inte följer det här formatet.

Informationsversion för sammansättning

Sammansättningsinformationsversionen används för att registrera ytterligare versionsinformation och har ingen effekt på körningsbeteendet. Det är valfritt att ange den här versionen. Om du använder Source Link ställs den här versionen in på build med NuGet-paketversionen plus en källkontrollversion. Innehåller till exempel 1.0.0-beta1+204ff0a incheckningshash för källkoden som sammansättningen skapades från. Mer information finns i Källlänk.

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

Kommentar

Äldre versioner av Visual Studio ger upphov till en byggvarning om den här versionen inte följer formatet Major.Minor.Build.Revision. Varningen kan ignoreras på ett säkert sätt.

❌ UNDVIK att ställa in sammansättningsinformationsversionen själv.

Tillåt SourceLink att automatiskt generera den version som innehåller NuGet- och källkontrollmetadata.

FöregåendeNästa