.NET Behavior in Heroku

Last updated November 11, 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, *.slnx, *.csproj, *.vbproj, *.fsproj, or *.cs 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.
  5. A single C# (.cs) file-based app.

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.
  • No solution or projects files are present, but multiple .cs files exist.

The buildpack builds and publishes the selected solution, project or C# 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

File-Based Apps

File-based apps are .NET applications defined in a single .cs file without project or solution files. The buildpack treats file-based apps the same as traditional projects, with a few key differences:

Configuration Defaults

Unless overridden with preprocessor directives, file-based apps use these defaults:

  • Project SDK: Microsoft.NET.Sdk
  • Target Framework: The latest .NET version that supports file-based apps

The default target framework is currently net10.0. When .NET 11 is released, the default will change to net11.0.

The buildpack automatically installs the .NET SDK version based on the target framework. For more details on SDK version selection, see Default .NET SDK Version Configuration.

Customizing File-Based Apps

You can customize the project SDK, target framework, and other settings using preprocessor directives in your .cs file:

// Specify the project SDK (defaults to Microsoft.NET.Sdk)
#:sdk Microsoft.NET.Sdk.Web

// Specify the target framework (defaults to net10.0)
#:property TargetFramework=net11.0

// Disable Native AOT compilation
#:property PublishAot=false

The buildpack uses the first #:sdk directive to determine the project SDK for automatic process type detection, and the #:property TargetFramework directive to determine which .NET SDK version to install. Other supported preprocessor directives such as #:package and #:project can also be used.

Extensionless files are not currently supported. File-based apps must have a .cs extension. While you can configure a shebang line (e.g., #!/usr/bin/env dotnet) at the top of your file, it will be ignored during the publish process.

All other build and deployment behavior follows the same process as traditional projects, including process type detection, build configuration, and environment variables.

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