.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.

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 pushed app contains one or more project.json 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.

Push an App

Follow the steps below to push your application.

1. (Optional) Specify any non-default package sources in the NuGet.Config file.

2. Run cf push APP-NAME command to push your app, where APP-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 MY-APP -b https://github.com/cloudfoundry/dotnet-core-buildpack.git
   

3. Find the URL of your app in the output from the push command and navigate to it to see your HWC 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 application in GitHub.

.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 files, ensure that you specify the same versions in both files.

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.

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>
     

   In the above examples, replace VERSION with the version of the package to use. Valid versions can be found at 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

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

.csproj Apps

Add the following to a .csproj app to lock the .NET Framework version:

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

.runtimeconfig.json Apps

In a .runtimeconfig.json app, the latest .NET Framework patch version is used by default. To pin to a specific .NET Framework version, add 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>

project.json Apps

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

MSBuild Apps

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.