.NET Buildpack on App Platform

App Platform supports two ways to build an image for your app: Cloud Native Buildpacks and Dockerfiles.

When you give App Platform access to your code, it defaults to using a Dockerfile if one is present in the root of the directory or specified in the app spec. Otherwise, App Platform checks your code to determine what language or framework it uses. If it supports the language or framework, it chooses an appropriate resource type and uses the proper buildpack to build the app and deploy a container.

App Platform uses the Heroku .NET buildpack to detect and build .NET applications, including C#, Visual Basic, and F# projects using the .NET and ASP.NET Core frameworks.

.NET Applications using Buildpacks

App Platform looks for any of the following files to detect a .NET application:

• Solution files: *.sln, *.slnx
• Project files: *.csproj, *.vbproj, *.fsproj
• File-based apps: *.cs

If App Platform detects one of these files in the root directory of your repository, it will apply the .NET buildpack during deployment to build your application.

Current Buildpack Version and Supported Runtimes

App Platform uses version 42 of the Heroku .NET buildpack. The buildpack supports .NET SDK versions 8.0 and later, including:

• Ubuntu-22
  • .NET 8.0 (8.0.123, 8.0.417)
  • .NET 9.0 (9.0.113, 9.0.309)
  • .NET 10.0 (10.0.102)

The buildpack supports C#, Visual Basic, and F# projects using the .NET and ASP.NET Core frameworks. A complete list of supported .NET SDK versions is available in the SDK inventory file.

Specify a .NET SDK Version

Default Version Configuration

By default, the buildpack installs the latest available and compatible .NET SDK version based on the TargetFramework property in each project file. The buildpack supports Target Framework Moniker (TFM) values in the format net{major_version}.0, for example, net8.0, net9.0, and net10.0.

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
</Project>

If a project file doesn’t specify TargetFramework, the buildpack looks for a Directory.Build.props file in the project directory or any parent directory and uses the TargetFramework property if defined there.

If a solution references projects targeting different framework versions, the buildpack prioritizes the most recent version when determining which SDK to install.

Advanced Version Configuration

To specify a different .NET SDK version, add a global.json file to the root directory. The buildpack supports configuring both the version and rollForward policy to control SDK installation.

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

Use the rollForward: disable option only when necessary, and regularly update the version to maintain security. For general usage, we recommend setting rollForward to latestFeature.

Specify a Solution File

By default, the buildpack automatically detects which solution, project, or file-based application 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 with a BUILD_TIME scope in your app’s spec:

services:
  - name: web
    git:
      repo: "https://github.com/example/repo"
      branch: master
    envs:
    - key: SOLUTION_FILE
      scope: BUILD_TIME
      value: "MyApp.sln"

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 = "MyApp.sln"

The solution file must be a simple filename without any directory components and must have a .sln or .slnx extension.

Build Behavior

Build Configuration

By default, the buildpack uses the Release configuration when building your application. You can customize the build configuration by setting the BUILD_CONFIGURATION environment variable:

services:
  - name: web
    git:
      repo: "https://github.com/example/repo"
      branch: master
    envs:
    - key: BUILD_CONFIGURATION
      scope: BUILD_TIME
      value: "Debug"

You can also configure this in project.toml:

[_]
schema-version = "0.2"

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

MSBuild Verbosity Level

You can control the verbosity level of MSBuild output by setting the MSBUILD_VERBOSITY_LEVEL environment variable. Supported values are:

• quiet (or q)
• minimal (or m)
• normal (or n)
• detailed (or d)
• diagnostic (or diag)

services:
  - name: web
    git:
      repo: "https://github.com/example/repo"
      branch: master
    envs:
    - key: MSBUILD_VERBOSITY_LEVEL
      scope: BUILD_TIME
      value: "detailed"

You can also configure this in project.toml:

[_]
schema-version = "0.2"

[com.heroku.buildpacks.dotnet.msbuild]
verbosity = "detailed"

Build Process

The buildpack follows these steps during the build process:

1. Detects the .NET SDK version requirement based on the TargetFramework property or global.json file
2. Downloads and installs the required .NET SDK
3. Restores .NET tools if a .config/dotnet-tools.json manifest file exists
4. Runs dotnet restore to restore NuGet packages
5. Runs dotnet publish to build and publish the application
6. Detects the web process type from published artifacts

Process Type Detection

The buildpack automatically detects process types from published artifacts:

• Web applications (ASP.NET Core projects using Microsoft.NET.Sdk.Web or Microsoft.NET.Sdk.Razor): Registered as web process type

If a Procfile is detected, the buildpack skips process type registration and uses the web processes defined in the Procfile.

.NET Tools

If your application includes a .config/dotnet-tools.json manifest file, the buildpack automatically runs dotnet tool restore to install the specified tools during the build process.

Port Binding

Your .NET application must listen on the port specified by the PORT environment variable. App Platform automatically sets this variable at runtime.

Here’s an example with ASP.NET Core that uses the PORT variable:

var builder = WebApplication.CreateBuilder(args);

// Configure the app to listen on the PORT environment variable
var port = Environment.GetEnvironmentVariable("PORT") ?? "5000";
builder.WebHost.UseUrls($"http://*:{port}");

var app = builder.Build();

// Application code goes here

app.Run();

Alternatively, you can use the ASPNETCORE_URLS environment variable which ASP.NET Core automatically recognizes:

services:
  - name: web
    git:
      repo: "https://github.com/example/repo"
      branch: master
    envs:
    - key: ASPNETCORE_URLS
      scope: RUN_TIME
      value: "http://*:${PORT}"