LATEST VERSION: 1.10 - CHANGELOG
Pivotal Cloud Foundry v1.9

.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 new toolchain, please refer to the legacy .NET buildpack.

Push an App

Cloud Foundry automatically uses the .NET Core buildpack when:

  • 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

If you do not want to use latest stable beta release of the .NET CLI, specify the version in the global.json file.

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

For a basic example, see this Hello World sample.

Configure the Listen Port

For your .NET Core app to work on Cloud Foundry, you must modify the Main method to make the app 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();
    

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

  4. Remove the following line from the Main method.

    .UseContentRoot(Directory.GetCurrentDirectory())
    
  5. Add this line after .UseKestrel():

    .UseConfiguration(config)
    
  6. Save the file, and then open project.json.

  7. Add the following dependency:

    "Microsoft.Extensions.Configuration.CommandLine": "1.0.0",
    
  8. Add the following property to the buildOptions section:

    "copyToOutput": {
        "include": [
            "wwwroot",
            "Areas/**/Views",
            "Views",
            "appsettings.json"
        ]
    }
    
  9. Remove the following line from the Startup method:

    .SetBasePath(env.ContentRootPath)
    
  10. If your app requires any other files at runtime, such as JSON configuration files, add them to the include section of copyToOutput.

  11. Save.

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)
        .UseStartup<Startup>()
        .Build();
    host.Run();
}

Note: The samples provided in the cli-samples repo and the templates provided by Visual Studio and Yeoman work with this buildpack after you have followed the steps above.

Deploy Apps with Multiple Projects

To deploy an app that contains multiple projects, specify the project you want the buildpack to run as the main project.

Create a .deployment file in the root folder of the .NET solution file which sets the path to the main project. You can also specify the path to the main project as the project folder or the project file, .xproj or .csproj.

For example, if a solution contains three projects in the src folder, the main project MyApp.Web plus MyApp.DAL and MyApp.Services, format the .deployment file as follows:

[config]
project = src/MyApp.Web

In this case, the buildpack automatically compiles the MyApp.DAL and MyApp.Services projects if the project.json 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. You can also specify the path to MyApp.Web as project = src/MyApp.Web/MyApp.Web.xproj, assuming the project is an xproj project.

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 is failing 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. The packages you changed may need to be removed 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 application 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.

Legacy .NET Buildpack

There is also a legacy .NET buildpack built by the Cloud Foundry community which addresses applications not based on .NET Core. However, it requires you to write and compile your apps using Mono (e.g. via Xamarin Studio, MonoDevelop or xbuild).

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