.NET Behavior in Heroku

Last updated September 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 and Build Behavior

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

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

When the root directory contains multiple solution files, you must explicitly configure which one to build.

The buildpack uses the following order of precedence to select a build target:

  1. A solution file configured using config vars.
  2. A solution file configured using a project.toml file.
  3. A single solution file.
  4. A single project file.

Use config vars to deploy different solutions from the same repository to different Heroku apps. To set a consistent, repository-wide default solution, use the project.toml file.

If multiple solution files are detected without explicit configuration, the build fails. It also fails if no solution file is present, but multiple project files exist.

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

Build Configuration

You can customize default solution file, build configuration (Release) and MSBuild verbosity level (minimal) using either a project.toml file or config vars. If both are configured, config vars take precedence.

Using project.toml File

Create a project.toml file in your app’s root directory:

[_]
schema-version = "0.2"

# Specifies which solution file to build
[com.heroku.buildpacks.dotnet]
solution_file = "MyWebApp.sln"

# Customizes MSBuild settings
[com.heroku.buildpacks.dotnet.msbuild]
configuration = "Debug"
verbosity = "quiet"

Using Config Vars

Fir-generation apps must have the Build Time Config Vars Heroku Labs feature enabled to customize these settings using config vars.

Configure config vars in the Heroku Dashboard, or with the CLI:

heroku config:set SOLUTION_FILE=MyWebApp.sln
heroku config:set BUILD_CONFIGURATION=Debug
heroku config:set MSBUILD_VERBOSITY_LEVEL=normal

Publish Command Parameters

The .NET buildpack adds the following parameters when running dotnet publish:

  • --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 parameter doesn’t affect the actual path of published output when combined with the PublishDir setting, 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).

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 with 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 executable projects that reference a supported project SDK. 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.