Octopus Deploy Documentation

ASP.NET Core web applications

Last updated

ASP.NET Core is the future of ASP.NET, and it contains many changes to how applications are built, and how they are run.

If you are new to ASP.NET Core you can start with the Tutorial: Get Started ASP.Net Core tutorial.

Publishing and packing the website

When your application is ready, it needs to be published:

# Publish the application to a folder
dotnet publish source/MyApp.Web --output published-app --configuration Release

When your application has been published you need to package it:

# Package the folder into a ZIP
octo pack --id MyApp.Web --version 1.0.0 --basePath published-app

For more information about packaging applications see Creating packages using the Octopus CLI.

If you are using the built-in repository you can create a zip file

When you have your generated nupkg or zip file it needs to be pushed to a repository.

If you are using TeamCity, you can use the new TeamCity plugin for dotnet commands.

OctoPack is not compatible with ASP.NET Core applications. Please see the OctoPack documentation for more details.


ASP.NET Core applications can either run as a command line program with Kestrel, or under IIS (which also uses Kestrel - check out the book for details).

See the ASP.NET Core IIS documentation for instructions on setting up IIS for ASP.NET Core.

When running under IIS, ensure the .NET CLR Version is set to No Managed Code.

Antiforgery cookie

The .AspNetCore.Antiforgery cookie created by ASP.NET Core uses the application path to generate its hash. By default Octopus will deploy to a new path every time, which causes a new cookie to be set every deploy. This results in many unneeded cookies in the browser. See this blog post for more details. To change this behavior, set the Antiforgery token in your startup.cs like this:

public void ConfigureServices(IServiceCollection services)
    services.AddAntiforgery(opts => opts.CookieName = "AntiForgery.MyAppName");

Cookie authentication in ASP.NET Core 2

Similar to antiforgery cookies, cookie authentication in ASP.NET Core 2 uses Microsoft's data protection API (DPAPI) which can use the application path to isolates applications from one another. This can cause older cookies to simply not work. To change this behavior, you need to set the application name in your startup.cs like this:

public void ConfigureServices(IServiceCollection services)
    services.AddDataProtection().SetApplicationName("my application");


With the JSON Configuration Variables feature you can define variables in Octopus for use in the JSON configuration files of your applications. This lets you define different values based on the scope of the deployment. This feature uses a matching syntax so you can update configuration nested in JSON object and array literals.

This is designed to work natively with .NET Core JSON configuration files but works equally well with any JSON files.

Configuring the JSON configuration variables feature

  1. When you define the package step in your project enable the JSON Configuration Variables feature by clicking the CONFIGURE FEATURES link and selecting JSON configuration variables and clicking OK.
  2. In the Features section of the step template, specify the relative paths within the package to your JSON configuration files. For instance:

Octopus will find the target files and replace any matching configuration settings with the value of matching Octopus variables.

Simple variables

Given this example of a target config file:

   "weatherApiUrl": "dev.weather.com",
   "weatherApiKey": "DEV1234567",
   "tempImageFolder": "C:\temp\img",
   "port": 8080,
   "debug": true

If you define the variables weatherApiUrl, weatherApiKey, port, and debug in the variables section of your deployment process with the values test.weather.com, TEST7654321, 80, and false, the target config file in your packaged application is updated to become:

   "weatherApiUrl": "test.weather.com",
   "weatherApiKey": "TEST7654321",
   "tempImageFolder": "C:\temp\img",
   "port": 80,
   "debug": false

Note, the tempImageFolder setting remains untouched and that the types of port and debug have not been changed. Octopus will attempt to keep the original type if the new value matches the type of the old value.

Hierarchical variables

It is common (and encouraged) to use hierarchical variables in JSON configuration files. This is supported in Octopus variables by using a nested path syntax delimited by colon characters.

For example, to update the value of weatherApi.url and weatherApi.key in the target config file you would configure the Octopus Variables weatherApi:url and weatherApi:key.

Hierarchical JSON

   "weatherApi": {
      "url": "dev.weather.com",
      "key": "DEV1234567"

You can also replace an entire object. For the example above you could set Octopus Variable weatherApi to a value of {"weatherApi":{"url":"test.weather.com","key":"TEST7654321"}}

Array variables

Octopus can also replace a value in a JSON array by using the zero-based index of the array in the variable name.

For example, the variable foo:bar:1 with a value qux will update the value of the second element in the array to be qux:

Hierarchical JSON

   "foo": {
      "bar": [

You can also replace an entire array. For the example above you could set Octopus Variable foo:bar to a value of ["baz","qux"].

Note that you can even use the Variable Substitution Syntax patterns in this file selection input box itself to do things like reference environment specific files, or conditionally include them based on scoped variables.

Learn more

Need support? We're here to help.