.NET Core Buildpack Reference

This reference documentation offers an in-depth description of the behavior and configuration options of the Paketo .NET Core buildpack. For explanations of how to use the buildpack for several common use-cases, see the Paketo .NET Core buildpack How To documentation.

Supported Dependencies

The .NET Core Paketo buildpack supports several versions of the .NET Core Framework. For more details on the specific versions supported in a given buildpack version, see the release notes.

SDK Version Selection

The dotnet-core-sdk buildpack will automatically determine the version based on the below priority order:

• BP_DOTNET_SDK_VERSION environment variable
  • This also supports wildcards e.g. 9.0.*
• global.json configuration file
  • Refer to the .NET documentation for more on how version selection works
• <RuntimeFrameworkVersion> from the .(cs|fs|vb)proj file
• <FrameworkVersion> from the .(cs|fs|vb)proj file

If using a preview version of the SDK, you must set BP_DOTNET_ENABLE_PRERELEASE=true to enable pre-release support.

ASP.NET Runtime Version Selection

The dotnet-core-aspnet-runtime buildpack will automatically determine the version based on the below priority order:

• BP_DOTNET_RUNTIME_VERSION environment variable
  • This must be a specific version e.g. 10.0.1
• *.runtimeconfig.json which is generated by dotnet publish for non-self-contained builds
  • If the specific version is not available, “roll-forward” behaviour will try to select next best patch release, followed by minor release
  • This can be disabled by setting environment variable BP_DOTNET_ROLL_FORWARD=Disable

Supported Service Bindings

The .NET Core buildpack can be configured using service bindings.

Behavior

The Paketo .NET Core buildpack is a composite buildpack designed to build .NET Core applications in several different forms.

Supported Application Types

The .NET Core buildpack supports several types of application source code that can be built into a container image. Developers can provide raw source code, or built artifacts like Framework-Dependent Deployments/Executables or Self-Contained Deployments when building their application.

Source Applications

The .NET Core buildpack is capable of building application source code into Framework-Dependent Deployments (FDD) or Executables (FDE). This is achieved using the dotnet publish command. For .NET Core Framework 2.x applications, an FDD is produced as the default build artifact, while an FDE is produced when the application source is for .NET Core Framework 3.x. The buildpack sets the following dotnet publish flags by default:

• --configuration Release
• --runtime linux-x64
• --self-contained false
• --output <temp-directory>

See the dotnet CLI documentation for details about build configuration.

Framework-Dependent Deployments or Framework-Dependent Executables

When building an application that has already been published as a Framework-Dependent Deployment or Framework-Dependent Executable, the buildpack will include the required .NET Core Framework dependencies and set the start command.

Self-Contained Deployment

When building an application as a Self-Contained Deployment (SCD), the buildpack will ensure the correct start command will be used to run your app. No .NET Core Framework dependencies will be included in the built image as they are already included in the SCD artifact.

Buildpack-Set Environment Variables

DOTNET_ROOT

The DOTNET_ROOT environment variable specifies the path to the directory where .NET Runtimes and SDKs are installed.

• Set by: dotnet-core-aspnet-runtime buildpack
• Phases: launch
• Value: path to the ASP.NET runtime root directory

PATH

The PATH environment variable is modified to enable the dotnet CLI to be found during subsequent build and launch phases.

• Set by: dotnet-core-sdk
• Phases: build and launch
• Value: path the directory containing the dotnet executable

Launch Process

The .NET Core buildpack will ensure that your application image is built with a valid launch process command. These commands differ slightly depending upon the type of built artifact produced during the build process.

For more information about which built artifact is produced for a Source Application, see this section.

Framework-Dependent Deployments and Source Applications

For Framework-Dependent Deployments (FDD), the dotnet CLI will be invoked to start your application. The application will be given configuration to help it bind to a port inside the container. The default port is 8080, but can be overridden using the $PORT environment variable.

dotnet myapp.dll --urls http://0.0.0.0:${PORT:-8080}

Copied!

Self-Contained Deployment and Framework-Dependent Executables

For Self-Contained Deployments and Framework-Dependent Executables, the executable will be invoked directly to start your application. The application will be given configuration to help it bind to a port inside the container. The default port is 8080, but can be overridden using the $PORT environment variable.

./myapp --urls http://0.0.0.0:${PORT:-8080}

Copied!

Software Bill of Materials

The .NET Core buildpack supports the full software bill of materials (SBOM) in Syft, CycloneDX, and SPDX formats. The .NET Core buildpack also includes limited support for the legacy Paketo-specific SBOM format. This Paketo-specific SBOM format does not include information about the application dependencies.

Check out the Access the Software Bill of Materials guide for more information about how to retrieve the SBOM for your .NET Core app image.