.NET Behavior in Heroku

Last updated April 17, 2025

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.
  • --artifacts-path <temporary-directory>: Sets the artifacts path to a temporary directory. This doesn’t affect the actual path of published output when combined with the PublishDir setting described above, and is only configured to trim the published output by excluding intermediate build artifacts.

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 defined in project files.

For Fir-generation apps, 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.

.NET Tools

The buildpack automatically restores local .NET tools defined in .config/dotnet-tools.json, and configures them for use during build, publish and test (Heroku CI).

Automatic Process Type Detection

First, Heroku looks for a Procfile specifying your process types.

If no Procfile is present in the root directory of your app during the build process, 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. Details about detected process types are written to the build log.

Process Registration

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

  • The name web, when only a single web application is detected within a solution
  • The project name or the value of the AssemblyName project property
    • The name is lowercased, replacing spaces, dots (.), and underscores (_) with hyphens (-), and removing any other non-alphanumeric/special characters.
  • 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://*:$PORT argument is appended to the command.

To select or override the process types for your application, use a Procfile.

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.