.NET Core Buildpack

Page last updated:

This topic describes how to push Cloud Foundry apps using the .NET Core buildpack. You can find supported ASP.NET Core versions in the .NET Core buildpack release notes.

Note: The .NET Core buildpack only works with ASP.NET Core. For apps which are not based on this toolchain, refer to the legacy .NET buildpack.

Push an App

Cloud Foundry automatically uses the .NET Core buildpack when one or more of the following conditions are met:

  • The pushed app contains one or more *.csproj or *.fsproj files.
  • The pushed app contains one or more project.json files.
  • The app is pushed from the output directory of the dotnet publish command.

If your Cloud Foundry deployment does not have the .NET Core buildpack installed or the installed version is out of date, push your app with the -b option to specify the buildpack:

$ cf push MY-APP -b https://github.com/cloudfoundry/dotnet-core-buildpack.git

Specify any non-default package sources in the NuGet.Config file.

For a basic example, see this Hello World sample.

.NET Core SDKs

To pin the .NET Core SDK to a specific version or version line, create a buildpack.yml file at the app root and add the following:

dotnet-core:
  sdk: 2.1.201

The following formats are also valid:

dotnet-core:
  sdk: 2.1.x

dotnet-core:
  sdk: 2.x

dotnet-core:
  sdk: 2.x.x

The buildpack chooses which SDK to install based on the files present at the app root, according to the following order of precedence:

  1. buildpack.yml
  2. global.json
  3. If the app contains only *.fsproj files, the buildpack installs the latest 1.1.x SDK.

Note: The app respects the SDK version specified in global.json at runtime. If you provide versions in both global.json and buildpack.yml, ensure that you specify the same versions in both files.

Configure the Listen Port

For your .NET Core app to work on Cloud Foundry, you must modify the Main method to configure the app to listen on the port specified by the $PORT environment variable, which Cloud Foundry sets automatically.

  1. Open the file that contains your Main method.

  2. Add a using statement to the top of the file.

    using Microsoft.Extensions.Configuration;

  3. Add the following lines before the line var host = new WebHostBuilder():

    var config = new ConfigurationBuilder()
    .AddCommandLine(args)
    .Build();

  4. Add the following line after .UseKestrel():

    .UseConfiguration(config)

    This allows the buildpack to pass the correct port from $PORT to the app when running the initial startup command.

  5. Add Microsoft.Extensions.Configuration.CommandLine as a dependency using one of the following:

    • project.json:

      "Microsoft.Extensions.Configuration.CommandLine": "VERSION",

    • *.csproj:

      <PackageReference Include="Microsoft.Extensions.Configuration.CommandLine">
    <Version>VERSION</Version>
</PackageReference>

    where VERSION is the version of the package to use. Valid versions can be found on https://www.nuget.org.

  6. If your app requires any other files at runtime, such as JSON configuration files, add them to the include section of copyToOutput.

  7. Save your changes.

With these changes, the dotnet run command copies your app Views to the build output, where the .NET CLI can find them. Refer to the following example Main method:

public static void Main(string[] args)
{
    var config = new ConfigurationBuilder()
        .AddCommandLine(args)
        .Build();

    var host = new WebHostBuilder()
        .UseKestrel()
        .UseConfiguration(config)
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseStartup<Startup>()
        .Build();
    host.Run();
}

Specify a .NET Framework Version

Lock the .NET Framework to a minor version. Do not lock to a patch version, because buildpacks contain only the two most recent patch versions of each minor version.

To lock the .NET Framework version in a .csproj app:

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <RuntimeFrameworkVersion>2.1.*</RuntimeFrameworkVersion>
  </PropertyGroup>

In a .runtimeconfig.json app, the latest .NET Framework patch version is used by default. To pin to a specific .NET Framework version, include the applyPatches property and set it to false:

{
  "runtimeOptions": {
    "tfm": "netcoreapp2.0",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "2.0.0"
    },
    "applyPatches": false
  }
}

Deploy Apps with Multiple Projects

To deploy an app that contains multiple projects, you must specify a main project for the buildpack to run. Create a .deployment file in the root folder of the app which sets the path to the main project as follows:

[config]
project = <main project>

  1. If the app uses project.json, set project to the directory containing the project.json file of the main project.

  2. If the app uses MSBuild, set project to the *.csproj or *.fsproj file of the main project.

For example, if an app using MSBuild contains three projects in the src folder, the main project MyApp.Web, MyApp.DAL, and MyApp.Services, format the .deployment file as follows:

[config]
project = src/MyApp.Web/MyApp.Web.csproj

In this example, the buildpack automatically compiles the MyApp.DAL and MyApp.Services projects if the MyApp.Web.csproj file of the main project lists them as dependencies, MyApp.Web. The buildpack attempts to execute the main project with dotnet run -p src/MyApp.Web/MyApp.Web.csproj.

Push an App in a Disconnected Environment

For offline use, you can cache the binaries in manifest.yml with the buildpack.

You can push apps with their other dependencies following these steps:

  1. Publish the app by running dotnet publish -r ubuntu.14.04-x64.

    Note: For this publish command to work, modify your app code so the .NET CLI publishes it as a self-contained app. For more information, see .NET Core Application Deployment.

  2. Navigate to the bin/<Debug|Release>/<framework>/<runtime>/publish directory. Or, if your app uses a manifest.yml, specify a path to the publish output folder. This allows you to push your app from any directory.

  3. Push your app.

Disabling the NuGet Package Cache

You may need to disable NuGet package caching, or clear NuGet packages cached in the staging environment, in one of the following scenarios:

  • Your app fails to stage because it runs out of space, exceeding the maximum allowable disk quota.
  • You have added pre-release packages to test a new feature, then decided to revert back to the main NuGet feed. You may need to remove the packages you changed from the cache to avoid conflicts.

Disabling NuGet caching both clears any existing NuGet dependencies from the staging cache and prevents the buildpack from adding NuGet dependencies to the staging cache.

To disable NuGet package caching, set the CACHE_NUGET_PACKAGES environment variable to false. If the variable is not set, or set to a different value, there is no change. Perform one of the following procedures to set CACHE_NUGET_PACKAGES to false:

  • Locate your app manifest, manifest.yml, and set the CACHE_NUGET_PACKAGES environment variable, following the format of the example below:

    ---
applications:
- name: sample-aspnetcore-app
  memory: 512M
  env:
    CACHE_NUGET_PACKAGES: false

  • Use cf set-env to set the CACHE_NUGET_PACKAGES environment variable on the command line:

    $ cf set-env YOUR-APP CACHE_NUGET_PACKAGES false

See the Environment Variables section of the Deploying with Application Manifests topic for more information.

Add Custom Libraries

If your app requires external shared libraries that are not provided by the rootfs or the buildpack, you must place the libraries in an ld_library_path directory at the app root.

Note: You must keep these libraries up-to-date. They do not update automatically.

The .NET Core buildpack automatically adds the directory <app-root>/ld_library_path to LD_LIBRARY_PATH so that your app can access these libraries at runtime.

Legacy .NET Buildpack

A legacy .NET buildpack exists, built by the Cloud Foundry community. This buildpack addresses apps not based on .NET Core. However, it requires you to write and compile your apps using Mono, for example from Xamarin Studio, MonoDevelop, or xbuild.

Create a pull request or raise an issue on the source for this page in GitHub