docs community blog github
Edit

How to Build .NET Core Apps with Paketo Buildpacks

This documentation explains how to use the Paketo .NET Core Buildpack to build applications for several common use-cases. For more in-depth description of the buildpack’s behavior and configuration see the Paketo .NET Core Buildpack Reference documentation.

Build a Sample App

To build your app locally with the buildpack using the pack CLI, run

git clone https://github.com/paketo-buildpacks/samples
cd samples/dotnet-core/aspnet
pack build my-app --buildpack gcr.io/paketo-buildpacks/dotnet-core \
  --builder paketobuildpacks/builder:base
copy to clipboard
Copied!

See samples for how to run the app.

NOTE: Though the example above uses the Paketo Base builder, this buildpack is also compatible with the Paketo Full builder.

Install Specific .NET 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 .Net Core Runtime release notes and .Net Core ASP.Net 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, either by passing a flag to the platform or by adding it to your project.toml. See the Cloud Native Buildpacks documentation to learn more about project.toml files.

With a pack build flag

pack build myapp --env BP_DOTNET_FRAMEWORK_VERSION=5.0.4
copy to clipboard
Copied!

In a project.toml file

[[ build.env ]]
  name = 'BP_DOTNET_FRAMEWORK_VERSION'
  value = '5.0.4'
copy to clipboard
Copied!

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"
    }
  }
}
copy to clipboard
Copied!

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>
copy to clipboard
Copied!

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>
copy to clipboard
Copied!

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

Deprecated: Using buildpack.yml

Specifying the .Net Core Framework version through buildpack.yml configuration will be deprecated in .Net Core Runtime and .Net Core ASPNET Buildpacks v1.0.0. To migrate from using buildpack.yml, please set the BP_DOTNET_FRAMEWORK_VERSION environment variable.

Install a Specific .NET 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 .Net Core SDK Buildpack v1.0.0.

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.

Build an App from Source in a Subdirectory

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, either by passing a flag to the platform or by adding it to your project.toml. See the Cloud Native Buildpacks documentation to learn more about project.toml files.

With a pack build flag

pack build my-app --env BP_DOTNET_PROJECT_PATH=./src/my-app
copy to clipboard
Copied!

In a project.toml file

[[ build.env ]]
  name = 'BP_DOTNET_PROJECT_PATH'
  value = './src/my-app'
copy to clipboard
Copied!
See the Cloud Native Buildpacks documentation to learn more about project.toml files.

Deprecated: Using buildpack.yml

Specifying the project path through buildpack.yml configuration will be deprecated in Dotnet Publish Buildpack v1.0.0 & Dotnet Execute Buildpack v1.0.0. To migrate from using buildpack.yml, please set the $BP_DOTNET_PROJECT_PATH environment variable.

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.

Edit

Last modified: September 21, 2021