.NET Core buildpack

Page last updated:

You can push Cloud Foundry apps to Linux Diego Cells using the .NET Core buildpack. To find supported ASP.NET Core versions, see .NET Core buildpack release notes.

The .NET Core buildpack can only be used to deploy apps to Linux Diego Cells.

To deploy .NET Core apps to Windows Diego Cells, use the Binary buildpack. For more information about the Binary buildpack, see Binary Buildpack.

Buildpacks provide needed dependencies to Cloud Foundry apps. 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 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 following table:

Push a .NET Core app

To push a .NET Core app to a Linux Diego Cell:

1. Run:

   cf push APP-NAME
   

   Where APP-NAME is the name you want to give your app.
   
   If your Cloud Foundry deployment does not have the .NET Core buildpack installed or the installed version is out of date, run the same 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.

2. Find the URL of your app in the output of the cf push command.

3. 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. See the following sections.

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

Deploying 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:

1. Create a .deployment file in your app’s root folder and open the new file in a text editor.

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

3. Save the revised .deployment file.

When deployed, the buildpack attempts to run 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 previously noted 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 are 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.

Deactivating and clearing your NuGet package cache

You might need to deactivate 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 might need to remove the packages you changed from the cache to avoid conflicts.

Deactivating 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 deactivated by default. If the default is not explicitly overridden, no additional NuGet caching configuration is required.

To deactivate NuGet package caching:

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

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

3. To alternatively configure the setting to false in the environment variables settings, run the following command:

   cf set-env APP-NAME CACHE_NUGET_PACKAGES false
   

   Where APP-NAME is the name of your app.

For more information, see Environment Variables in Deploying with App Manifests.

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.

Deploy a FDD using the buildpack:

1. Publish the app by running:

   dotnet publish [-f FRAMEWORK-NAME] [-c Release]
   

   Where FRAMEWORK-NAME is your target framework.

2. Prepare to push your app with one of these methods:

   • 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, go to bin/Debug|Release/FRAMEWORK-NAME/RUNTIME-NAME/publish directory, where FRAMEWORK-NAME is your target framework, and RUNTIME-NAME is the runtime you are using to push your app.

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

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

[provider_sect]
default = default_sect
legacy = legacy_sect

[default_sect]
activate = 1

[legacy_sect]
activate = 1