Versiebeheer

Een softwarebibliotheek is zelden volledig in versie 1.0. Goede bibliotheken ontwikkelen zich in de loop van de tijd, voegen functies toe, lossen bugs op en verbeteren van de prestaties. Het is belangrijk dat u nieuwe versies van een .NET-bibliotheek kunt vrijgeven, met extra waarde voor elke versie, zonder dat bestaande gebruikers worden onderbroken.

Wijzigingen die fouten veroorzaken

Zie Belangrijke wijzigingen voor informatie over het afhandelen van belangrijke wijzigingen tussen versies.

Versienummers

Een .NET-bibliotheek heeft veel manieren om een versie op te geven. Deze versies zijn de belangrijkste:

NuGet-pakketversie

De NuGet-pakketversie wordt weergegeven op NuGet.org, Visual Studio NuGet-pakketbeheer en wordt toegevoegd aan broncode wanneer het pakket wordt gebruikt. De NuGet-pakketversie is het versienummer dat gebruikers vaak zien en ze verwijzen ernaar wanneer ze praten over de versie van een bibliotheek die ze gebruiken. De NuGet-pakketversie wordt gebruikt door NuGet en heeft geen invloed op runtimegedrag.

<PackageVersion>1.0.0-alpha1</PackageVersion>

De NuGet-pakket-id in combinatie met de NuGet-pakketversie wordt gebruikt om een pakket in NuGet te identificeren. Bijvoorbeeld: Newtonsoft.Json + 11.0.2. Een pakket met achtervoegsel is een pre-release-pakket en heeft speciaal gedrag waardoor het ideaal is voor testen. Zie Pre-releasepakketten voor meer informatie.

Omdat de NuGet-pakketversie de meest zichtbare versie is voor ontwikkelaars, is het een goed idee om deze bij te werken met behulp van Semantic Versioning (SemVer). SemVer geeft de betekenis van wijzigingen tussen de release aan en helpt ontwikkelaars bij het kiezen van welke versie moet worden gebruikt. Als u bijvoorbeeld van 1.02.0 waaruit blijkt dat er mogelijk wijzigingen zijn die fouten veroorzaken.

✔️ OVERWEEG om SemVer 2.0.0 te gebruiken om uw NuGet-pakket te versiebeheer.

✔️ Gebruik de NuGet-pakketversie in openbare documentatie omdat dit het versienummer is dat gebruikers vaak zullen zien.

✔️ NEEM een achtervoegsel voor de voorlopige release op bij het vrijgeven van een niet-stabiel pakket.

Gebruikers moeten ervoor kiezen om voorlopige pakketten te krijgen, zodat ze begrijpen dat het pakket niet volledig is.

Assemblyversie

De assemblyversie is wat de CLR tijdens runtime gebruikt om te selecteren welke versie van een assembly moet worden geladen. Het selecteren van een assembly met versiebeheer is alleen van toepassing op assembly's met een sterke naam.

<AssemblyVersion>1.0.0.0</AssemblyVersion>

De .NET Framework CLR vereist een exacte overeenkomst om een sterk benoemde assembly te laden. Is bijvoorbeeld Library1, Version=1.0.0.0 gecompileerd met een verwijzing naar Newtonsoft.Json, Version=11.0.0.0. .NET Framework laadt alleen die exacte versie 11.0.0.0. Als u een andere versie tijdens runtime wilt laden, moet er een bindingsomleiding worden toegevoegd aan het configuratiebestand van de .NET-toepassing.

Sterke naamgeving in combinatie met assemblyversie maakt het laden van de assemblyversie strikt mogelijk. Hoewel het sterk benoemen van een bibliotheek een aantal voordelen heeft, resulteert dit vaak in runtime-uitzonderingen die niet kunnen worden gevonden en vereist bindingsomleidingen in app.config of web.config moeten worden opgelost. In .NET Core is het laden van assembly's meer ontspannen. De .NET Core-runtime laadt automatisch assembly's met een hogere versie tijdens runtime.

✔️ OVERWEEG alleen een primaire versie in de AssemblyVersion op te nemen.

Bibliotheek 1.0 en Bibliotheek 1.0.1 hebben bijvoorbeeld beide een AssemblyVersion van 1.0.0.0, terwijl Library 2.0 AssemblyVersion van 2.0.0.0heeft. Wanneer de assemblyversie minder vaak verandert, vermindert het bindingsomleidingen.

✔️ OVERWEEG het primaire versienummer van de AssemblyVersion en de NuGet-pakketversie gesynchroniseerd te houden.

De AssemblyVersion is opgenomen in enkele informatieve berichten die worden weergegeven aan de gebruiker, bijvoorbeeld de assemblynaam en de namen van het gekwalificeerde assemblytype in uitzonderingsberichten. Het onderhouden van een relatie tussen de versies biedt ontwikkelaars meer informatie over welke versie ze gebruiken.

❌ GEEN vaste AssemblyVersion hebben.

Hoewel een onveranderlijke AssemblyVersion de noodzaak van bindingsomleidingen vermijdt, betekent dit dat slechts één versie van de assembly kan worden geïnstalleerd in de Global Assembly Cache (GAC). De toepassingen die naar de assembly in de GAC verwijzen, worden ook verbroken als een andere toepassing de GAC-assembly bijwerkt met wijzigingen die fouten veroorzaken.

Assemblybestandsversie

De versie van het assemblybestand wordt gebruikt om een bestandsversie in Windows weer te geven en heeft geen effect op runtimegedrag. Het instellen van deze versie is optioneel. Dit is zichtbaar in het dialoogvenster Bestandseigenschappen in Windows Verkenner:

<FileVersion>11.0.2.21924</FileVersion>

✔️ OVERWEEG een buildnummer voor continue integratie op te nemen als assemblyfileVersion-revisie.

U bouwt bijvoorbeeld versie 1.0.0 van uw project en het buildnummer voor continue integratie is 99, zodat uw AssemblyFileVersion 1.0.0.99 is.

✔️ Gebruik de indeling Major.Minor.Build.Revision voor de bestandsversie.

Hoewel de bestandsversie nooit wordt gebruikt door .NET, verwacht Windows dat de bestandsversie de Major.Minor.Build.Revision indeling heeft. Er wordt een waarschuwing weergegeven als de versie deze indeling niet volgt.

Informatieversie van assembly

De informatieversie van de assembly wordt gebruikt om aanvullende versiegegevens vast te leggen en heeft geen invloed op runtimegedrag. Het instellen van deze versie is optioneel. Als u Source Link gebruikt, wordt deze versie ingesteld op build met de NuGet-pakketversie plus een broncodebeheerversie. Bevat bijvoorbeeld 1.0.0-beta1+204ff0a de doorvoer-hash van de broncode waaruit de assembly is gebouwd. Zie Bronkoppeling voor meer informatie.

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

Notitie

Oudere versies van Visual Studio genereren een buildwaarschuwing als deze versie niet de indeling Major.Minor.Build.Revisionvolgt. De waarschuwing kan veilig worden genegeerd.

❌ VERMIJD het zelf instellen van de informatieversie van de assembly.

Sta SourceLink toe om automatisch de versie met NuGet- en broncodebeheermetagegevens te genereren.

VorigeVolgende