Updates van afhankelijkheden in uw .NET-project beheren

Voltooid

Eerder of later wilt u bijwerken naar een nieuwe versie van een bibliotheek. Misschien is een functie gemarkeerd als afgeschaft of is er een nieuwe functie in een latere versie van een pakket dat u gebruikt.

Er zijn enkele overwegingen waarmee u rekening moet houden voordat u een bibliotheek bijwerkt:

• Het type update: Welk type update is beschikbaar? Is het een kleine bug fix? Voegt de update een nieuwe functie toe die u nodig hebt? Wordt uw code verbroken? U kunt het type update doorgeven met behulp van een systeem genaamd Semantic Versioning. De manier waarop het versienummer van de bibliotheek wordt uitgedrukt, communiceert met ontwikkelaars het type update waarmee ze te maken hebben.
• Of het project correct is geconfigureerd: u kunt uw .NET-project zo configureren dat u alleen de gewenste typen updates krijgt. U voert alleen een update uit als een specifiek type update beschikbaar is. We raden deze aanpak aan, omdat u geen verrassingen loopt.
• Beveiligingsproblemen: het beheren van de projectafhankelijkheden in de loop van de tijd houdt in dat u zich bewust bent van problemen die zich kunnen voordoen. Problemen kunnen ontstaan als er een beveiligingsprobleem wordt gedetecteerd. In het ideale voorbeeld worden patches uitgebracht die u kunt downloaden. Het .NET Core-hulpprogramma helpt u bij het uitvoeren van een controle op uw bibliotheken om erachter te komen of u pakketten hebt die moeten worden bijgewerkt. Daarnaast kunt u hiermee de juiste actie ondernemen om een probleem op te lossen.

Semantic Versioning gebruiken

Er is een industriestandaard genaamd semantische versiebeheer. Dit is hoe u het type wijziging uitdrukt dat u of een andere ontwikkelaar introduceert in een bibliotheek. Semantische versiebeheer werkt door ervoor te zorgen dat een pakket een versienummer heeft en dat het versienummer in deze secties is verdeeld:

• Primaire versie: het meest linkse nummer. Het is bijvoorbeeld de 1 in 1.0.0. Een wijziging in dit nummer betekent dat u 'belangrijke wijzigingen' in uw code kunt verwachten. Mogelijk moet u een deel van de code herschrijven.
• Secundaire versie: het middelste getal. Het is bijvoorbeeld de 2 in 1.2.0. Een wijziging in dit nummer betekent dat er functies zijn toegevoegd. De code zou nog steeds moeten werken. Het is meestal veilig om de update te accepteren.
• Patchversie: het meest rechtse nummer. Het is bijvoorbeeld de 3 in 1.2.3. Een wijziging in dit nummer betekent dat er een wijziging is toegepast waarmee iets in de code wordt opgelost die moet werken. Het moet veilig zijn om de update te accepteren.

In deze tabel ziet u hoe het versienummer wordt gewijzigd voor elk versietype:

Type	Wat gebeurt
Primaire versie	1.0.0 wijzigingen in 2.0.0
Secundaire versie	1.1.1 wijzigingen in 1.2.0
Patchversie	1.0.1 wijzigingen in 1.0.2

Veel bedrijven en ontwikkelaars gebruiken dit systeem. Als u van plan bent om pakketten te publiceren en naar het NuGet-register te pushen, wordt verwacht dat u semantische versiebeheer volgt. Zelfs als u alleen pakketten downloadt uit het NuGet-register, kunt u ervan uitgaan dat deze pakketten Semantic Versioning volgen.

Wijzigingen in een pakket kunnen risico's introduceren, inclusief het risico dat een bug schadelijk kan zijn voor uw bedrijf. Voor sommige risico's moet u mogelijk een deel van uw code herschrijven. Het herschrijven van code kost tijd en geld.

Benadering van bijwerken

Als .NET-ontwikkelaar kunt u het updategedrag doorgeven dat u wilt .NET. Denk over bijwerken in termen van risico's. Hier volgen enkele benaderingen:

• Primaire versie: Ik ben in orde met het bijwerken naar de nieuwste primaire versie zodra deze is uitgeschakeld. Ik ga akkoord met het feit dat ik mogelijk code aan mijn kant moet wijzigen.
• Secundaire versie: Ik ben in orde met een nieuwe functie die wordt toegevoegd. Ik ga er niet mee akkoord dat er fouten in de code worden veroorzaakt.
• Patchversie: De enige updates waarmee ik in orde ben, zijn oplossingen voor fouten.

Als u een nieuw of kleiner .NET-project beheert, kunt u wat losser omgaan met het definiëren van de updatestrategie. U kunt bijvoorbeeld altijd bijwerken naar de nieuwste versie. Voor complexere projecten ligt het iets genuanceerder, maar we bewaren dat voor een toekomstige module.

