Dela via

Versionshantering

  • Artikel

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 utan att bryta befintliga användare.

Störande ändringar

Information om hur du hanterar brytande ändringar mellan versioner finns i Brytande ändringar.

Versionsnummer

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

NuGet-paketversion

NuGet-paketversion visas på NuGet.org och 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. Till 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. För mer information, se förhandsversionspaket .

Eftersom NuGet-paketversionen är den mest synliga versionen för utvecklare är det en bra idé att uppdatera den med Semantic Versioning (SemVer). SemVer anger betydelsen av ändringar mellan versioner 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 tyder det på att det finns potentiellt oförenliga ändringar.

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

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

✔️ Inkludera ett prerelease-suffix när du släpper ett icke-stabilt paket. (Mer information om hur du markerar API:er som förhandsversion eller experimentell finns i FÖRHANDSVERSIONS-API:er.)

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 Common Language Runtime (CLR) använder vid körning för att välja vilken version av ett assembly 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. Till exempel kompilerades 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. För att ladda 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 att en sammansättning inte kan hittas och kräver att bindningsomdirigeringar i app.config eller web.config åtgärdas. I .NET (Core) är assemblyinläsningen mer flexibel. .NET-körningen (Core) läser automatiskt in samlingar med en högre version under 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.

❌ HAR 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 kommer de applikationer som refererar till assemblyn i GAC att sluta fungera om en annan applikation uppdaterar GAC-assemblyn med oförenliga ä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>

Utforskaren i Windows

✔️ Ö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 filversion.

Även om filversionen aldrig används av .NET förväntar sig Windows att filversionen vara i Major.Minor.Build.Revision format. 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. Till exempel innehåller 1.0.0-beta1+204ff0a incheckningshash för källkoden som sammansättningen skapades från. Mer information finns i Source Link.

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

Not

Ä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