.NET Core Buildpack
- Push an App
- Source-Based, Non-Published Deployments
- Framework-Dependent Deployments
- Self-Contained Deployments
- Specify .NET Core SDKs
- Specify .NET Runtime Versions
- Push an App in a Disconnected Environment
- Maintain ASP.NET Core Assemblies
- Configure the Listen Port
- Add Custom Libraries
- Install Node for Server Side Rendering
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.
Pivotal Web Services (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 an App
Follow the steps below to push your app.
Run
cf push APP-NAME
command to push your app, whereAPP-NAME
is the name you want to give your app. For example:$ cf push my-app Creating app my-app in org sample-org / space sample-space as username@example.com... OK ... requested state: started instances: 1/1 usage: 1GB x 1 instances urls: my-app.example.com
If your PWS 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 APP-NAME -b https://github.com/cloudfoundry/dotnet-core-buildpack.git
Where
APP-NAME
is the name of your app.Find the URL of your app in the output from the push command and navigate to it to see your app running. In the example above,
my-app.example.com
is the URL of your app.
For a basic example app, see ASP.NET Core getting started app in GitHub.
Source-Based, Non-Published Deployments
When using this workflow, you push the source code for your app to Cloud Foundry by running the cf push
command.
Note that for a source-based, non-published deployment, you push the source code for your app, 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
Deploy Apps with Multiple Projects
If you want to deploy an app that contains multiple projects, you must specify your main project for the buildpack to run.
To specify your main project, create a .deployment
file in the root folder of the app
that sets the path to the main project in the following format:
[config]
project = PATH-TO-YOUR-MAIN-PROJECT
Where PATH-TO-YOUR-MAIN-PROJECT
is the location of your main project.
Set project
to the *.csproj
or *.fsproj
file of your main project.
For example, if an app contains three projects in the src
folder,
the main project MyApp.Web
as well as 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.
The buildpack attempts to execute the main project using the dotnet run -p src/MyApp.Web/MyApp.Web.csproj
command.
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.
To disable NuGet package caching, set the CACHE_NUGET_PACKAGES
environment variable to false
.
If the variable is not set, no change is required.
To set CACHE_NUGET_PACKAGES
to false
, do one of the following:
Locate your app manifest,
manifest.yml
, and set theCACHE_NUGET_PACKAGES
environment variable tofalse
:--- 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 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 YOUR-FRAMEWORK] [-c Release]
Where
YOUR-FRAMEWORK
is your target framework.Navigate to the
bin/Debug|Release/YOUR-FRAMEWORK/YOUR-RUNTIME/publish
directory. Alternatively, if your app uses amanifest.yml
, specify a path to the output folder ofdotnet publish
. This allows you to push your app from any directory.Push your app.
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.
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. Because this workflow results in a pre-published binary, the buildpack is not able to keep all your dependencies in sync and up to date.
When using the SCD workflow for deploying your app,
you must specify a runtime in the dotnet publish
command. For example:
$ dotnet publish -r ubuntu14.04-x64
In addition, you must 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 the global.json
and buildpack.yml
files,
ensure that 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
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.
If you want to lock the .NET Runtime version, add the following to your .csproj
or .fsproj
file:
<PropertyGroup>
<TargetFramework>netcoreapp2.1</TargetFramework>
<RuntimeFrameworkVersion>2.1.*</RuntimeFrameworkVersion>
</PropertyGroup>
Framework-Dependent Apps
In your .runtimeconfig.json
app, the latest .NET Runtime patch version is used by default.
If you want to set a specific .NET Runtime version, add the applyPatches
property and set it to false
as follows:
{
"runtimeOptions": {
"tfm": "netcoreapp2.0",
"framework": {
"name": "Microsoft.NETCore.App",
"version": "2.0.0"
},
"applyPatches": false
}
}
Push an App in a Disconnected Environment
For offline environments, Cloud Foundry recommends using the Framework-Dependent Deployments workflow. This workflow enables the deployed app to use the latest runtime provided by the offline buildpack.
Maintain ASP.NET Core Assemblies
Note: This section applies only to source-based and framework-dependent deployments.
For maintaining ASP.NET Core assemblies, update your .csproj
file with the following:
<PropertyGroup>
<PublishWithAspNetCoreTargetManifest>false</PublishWithAspNetCoreTargetManifest>
</PropertyGroup>
This results in a fully vendored app that requires fewer buildpack updates.
Alternatively, to keep your SDK up to date, you can set buildpack.yml
to the .NET SDK line you want to use:
---
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
For your .NET Core app to work on PWS,
you must modify the Main
method to configure the app to listen on the port specified by the $PORT
environment variable.
PWS sets this environment variable 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 in*.csproj
:<PackageReference Include="Microsoft.Extensions.Configuration.CommandLine"> <Version>VERSION</Version> </PackageReference>
In the above example, replace
VERSION
with 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 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();
}
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.
Install Node for Server Side Rendering
If your app requires node
to be installed at runtime for server side rendering, you must set the INSTALL_NODE
environment variable to true
before pushing or restaging your app.