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 zonder bestaande gebruikers te breken.
Belangrijke wijzigingen
Zie Onderbrekende wijzigingenvoor informatie over het afhandelen van wijzigingen die functionaliteit tussen versies kunnen verstoren.
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 en 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 prereleasepakket en heeft speciaal gedrag waardoor het ideaal is voor testen. Voor meer informatie, zie prereleasepakketten .
Omdat de NuGet-pakketversie de meest zichtbare versie is voor ontwikkelaars, is het een goed idee om het bij te werken met behulp van Semantic Versioning (SemVer). SemVer geeft de betekenis van wijzigingen tussen releases aan en helpt ontwikkelaars bij het nemen van een weloverwogen beslissing bij het kiezen van de versie die moet worden gebruikt. Bijvoorbeeld, als u van 1.0 naar 2.0 gaat, duidt dit erop dat er mogelijk brekende wijzigingen zijn.
✔️ 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 prereleaseachtervoegsel op bij het vrijgeven van een nonstable-pakket. (Zie Preview-API'svoor meer informatie over het markeren van API's als preview of experimenteel.
Gebruikers moeten zich aanmelden voor het ophalen van voorlopige pakketten, 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 match om een assembly met een sterke naam te laden.
Library1, Version=1.0.0.0 is bijvoorbeeld 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 strikte assemblyversie ladenmogelijk. Hoewel sterke naamgeving van een bibliotheek een aantal voordelen heeft, resulteert dit vaak in runtime-uitzonderingen die niet kunnen worden gevonden en bindingsomleidingen vereist in app.config of web.config moeten worden opgelost. In .NET (Core) is het laden van assembly's meer ontspannen. De .NET-runtime (Core) laadt automatisch assembly's met een hogere versie tijdens runtime.
✔️ OVERWEEG alleen een hoofversie 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 van2.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 naam van de assembly en de gekwalificeerde typenamen van de assembly in foutmeldingen. 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, zullen ook niet meer werken als een andere toepassing de GAC-assembly bijwerkt met wijzigingen die onderbrekingen 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.
Informatieve versie 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.
1.0.0-beta1+204ff0a bevat bijvoorbeeld de doorvoer-hash van de broncode waaruit de assembly is gebouwd. Zie Source Linkvoor 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.
