.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
The first several releases of the .NET Core SDKs used project.json
files for project build configuration. The current release of the .NET Core SDK uses MSBuild as its build tool, which uses *.csproj
and *.fsproj
files for configuration.
Currently, the .NET Core buildpack includes both types of SDKs. If the pushed app contains a global.json
file, the buildpack installs the version specified by that file. Otherwise, the buildpack chooses which SDK to install as follows:
- If the app only contains
project.json
files, the buildpack installs the latest SDK that supports this configuration. - If the app only contains
*.csproj
and*.fsproj
files, the buildpack installs the latest SDK that uses MSBuild. - If the app contains both file types without a
global.json
, the buildpack throws an error, as it cannot determine the proper SDK to install.
Note: Microsoft has removed support for project.json from the .NET Core SDK tools. Consequently, support for project.json
apps in the buildpack will soon be deprecated.
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.
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)
This allows the buildpack to pass the correct port from
$PORT
to the app when running the initial startup command.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
.If your app requires any other files at runtime, such as JSON configuration files, add them to the
include
section ofcopyToOutput
.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:
<ItemGroup>
<PackageReference Include="Microsoft.NETCore.App">
<Version>1.1.*</Version>
</PackageReference>
</ItemGroup>
To lock the .NET Framework version in a project.json
app:
"dependencies": {
"Microsoft.NETCore.App": {
"type": "platform",
"version": "1.0.*"
}
}
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>
If the app uses
project.json
, setproject
to the directory containing theproject.json
file of the main project.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:
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.
Navigate to the
bin/<Debug|Release>/<framework>/<runtime>/publish
directory. Or, if your app uses amanifest.yml
, specify a path to the publish output folder. This allows you to push your app from any directory.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 theCACHE_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 theCACHE_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