Skip to content

NuGet packages

Jump to bottom
Rikkert01 edited this page Jul 23, 2026 · 13 revisions

EII uses NuGet packages to share libraries. You can add a version to a library so people can develop within a stable context.

SemVer

Semantic Versioning (SemVer) is used for package versions: MAJOR.MINOR.PATCH

MAJOR version: when you make incompatible API changes MINOR version: when you add functionality in a backward-compatible way PATCH version: when you make backward-compatible bug fixes

(See also [semver.org](ook https://semver.org/), GitVersion docs, or Microsoft NuGet docs

So when you fix a bug or implement something without changing the interface, you only need to increase the PATCH version. This is basically the case for every PR that gets merged, except when the interface changes. In that case, the MINOR or even the MAJOR version should be increased. More about package dependency resolution at learn.microsoft.com/en-us/nuget/concepts/dependency-resolution

Wildcards

To avoid having to update the consuming packages with a new package reference (e.g., from 1.0.4 to 1.0.5), you can use a wildcard. Example:

<PackageReference Include="Your.Package.Name" Version="1.0.*-*"/>

image

Here, *-* means the latest PATCH version and any prerelease tags will be used. Examples of prerelease tags:

1.0.32-2 1.0.0-alpha

We probably don’t need to use prerelease tags for now. When the MINOR or MAJOR version changes, the PATCH (and MINOR in case of a higher MAJOR) resets to 0. (Gaps in version numbers are allowed.)

An example:

image

Version Bumping

To bump a MINOR or MAJOR version, you can include the following commands in your commit message:

  • +semver: major → increases MAJOR
  • +semver: minor → increases MINOR
  • +semver: patch → increases PATCH

If you only make backward-compatible changes, you only need to increase the PATCH version. No command is needed in the commit message for that. But if you want to bump the MINOR, include +semver: minor in your commit message. (This can be placed anywhere in the message.)

Example:

image

This would result in the next version being something like 1.4.0. Note: You’ll need to update the consuming packages to:

<PackageReference Include="Eii.ValueChain.Storage" Version="1.4.*-*"/>

Multi target packages

A package can target different frameworks, like net48;net8.0

image

Transitive packages

When you add a package that references another package (which might in turn reference another package) you don't have to reference all packages. NuGet will figure out what other packages will be included: the "Transitive packages".

In this example the EwECore package has a reference to the EwEPlugin package, that in turn uses the EwEUtils package.

image

Add package sources

Nuget packages can come from many different places.

image

Where packages come from

  1. GitHub Packages (Official-EwE): all internal Eii.* packages are published to and restored from https://nuget.pkg.github.com/Official-EwE/index.json.
  2. Buf Schema Registry (BSR): BSR.* generated SDKs come from https://buf.build/gen/nuget/index.json.
  3. nuget.org: all other public dependencies.

This is enforced via packageSourceMapping in NuGet.config:

  1. Eii.* → github-Official-EwE
  2. BSR.* → BSR
  3. Everything else → nuget.org

Example of a Nuget.config

image

Getting BSR password

To access the BSR Package source you have to be able to log in to BSR. It's easiest to log in with your GitHub account:

image

Then go to the Grpc SDK page

Enter a descriptive name and click Create:

image

Copy the Username and the ClearPassword:

image

You now can use that password to ad to your nuget.config:

Adding package source secrets to your PC

The GitHub and BSR package sources are protected with secrets.

The NuGet.config file in the solution describes what package sources to use. It does not hold the secrets! So this file can be added to the Git repo.

To install the (PERSONAL) passwords encrypted on Windows, you must first remove them from C:\Users\<user>\AppData\Roaming\NuGet. Then you can use the following CLI command:

  • github-Official-EwE: dotnet nuget add source "https://nuget.pkg.github.com/Official-EwE/index.json" -n "github-Official-EwE" -u "<your-github-username>" -p "<your-PAT>"
  • BSR: dotnet nuget add source "https://buf.build/gen/nuget/index.json" -n "BSR" -u "<your-github-username>" -p "<your-BSR-Password>"

This changes the mother of all NuGet.config files which is stored in C:\Users\<user>\AppData\Roaming\NuGet. The secrets in this file are encrypted.

Note that a PAT can only be used on one computer; if you use multiple machines, each will need to have their own unique PAT installed

Clone this wiki locally