.NET Bumper ⛐📦⤴️✨

[!NOTE] This project is currently experimental.

Overview

.NET Bumper is a .NET Global Tool to upgrade projects to a newer version of .NET.

.NET Bumper in action

Bumper helps you upgrade your .NET projects to a newer version by taking care of some of the steps required to move from one version to another. Bumper supports upgrading to both Long Term Support (LTS) and Standard Term Support (STS) versions of .NET, and the latest preview versions of .NET. 🚀

Steps the tool can perform on your behalf include:

Updating the .NET SDK version in global.json 🧑‍💻
Upgrading the Target Framework of your project files ⚙️
Upgrading .NET, ASP.NET Core and EFCore NuGet packages to the appropriate versions 📦
Updating image tags in Dockerfiles 🐳
Running dotnet test to validate the upgrade 🧪

[!NOTE] Upgrades are made on a best-effort basis. You should always review the changes made by the tool and test any changes made to validate the upgrade.

Quick Start

To install the tool and upgrade a .NET 6 or later project to the latest Long Term Support (LTS) version of .NET, run the following command:

dotnet tool install --global MartinCostello.DotNetBumper
dotnet bumper .

Usage

For a full list of options, run dotnet bumper --help.

An example of the output is shown below.

Examples

Upgrade a project to the current LTS version of .NET

dotnet bumper ~/projects/awesome-project

Upgrade a project to the latest version of .NET

dotnet bumper ~/projects/awesome-project --upgrade-type Latest

Upgrade a project to the preview version of .NET

dotnet bumper ~/projects/awesome-project --upgrade-type Preview

Upgrade a project to a specific version of .NET

dotnet bumper ~/projects/awesome-project --channel 8.0

Upgrade a project to the current LTS version of .NET and then run dotnet test after the upgrade has completed

dotnet bumper ~/projects/awesome-project --test

Options

> dotnet bumper --help
Upgrades projects to a newer version of .NET.

Usage: dotnet bumper [options] <ProjectPath>

Arguments:
  ProjectPath                      The path to directory containing a .NET 6+ project to be upgraded. If not specified,
                                   the current directory will be used.

Options:
  -v|--verbose                     Show verbose output
  --version                        Show version information.
  -?|-h|--help                     Show help information.
  -cf|--configuration-file <PATH>  The path to a custom JSON or YAML configuration file to use, if any.
  -c|--channel <CHANNEL>           The .NET release channel to upgrade to in the format "major.minor".
  -lf|--log-format <FORMAT>        The log format to use.
                                   Allowed values are: None, Json, Markdown, GitHubActions.
                                   Default value is: None.
  -lp|--log-path <PATH>            The path to write the log file to, if any.
  -q|--no-logo                     Do not display the startup banner.
  -t|--upgrade-type <TYPE>         The type of upgrade to perform.
                                   Allowed values are: Lts, Latest, Preview.
  -test|--test                     Test the upgrade by running dotnet test on completion.
  -timeout|--timeout <TIMESPAN>    The optional period to timeout the upgrade after.
  -e|--warnings-as-errors          Treat any warnings encountered during the upgrade as errors.

Custom Configuration File

A custom configuration file can be used to specify some additional options to change the behaviour of Bumper for a specific repository. The possible options are documented in the schema file. The format of the file can be either JSON or YAML.

Bumper automatically loads the configuration file from directory containing the project to upgrade if one of the following files is found:

.dotnet-bumper.json
.dotnet-bumper.yml
.dotnet-bumper.yaml

The file can also be explicitly specified using the --configuration-file option.

An example JSON and YAML configuration file are shown below:

{
  "$schema": "https://raw.githubusercontent.com/martincostello/dotnet-bumper/main/dotnet-bumper-schema.json",
  "excludeNuGetPackages": [
    "System.Text.Json"
  ],
  "includeNuGetPackages": [
    "Npgsql"
  ],
  "noWarn": [
    "NU1605"
  ],
  "remainingReferencesIgnore": [
    "tools/*"
  ]
}

excludeNuGetPackages:
  - System.Text.Json
includeNuGetPackages:
  - Npgsql
noWarn:
  - NU1605
remainingReferencesIgnore:
  - "tools/*"

Pre-requisites

.NET 8 must be installed to use the tool
- The .NET SDK version to upgrade to must also be installed if this is different
The dotnet-outdated .NET Global tool must also be installed
Any project being upgraded must already target at least .NET 6

Questions

An FAQ document for .NET Bumper is available here.

Building and Testing

Compiling the application yourself requires Git and the .NET SDK to be installed.

To build and test the application locally from a terminal, run the following set of commands:

git clone https://github.com/martincostello/dotnet-bumper.git
cd dotnet-bumper
dotnet tool restore
./build.ps1

Feedback

Any feedback or issues can be added to the issues for this project in GitHub.

Repository

The repository is hosted in GitHub: https://github.com/martincostello/dotnet-bumper.git

License

This project is licensed under the Apache 2.0 license.

martincostello / dotnet-bumper

readme