.NET Core Buildpack

Overview
Push a .NET Core App
Source-Based, Non-Published Deployments
Framework-Dependent Deployments
Self-Contained Deployments
Specify .NET Core SDKs
Specify .NET Runtime Versions
- Source-Based Apps
- Framework-Dependent Apps
Push an App in a Disconnected Environment
Maintain ASP.NET Core Assemblies
Configure the Listen Port
Add Custom Libraries

Page last updated:

This topic describes how to push Cloud Foundry apps to Linux cells 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 can only be used to deploy apps to Linux cells. To deploy .NET Core apps to Windows cells, use the Binary buildpack.

Overview

Buildpacks provide needed dependencies to Pivotal Web Services (PWS) apps. PWS 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 app is pushed from the output directory of the dotnet publish command.

For information about deploying different types of .NET apps, follow the links in the table below.

Type of .NET App	Buildpack
ASP.NET MVC ASP.NET Web Forms ASP.NET WebAPI Apps Windows Communication Foundation (WCF)	HWC
.NET Console	Binary
.NET Core pushed to Linux stack	.NET Core
.NET Core pushed to Windows stack	Binary

Push a .NET Core App

To push a .NET Core app to a Linux cell, do the following:

Run the cf push command:

cf push APP-NAME

Where APP-NAME is the name you want to give your app. For example:

$ cf push my-app
Pushing app my-app to org my-org / space my-space as username@example.com...
...
name:              my-app
requested state:   started
routes:            my-app.example.com
last uploaded:     Mon 13 May 15:48:00 PDT 2020
stack:             cflinuxfs3
buildpacks:        dotnet-core

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

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

Where APP-NAME is the name you want to give your app.

Find the URL of your app in the output of the push command. In the example above, my-app.example.com is the URL of the app.
Open a browser and navigate to the URL to see your app running.

For a basic sample app, see ASP.NET Core Getting Started App in GitHub.

Source-Based, Non-Published Deployments

For a source-based, non-published deployment, you push your app’s source code, not the output directory of the dotnet publish command.

The source-based, non-published workflow ensures the buildpack can keep all your dependencies in sync and up to date. For additional information about using source-based, non-published deployments, see the following sections:

Deploy Apps with Multiple Projects
Use Non-Default Package Sources
Disable and Clear Your NuGet Package Cache

Note: The source-based deployment workflow also uses the cf push command to push source-based apps to Cloud Foundry.

Deploy Apps with Multiple Projects

If you are deploying an app containing multiple projects, you must specify which of the app’s projects is the main project.

To specify the main project in a multi-project deployment perform the following steps:

Create a .deployment file in your app’s root folder and open the new file in a text editor.
Designate the main project’s path by configuring the file, using the following format:
```
[config]
project = PATH-TO-YOUR-MAIN-PROJECT
```
Where PATH-TO-YOUR-MAIN-PROJECT is the location of your main project’s *.csproj or *.fsproj file.

For example:
```
[config]
project = src/MyApp.Web/MyApp.Web.csproj
```
In this example, by pointing to the MyApp.Web *.csproj file, MyApp.Web is configured as the main project.
Save the revised .deployment file.

When deployed, the buildpack attempts to execute the main project using the dotnet run command, dotnet run -p PATH-TO-YOUR-MAIN-PROJECT, and automatically compiles all projects listed as dependencies in the main project’s *.csproj or *.fsproj file.

For example: Suppose your .deployment file is configured as above and you have an app src folder containing three projects: MyApp.Web, MyApp.DAL and MyApp.Services. If your MyApp.Web.csproj file lists the MyApp.DAL and MyApp.Services projects as dependencies, the two additional projects will be compiled by the buildpack.

Use Non-Default Package Sources

If you want to deploy an app that uses non-default package sources, you must specify those package sources in the NuGet.Config file. For information about NuGet.Config, see nuget.config reference in the Microsoft documentation.

Disable and Clear Your 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 and 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 clears any existing NuGet dependencies from the staging cache and prevents the buildpack from adding NuGet dependencies to the staging cache.

NuGet package caching is disabled by default. If the default is not explicitly overridden, no additional NuGet caching configuration is required.

To disable NuGet package caching, do the following:

Confirm the CACHE_NUGET_PACKAGES environment variable is not set to true in your app manifest by locating the manifest.yml file and confirming CACHE_NUGET_PACKAGES is not set to true.
If needed, set CACHE_NUGET_PACKAGES to false in the manifest.yml file by setting the CACHE_NUGET_PACKAGES environment variable to false.

For example:
```
---
applications:
- name: sample-aspnetcore-app
  memory: 512M
  env:
    CACHE_NUGET_PACKAGES: false
```
To alternatively configure the setting to false in the environment variables settings, run the following on the command line:
```
cf set-env APP-NAME CACHE_NUGET_PACKAGES false
```
Where APP-NAME is the name of your app.

For more information, see the Environment Variables section of the Deploying with Application Manifests topic.

