.NET Behavior in Heroku

Last updated December 03, 2024

The Heroku Platform and .NET buildpack has the following behavior for any type of .NET application deployed. For more details, view the .NET buildpack.

For detailed guidance on deploying a .NET application, see the Getting Started with .NET on Heroku (Classic) or Getting Started with .NET on Heroku (Fir).

Auto-Detection

Heroku automatically recognizes your app as a .NET app if it includes a *.sln, *.csproj, *.vbproj, or *.fsproj file in the root directory.

When Heroku recognizes a .NET application, you see this build output:

For apps with classic buildpacks:

$ git push heroku main
-----> .NET app detected

For apps with Cloud Native Buildpacks:

## Heroku .NET Buildpack

Build Behavior

An app can contain both solution (*.sln) and project files (*.csproj, *.vbproj, or *.fsproj) in the root directory. The buildpack selects files to publish based on the following rules:

  • Solution files are preferred over project files.
  • If the buildpack finds multiple solution files, it uses the first file sorted lexicographically. We recommend only having one solution file in the root directory.
  • If the buildpack detects multiple project files, it returns an error.

The buildpack builds and publishes the selected solution or project file using the dotnet publish command.

Build Configuration

The .NET buildpack adds the following parameters:

  • --runtime <rid>: Sets the Runtime Identifier (RID) to either linux-amd64 or linux-arm64 depending on the target platform.
  • -p:PublishDir=bin/publish: Sets the PublishDir MSBuild property to bin/publish ensuring consistent output location relative to the project file.

This configuration also facilitates writing Procfile commands compatible with any operating system, CPU architecture, build configuration such as Release and Debug, and Target Framework Moniker (TFM).

You can customize the default build configuration,Release, and MSBuild verbosity level, minimal, with the BUILD_CONFIGURATION and MSBUILD_VERBOSITY_LEVEL environment variables.

Classic Buildpacks

Configure environment variables in the Heroku Dashboard, or with the CLI:

heroku config:set BUILD_CONFIGURATION=Debug
heroku config:set MSBUILD_VERBOSITY_LEVEL=normal

Cloud Native Buildpacks

Configure environment variables in a project.toml file:

[_]
schema-version = "0.2"

[[io.buildpacks.build.env]]
name='BUILD_CONFIGURATION'
value='Debug'

[[io.buildpacks.build.env]]
name='MSBUILD_VERBOSITY_LEVEL'
value='normal'

NuGet Dependencies

The dotnet publish process restores NuGet dependencies. The buildpack caches restored packages in a global package cache and sets the NUGET_PACKAGES environment variable to point to a non-default location.

To prevent excessive cache growth, the cache is purged every 20 uses.

Automatic Process Type Detection

Heroku automatically adds process types for projects that reference a known “executable” project SDK, such as Microsoft.NET.Sdk.Web or Microsoft.NET.Sdk.Worker. To learn more about SDK-style projects, see the .NET project SDK documentation.

Process Registration

When the buildpack detects a supported project SDK, it registers a process type with:

  • The project name or the value of the AssemblyName project property
  • The path to the published executable as the command
    • For supported web apps, such as projects referencing Microsoft.NET.Sdk.Web and Microsoft.NET.Sdk.Razor SDKs, the --urls http://0.0.0.0:$PORT argument is appended to the command.

Supported Project SDKs

The following project SDKs support automatic process type registration:

  • Microsoft.NET.Sdk for projects with the OutputType property set to Exe
  • Microsoft.NET.Sdk.Worker
  • Microsoft.NET.Sdk.Web
  • Microsoft.NET.Sdk.Razor

Environment

Default Environment Variables

The .NET buildpack sets default values for the following environment variables:

Modified Environment Variables

The buildpack also modifies the following environment variables:

  • PATH: The .NET root directory is added to the PATH, allowing commands like dotnet to be executed without specifying the full path.

Process Type-Specific Environment Variables

  • PORT=<value>: Heroku sets the PORT environment variable for web process types. Use this value to configure the port for HTTP/web applications.

Customer Support

You can submit issues via one of the Heroku Support channels.

Additional Reading

Feedback

Log in to submit feedback.