Over het algemeen geldt dat hoe kleiner de afhankelijkheid die u bijwerkt, hoe minder afhankelijkheden het heeft en hoe waarschijnlijker het updateproces eenvoudig is.

Het projectbestand configureren voor bijwerken

Wanneer u een of meer afhankelijkheden toevoegt, configureert u het projectbestand zodat u voorspelbaar gedrag krijgt wanneer u uw project herstelt, bouwt of uitvoert. U kunt aangeven welke benadering u wilt gebruiken voor een pakket. NuGet heeft de concepten van versiebereiken en zwevende versies.

Versiebereiken zijn een speciale notatie die u kunt gebruiken om een specifiek bereik aan te geven van versies die u wilt oplossen.

Notatie	Toegepaste regel	Beschrijving
1.0	x >= 1,0	Minimumversie, inclusief
(1.0,)	x > 1.0	Minimumversie, exclusief
[1.0]	x == 1.0	Exact overeenkomende versie
(,1.0]	x ≤ 1.0	Maximumversie, inclusief
(,1.0)	x < 1.0	Maximumversie, exclusief
[1.0,2.0]	1.0 ≤ x ≤ 2.0	Exact bereik, inclusief
(1.0,2.0)	1.0 < x < 2.0	Exact bereik, exclusief
[1.0,2.0)	1.0 ≤ x < 2.0	Gemende inclusieve minimum- en exclusieve maximumversie
(1.0)	ongeldig	ongeldig

NuGet biedt ook ondersteuning voor het gebruik van een zwevende versienotatie voor primaire, secundaire, patch- en prereleaseachtervoegsels van het getal. Deze notatie is een sterretje (*). De versiespecificatie 6.0.* zegt bijvoorbeeld 'gebruik de nieuwste versie 6.0.x'. In een ander voorbeeld betekent 4.* 'gebruik de nieuwste 4.x-versie'. Het gebruik van een zwevende versie vermindert wijzigingen in het projectbestand terwijl u up-to-date blijft met de nieuwste versie van een afhankelijkheid.

Notitie

Het is aan te raden om een specifieke versie te installeren in plaats van een zwevende notatie te gebruiken. Als u een specifieke versie installeert, zorgt u ervoor dat uw builds herhaalbaar zijn, tenzij u expliciet een update voor een afhankelijkheid aanvraagt.

Wanneer u een zwevende versie gebruikt, vindt er met NuGet omzetting plaats naar de nieuwste versie van een pakket dat overeenkomt met het versiepatroon. In het volgende voorbeeld krijgt 6.0.* de nieuwste versie van een pakket dat begint met 6.0. Deze versie is 6.0.1.

Hier volgen enkele voorbeelden die u kunt configureren voor de primaire, secundaire of patchversie:

<!-- Accepts any version 6.1 and later. -->
<PackageReference Include="ExamplePackage" Version="6.1" />

<!-- Accepts any 6.x.y version. -->
<PackageReference Include="ExamplePackage" Version="6.*" />
<PackageReference Include="ExamplePackage" Version="[6,7)" />

<!-- Accepts any later version, but not including 4.1.3. Could be
     used to guarantee a dependency with a specific bug fix. -->
<PackageReference Include="ExamplePackage" Version="(4.1.3,)" />

<!-- Accepts any version earlier than 5.x, which might be used to prevent pulling in a later
     version of a dependency that changed its interface. However, we don't recommend this form because determining the earliest version can be difficult. -->
<PackageReference Include="ExamplePackage" Version="(,5.0)" />

<!-- Accepts any 1.x or 2.x version, but not 0.x or 3.x and later. -->
<PackageReference Include="ExamplePackage" Version="[1,3)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and later. -->
<PackageReference Include="ExamplePackage" Version="[1.3.2,1.5)" />

Verouderde pakketten zoeken en bijwerken

De dotnet list package --outdated-opdracht bevat verouderde pakketten. Met deze opdracht ontdekt u wanneer er nieuwere versies van pakketten beschikbaar zijn. Hier volgt een typische uitvoer van de opdracht:

Top-level Package      Requested   Resolved   Latest
> Humanizer            2.7.*       2.7.9      2.8.26

Hier volgt de betekenis van de kolomnamen in de uitvoer:

• Requested: de versie- of versiebereik die u hebt opgegeven.
• Resolved: De werkelijke versie die is gedownload voor het project dat overeenkomt met de opgegeven versie.
• Latest: De nieuwste versie die beschikbaar is voor update vanuit NuGet.

De aanbevolen werkstroom is om de volgende opdrachten uit te voeren, in deze volgorde:

1. Voer dotnet list package --outdated uit. Met deze opdracht worden alle verouderde pakketten weergegeven. Het bevat informatie in de kolommen Requested, Resolved en Latest.
2. Voer dotnet add package <package name> uit. Als u deze opdracht uitvoert, wordt geprobeerd om bij te werken naar de nieuwste versie. Eventueel kunt u daarbij --version=<version number/range> doorgeven.