Post

Adding packages to DOTNET

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 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 typeWhat happensDescription
Major version1.0.0 -> 2.0.0Breaking changes
Minor version1.0.0 -> 1.1.0Features added
Patch version1.0.0 -> 1.0.1Bug 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.

Configure the project file for updates

  • 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:
NotationApplied ruleDescription
1.0x >= 1.0Minimum version, inclusive
(1.0,)x > 1.0Minimum version, exclusive
[1.0]x == 1.0Exact version match
(,1.0]x <= 1.0Maximum version, inclusive
(,1.0)x < 1.0Maximum version, exclusive
[1.0,2.0]1.0 <= x <= 2.0Exact range, inclusive
(1.0,2.0)1.0 < x < 2.0Exact range, exclusive
[1.0,2.0)1.0 <= x < 2.0Mixed inclusive minimum and exclusive maximum version
(1.0)invalidinvalid
  • 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:
    1. Run dotnet list package --outdated.
      • This command lists all the outdated packages.
      • It provides information in the Requested, Resolved, and Latest columns.
    2. 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.
This post is licensed under CC BY 4.0 by the author.