Framework-Dependent Deployments

For a framework-dependent deployment (FDD), you deploy only your app and third-party dependencies. Cloud Foundry recommends using this workflow if you deploy an app in an offline setting. For information about deploying FDDs, see Framework-dependent deployments (FDD) in the Microsoft documentation.

To deploy an FDD using the buildpack, do the following:

Publish the app by running the dotnet publish command:
```
dotnet publish [-f FRAMEWORK-NAME] [-c Release]
```
Where FRAMEWORK-NAME is your target framework.
Prepare to push your app by doing one of the following:
- If your app uses a manifest.yml, specify a path to the output folder of dotnet publish. This allows you to push your app from any directory.
- If not, navigate to the bin/Debug|Release/YOUR-FRAMEWORK/YOUR-RUNTIME/publish directory.
Push your app.

Self-Contained Deployments

For a self-contained deployment (SCD), you deploy your app, third-party dependencies, and the version of .NET Core that you used to build your app. For information about SCDs, see Self-contained deployments (SCD) in the Microsoft documentation.

Note: Cloud Foundry does not recommend using the SCD workflow. The buildpack is unable to keep dependencies in sync and up to date for workflows that deploy a pre-published binary.

When using the SCD workflow for deploying your app, you must do the following:

Specify a runtime in the dotnet publish command. For example:
```
$ dotnet publish -r ubuntu14.04-x64
```
Include the specified runtime in the RuntimeIdentifiers section of the project file.

Specify .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 your SDK version in one of the following formats:

dotnet-core:
  sdk: 2.1.201

dotnet-core:
  sdk: 2.1.x

dotnet-core:
  sdk: 2.x

The buildpack chooses what SDK to install based on the files present at the app root in the following order of precedence:

buildpack.yml
global.json
*.fsproj

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

Specify .NET Runtime Versions

This section explains how to specify a .NET Runtime version for source-based and framework-dependent apps.

Source-Based Apps

If you want to lock the .NET Runtime version, configure your .csproj or .fsproj file to lock your app to the desired version.

For example, the following configuration locks the runtime to 2.1:

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

Note: For source-based apps, specify a minor version of the .NET Runtime. Do not specify a patch version because buildpacks contain only the two most recent patch versions of each minor version.

Framework-Dependent Apps

Your app is configured to use the latest .NET Runtime patch version by default.

If you want your app to maintain a specific .NET Runtime version, you must modify your app’s .runtimeconfig.json file to include the applyPatches property and set the property to false.

For example:

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

Note: Set applyPatches: false in *.runtimeconfig.json only if you want to pin your .NET Framework to a specific version. This prevents your app from receiving updates to the runtime version and assemblies.

Push an App in a Disconnected Environment

For offline environments, Cloud Foundry recommends using the Framework-Dependent Deployment workflow. This workflow enables the deployed app to use the latest runtime provided by the offline buildpack. For more information, see: Framework-Dependent Deployments.

Maintain ASP.NET Core Assemblies

Note: This section applies only to source-based and framework-dependent deployments.

For maintaining ASP.NET Core assemblies, it is recommended you do one of the following

Configure your app as a fully vendored app requiring fewer buildpack updates. Modify your .csproj file with the following:

<PropertyGroup>
  <PublishWithAspNetCoreTargetManifest>false</PublishWithAspNetCoreTargetManifest>
</PropertyGroup>

Keep your SDK up to date, by setting buildpack.yml to the .NET SDK line you want to use. For example:
```
---
dotnet-core:
    sdk: 2.0.x
```

Note: 2.0.x ASP.NET Core assemblies are released in the 2.1.200-2.1.299 SDK versions, and 2.1.x assemblies are released in the 2.1.300 and above SDK versions.

Configure the Listen Port

PWS sets the $PORT environment variable automatically. For your .NET Core app to work on PWS, you must configure the app to listen on the environment’s specified port.

For C# apps, the following modifications allow the buildpack to pass the correct port from $PORT environment variable to the app when running the initial startup command:

Open the file that contains your Main method.

Add a using statement to the top of the file:

using Microsoft.Extensions.Configuration;

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

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

Add the following line after .UseKestrel():

.UseConfiguration(config)

The Main method should now resemble the following example:

public static void Main(string[] args)
{
    var config = new ConfigurationBuilder()
        .AddCommandLine(args)
        .Build();
    var host = new WebHostBuilder()
        .UseKestrel()
        .UseConfiguration(config)
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseStartup&lt;Startup&gt;()
        .Build();
    host.Run();
}

Save your changes.
Add Microsoft.Extensions.Configuration.CommandLine as a dependency in *.csproj:
```
<PackageReference Include="Microsoft.Extensions.Configuration.CommandLine">
  <Version>VERSION</Version>
</PackageReference>
```
Where VERSION is the version of the package to use. To find a list of valid versions, navigate to https://www.nuget.org.
If your app requires any other files at runtime, such as JSON configuration files, add them to the include section of copyToOutput.
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.

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.

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