Introduction
When you are working on a project in DOTNET, you may need to add packages to your project just like using npm
in Node.js or pip
in Python. In DOTNET, you can use NuGet
to add packages to your project. Read about nuget from the resources and tools.
Adding a package to a .Net application
Adding a package to a .Net application
- The GIF above shows how to add a package to a .Net by searching and installing the package from the NuGet website.
- You can also add a package to your project using the terminal.
- Open the terminal and navigate to the project directory.
- Run the following command to add a package to your project:
1
| dotnet add package <package-name>
|
- Example - The “Password Generator” package
1
| dotnet add package PasswordGenerator --version 2.1.0
|
- The above command will add the “Password Generator” package to your project with version 2.1.0.
- In your VS Code, you can see the package added to your project in the
Dependencies
section.
Using the package in your project
- Once you have added the package to your project, you can use it in your project.
- You can import the package in your project using the
using
keyword. - Example - Using the “Password Generator” package
1
| using PasswordGenerator;
|
Manage dependency updates in your .NET project
- Sometimes, you may need to update the packages in your project.
- Updates are necessary to get the latest features and bug fixes.
- Here are some suggested ways to manage dependency updates in your .NET project:
Use semantic versioning
- Semantic versioning is a versioning system that specifies the version of a package based on the changes made to it.
- Semantic versioning works by ensuring that a package has a version number, and that the version number is divided into these sections:
- Major version: The leftmost number.
- For example, it’s the 1 in
1.0.0
. - A change to this number means that you can expect breaking changes in code.
- You might need to rewrite part of your code.
- Minor version: The middle number.
- For example, it’s the 2 in
1.2.0
. - A change to this number means that features have been added.
- Your code should still work.
- It’s generally safe to accept the update.
- Patch version: The rightmost number.
- For example, it’s the 3 in
1.2.3
. - A change to this number means that a change has been applied that fixes something in the code that should have worked.
- It should be safe to accept the update.
- This table illustrates how the version number changes for each version type:
Version type | What happens | Description |
---|
Major version | 1.0.0 -> 2.0.0 | Breaking changes |
Minor version | 1.0.0 -> 1.1.0 | Features added |
Patch version | 1.0.0 -> 1.0.1 | Bug fixes |
Use the “Update approach”
- The “Update approach” is a method of updating packages in your project in terms of risk.
- Major version: I’m OK with updating to the latest major version as soon as it’s out. I accept the fact that I might need to change code on my end.
- Minor version: I’m OK with a new feature being added. I’m not OK with code that breaks.
- Patch version: The only updates I’m OK with are bug fixes.
- In general, the smaller the dependency you’re updating, the fewer dependencies it has and the more likely that the update process will be easy.
- NuGet has the concepts of version ranges and floating versions when it comes to updating packages.
- Version ranges: Is a special notation that’s used for specifying specific version ranges that you want to have resolved as shown in the table below:
Notation | Applied rule | Description |
---|
1.0 | x >= 1.0 | Minimum version, inclusive |
(1.0,) | x > 1.0 | Minimum version, exclusive |
[1.0] | x == 1.0 | Exact version match |
(,1.0] | x <= 1.0 | Maximum version, inclusive |
(,1.0) | x < 1.0 | Maximum version, exclusive |
[1.0,2.0] | 1.0 <= x <= 2.0 | Exact range, inclusive |
(1.0,2.0) | 1.0 < x < 2.0 | Exact range, exclusive |
[1.0,2.0) | 1.0 <= x < 2.0 | Mixed inclusive minimum and exclusive maximum version |
(1.0) | invalid | invalid |
- Floating versions: using a floating version notation for major, minor, patch, and pre-release suffix parts of the number.
- This notation is an asterisk (*).
- For example, the version specification
6.0.*
says “use the latest 6.0.x version.” - In another example,
4.*
means “use the latest 4.x version.” - Using a floating version reduces changes to the project file while keeping up to date with the latest version of a dependency.
- When you’re using a floating version, NuGet resolves the latest version of a package that matches the version pattern.
- It is recommended to install a specific version instead of using any of the floating notations.
- Installing a specific version ensures that your builds are repeatable unless you explicitly request an update to a dependency.
- Here are some examples that can configure for major, minor, or patch version:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
| <!-- 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)" />
|
Find and update outdated packages
- The
dotnet list package --outdated
command lists outdated packages. - This command can help you learn when newer versions of packages are available. Here’s a typical output from the command:
1
2
| Top-level Package Requested Resolved Latest
> Humanizer 2.7.* 2.7.9 2.8.26
|
- Here are the meanings of the names of the columns in the output:
- Requested: The version or version range that you’ve specified.
- Resolved: The actual version that’s been downloaded for the project that matches the specified version.
- Latest: The latest version available for update from NuGet.
- The recommended workflow is to run the following commands, in this order:
- Run
dotnet list package --outdated
.- This command lists all the outdated packages.
- It provides information in the Requested, Resolved, and Latest columns.
- Run dotnet
add package <package name>
.- If you run this command, it will try to update to the latest version.
- Optionally, you can pass in
--version=<version number/range>
. For example dotnet add package Humanizer --version 2.11.10
.