The Tanzu .Net Core Buildpack supports building several configurations of .Net Core applications.

Supported Dependencies

The Tanzu .Net Core 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.

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.

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.

Specifying Runtime and ASP.Net Versions

The .Net Core Runtime and .Net Core ASP.Net Buildpacks allow you to specify a version of the .Net Core Runtime and ASP.Net to use during deployment. This version can be specified in several ways including through a runtimeconfig.json, MSBuild Project file, or build-time environment variables. When specifying a version of the .Net Core Runtime and ASP.Net, you must choose a version that is available within these buildpacks. These versions can be found in the release notes.

.Net Core ASP.Net will only be included in the build process if your application declares its Runtime Framework as either Microsoft.AspNetCore.App or Microsoft.AspNetCore.All.

Using BP_DOTNET_FRAMEWORK_VERSION

To configure the buildpack to use a certain version of the .Net Core Runtime and ASP.Net when deploying your app, set the $BP_DOTNET_FRAMEWORK environment variable at build time.

Note: If you specify a particular version using the above environment variable, the buildpack will not run runtime version roll-forward logic. To learn more about roll-forward logic, see the Microsoft .Net Runtime documentation.

Using runtimeconfig.json

If you are using a runtimeconfig.json file, you can specify the .Net Core Runtime version within that file. To configure the buildpack to use .Net Core Runtime v2.1.14 when deploying your app, include the values below in your runtimeconfig.json file:

{
  "runtimeOptions": {
    "framework": {
      "version": "2.1.14"
    }
  }
}

Using a Project file

If you are using a Project file (eg. *.csproj, *.fsproj, or *.vbproj), you can specify the .Net Core Runtime version within that file. To configure the buildpack to use .Net Core Runtime v2.1.14 when deploying your app, include the values below in your Project file:

<Project>
  <PropertyGroup>
    <RuntimeFrameworkVersion>2.1.14</RuntimeFrameworkVersion>
  </PropertyGroup>
</Project>

Alternatively, for applications that do not rely upon a specific .Net Core Runtime patch version, you can specify the Target Framework and the buildpack will choose the appropriate .Net Core Runtime version. To configure the buildpack to use a .Net Core Runtime version in the 2.1 .Net Core Target Framework when deploying your app, include the values below in your Project file:

<Project>
  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
  </PropertyGroup>
</Project>

For more details about specifying a .Net Core version using a Project file, please review the Microsoft documentation.

.Net Core Framework Version Selection

The .Net Core Buildpack uses the same version selection policy that Microsoft has put together for .Net Core Framework. If you would like to know more about the policy please refer to this documentation provided by Microsoft.

Deprecated: Using buildpack.yml

Specifying the .Net Core Framework version through buildpack.yml configuration will be deprecated in the next major version release of the buildpack. To migrate from using buildpack.yml, please set the BP_DOTNET_FRAMEWORK_VERSION environment variable.

Specifying an SDK Version

By default, the .Net Core SDK Buildpack installs the latest available patch version of the SDK that is compatible with the installed .Net Core runtime. The available SDK versions for each buildpack release can be found in the release notes.

However, the .Net Core SDK version can be explicitly set by specifying a version in a buildpack.yml file.

Deprecated: Using buildpack.yml

Specifying the .Net Core SDK version through buildpack.yml configuration will be deprecated in the next major version release of the buildpack.

Because versions of the .NET Core runtime and .NET Core SDK dependencies are so tightly coupled, most users should instead use the BP_DOTNET_FRAMEWORK_VERSION environment variable to specify which version of the .NET Core runtime that the .NET Core Runtime Buildpack should install. The .Net Core SDK buildpack will automatically install an SDK version that is compatible with the selected .NET Core runtime version.

Specifying a Custom Project Path

By default, the .Net Core Build Buildpack will consider the root directory of your codebase to be the project directory. This directory should contain a C#, F#, or Visual Basic Project file. If your project directory is not located at the root of your source code you will need to set a custom project path.

Using BP_DOTNET_PROJECT_PATH

You can specify a project path by setting the $BP_DOTNET_PROJECT_PATH environment variable at build time.

Deprecated: Using buildpack.yml

Specifying the project path through buildpack.yml configuration will be deprecated in the next major version release of the buildpack. To migrate from using buildpack.yml, please set the $BP_DOTNET_PROJECT_PATH environment variable.

Supported Service Bindings

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

type Required Files # Bindings of This Type Accepted
nugetconfig type, nuget.config 0 or 1

Provide NuGet Configurations

A NuGet configuration file can be provided to the build process in two different ways. The provided file will have an effect on the dotnet publish command within the build process.

Via Service Bindings

Configuration can be provided to the build without explicitly including the file, which might contain credentials or other sensitive data, in the application directory. When building with the pack CLI, a service binding containing a nuget.config file can be provided. In addition to the nuget.config file, the binding must be of type nugetconfig. Check out the service bindings documentation for more details on service bindings.

The binding will be made available as a "user-level" NuGet configuration at $HOME/.nuget/NuGet/NuGet.Config during the build process. The configuration applies across all operations involving NuGet, but will be overriden by project-level configurations.

The resulting command will look like:

pack build myapp --env SERVICE_BINDING_ROOT=/bindings --volume <absolute-path-to-binding>:/bindings/nugetconfig

Via Application Source Code

A NuGet configuration file can also be provided in the application source directory following .NET Core rules. The project-level configuration will take precedence over a NuGet configuration provided via service binding.

For more info, see Paketo docs

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-runtime, dotnet-core-sdk, dotnet-core-aspnet buildpacks
  • Phases: build and launch
  • Value: path to the .Net root directory

RUNTIME_VERSION

The RUNTIME_VERSION environment variable specifies the version of the .Net Core Runtime installed by the .Net Core Runtime Buildpack.

  • Set by: dotnet-core-runtime
  • Phases: build
  • Value: installed version of the .Net Core Runtime

SDK_LOCATION

The SDK_LOCATION environment variable specifies the file path location of the installed .Net Core SDK.

  • Set by: dotnet-core-sdk
  • Phases: build
  • Value: path to the .Net Core SDK installation

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 Conf 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}

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}

Additional Configuration

Install a Custom CA Certificate

.NET Core buildpack users can provide their own CA certificates and have them included in the container root truststore at build-time and runtime by following the instructions outlined in the CA Certificates section of our configuration docs.

Override the Start Process Set by the Buildpack

.NET Core buildpack users can set custom start processes for their app image by following the instructions in the Procfiles section of our configuration docs.

Set Environment Variables for App Launch Time

.NET Core buildpack users can embed launch-time environment variables in their app image by following the documentation for the Environment Variables Buildpack.

Add Custom Labels to the App Image

.NET Core buildpack users can add labels to their app image by following the instructions in the Applying Custom Labels section of our configuration docs.

check-circle-line exclamation-circle-line close-line
Scroll to top icon