Heroku Cloud Native Buildpack: .NET

heroku/dotnet is the Heroku Cloud Native Buildpack for .NET and ASP.NET Core applications. It builds .NET and ASP.NET Core application source code into application images with minimal configuration.

Important

This is a Cloud Native Buildpack, and is a component of the Heroku Cloud Native Buildpacks project, which is in preview. If you are instead looking for the Heroku Classic Buildpack for .NET (for use on the Heroku platform), you may find it here.

Usage

Note

Before getting started, ensure you have the pack CLI installed. Installation instructions are available here.

To build a .NET application codebase into a production image:

$ cd ~/workdir/sample-dotnet-app
$ pack build sample-app --builder heroku/builder:24

Then run the image:

docker run --rm -it -e "PORT=8080" -p 8080:8080 sample-app

Application Requirements

A solution file (e.g. MySolution.sln or MySolution.slnx) or .NET project file (e.g. *.csproj, *.vbproj or *.fsproj) must be present in the application’s root directory. If the root directory contains both solution and project files, the solution file will be preferred for the build and publish process.

The buildpack support C#, Visual Basic and F# projects using the .NET and ASP.NET Core frameworks (version 8.0 and up).

Configuration

.NET Version

By default, the buildpack will install the latest available .NET SDK based on the value of the TargetFramework property, which must be set in each project file. TFM values that follow the net{major_version}.0 format are currently supported (e.g. net6.0, net7.0, net8.0). If a solution references projects that target different framework versions, the most recent version will be preferred when inferring the .NET SDK version to install.

To install a different .NET SDK version, add a global.json file to the root directory. The buildpack supports specifying both the version and rollForward policy to define which .NET SDK version to install. For instance, to install a specific version a global.json file may look like this:

{
  "sdk": {
    "version": "8.0.106",
    "rollForward": "disable"
  }
}

A complete inventory of supported .NET SDK versions and platforms is available here.

Solution File

By default, the buildpack automatically detects the solution or project file to build and publish. However, if your codebase contains multiple solution files in the root directory, you must specify which one to use.

You can configure the solution file using either an environment variable or a project.toml file.

Using Environment Variable

Set the SOLUTION_FILE environment variable during build:

$ pack build sample-app \
    --env "SOLUTION_FILE=foo.sln" \
    --builder heroku/builder:24

Using project.toml

Alternatively, create a project.toml file in the root of your project:

[_]
schema-version = "0.2"

[com.heroku.buildpacks.dotnet]
solution_file = "foo.sln"

Note

If you use both an environment variable and a project.toml file, the environment variable will take precedence.

MSBuild

The recommended way to customize MSBuild is by creating a project.toml file in the root of your project. This allows you to change the default build configuration, Release, and the default verbosity level, minimal.

[_]
schema-version = "0.2"

[com.heroku.buildpacks.dotnet.msbuild]
configuration = "Debug"
verbosity = "quiet"

Alternatively, you can use the BUILD_CONFIGURATION and MSBUILD_VERBOSITY_LEVEL environment variables during build.

To build using a Debug build configuration and detailed verbosity level:

$ pack build sample-app \
    --env "BUILD_CONFIGURATION=Debug" \
    --env "MSBUILD_VERBOSITY_LEVEL=detailed" \
    --builder heroku/builder:24

Note

If you use both a project.toml file and environment variables, the settings from the environment variables will take precedence.

Contributing

Issues and pull requests are welcome. See our contributing guidelines if you would like to help.