(C# ASP.NET Core) The launchSettings.json File and launch Profiles

Recap of the Previous Tutorial

In the previous tutorial we learned of the various options for running an ASP.NET Core application in a real-life, production scenario. We saw that there are three broad possibilities of launching an app: (i) run it as a standalone application, directly through Kestrel (ii) run it through Kestrel in OutOfProcess mode with IIS as a proxy server and (iii) run it through the built-in IISHttpServer, with IIS in the InProcess mode.

Video Explanation

Please watch the following youtube video:

Objective of this Tutorial

Every asp.net core developer would want to easily run the app in each of these various modes so that the application can be tested and debugged without a full publish of the app.

Visual Studio supports all the various launch modes so that an application can be tested and debugged without a full publish to the internet. For this purpose, it maintains a file called launchSettings.json.

In this tutorial we shall study the launchSettings.json file, then add a new profile, and finally launch a project with all the launch profiles, and verify that the application does indeed run as desired.

Step 1: Create an ASPNET Core Project

Open visual studio and create a simple asp.net core project.

You can create a project of one razor page called Index, and write any html that displays a message.

We shall use this project to learn about the various launch profiles. See the linked video to have a look at the project I created.

Step 2: Examine the launchSettings File

Visual studio maintains a file called launchSettings.json in a folder called Properties. This file contains various options for launching your app.

The various features of this file are:

1. launchSettings is used only by visual studio - it is never deployed to a production server.
2. It is auto-generated by visual studio.
3. It can be edited as per the needs.

Let us double-click to open this file.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:57948",
      "sslPort": 44387
    }
  },

  "profiles": {

    "MyRazorApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "https://localhost:72...",
      "dotnetRunMessages": true
    },

    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },

// more can be added 

    "IIS Express (OutOfProcess)": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "ancmHostingModel": "OutOfProcess",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }

In my file there is a section called iisSettings. This section describes the settings for the ports and IIS authentication. These settings are used whenever the application uses IIS Server.

The file also contains a section called profiles. In my case there are two profiles - one is of the same name as the project (the name of my project is MyRazorApp), and the other is called IIS Express. These profiles describe various self-explanatory properties. These profiles were added by visual studio when I created my project.

A property of interest is commandName. If the value is Project, then the asp.net core application will run as a standalone application directly through Kestrel. But, if the value is IISExpress, then the application will use IIS Express in the default InProcess mode - Kestrel will not be used.

Visual studio added no profile for OutOfProcess mode. So I have added a new profile to support the OutOfProcess mode, that uses IIS as a proxy for Kestrel. We can give any readable name to this profile, such as IIS Express (OutOfProcess). We have copied everything of the IIS Express existing profile, and added a property ancmHostingModel with the value equal to OutOfProcess. Note that if this property is not mentioned, then the default value is InProcess.

Also notice that each profile can set its own environment variable to "Development", "Staging", "Production" or whatever.

Look! how convenient everything is!

Step 3: Using the launch Profiles

Now it is time to use these profiles and run the application in various modes.

Open the Standard toolbar by using the menu View > Toolbars > Standard.

This toolbar has a dropdown of all the profiles listed in the launchSettings file. The names are exactly the same as we described in the launchSettings.json file.

Let us click the first profile (of the name MyRazorApp) and launch the application. This profile will launch the application as a standalone.

Observe that a console window opens and the log of messages can be seen as well. Kestrel is directly accepting our requests. We can even examine the http headers through a browser such as Chrome or Edge, to verify that the server is indeed shown as Kestrel.

Let us now select the second profile (named IIS Express) and run the app. Now the app runs in the default InProcess mode where it runs in the same process as of IIS. In this case Kestrel is not used. We can examine the headers to verify that the server is shown as IIS, as expected! because the application runs in the process space of IIS.

Finally, we can run the app in the OutOfProcess mode by selecting the third profile that we added. In this case IIS Express is used as a proxy of the kestrel server. We can examine the headers to verify that the server is shown as Kestrel, as expected! because the main server is Kestrel, whereas IIS is just a proxy.

Step 4" "Using the Launch Profiles GUI

Visual Studio provides an alternative GUI based visual method for managing the launchSettings.json file.

For this, dropdown of launch settings by clicking the same toolbar and select debug properties. Click it. You will see that a Launch Profiles window opens that shows all our profiles stacked on the left hand side. These profiles have been picked from the launchSettings.json file. (Please do refer the linked video if this is not clear)

You can delete, add and edit existing profiles through this interface. Any changes you make here are automatically synced with the launchSettings file. For example, hosting model can be chosen from a dropdown, and localhost ports can be set through the textboxes.

You can obtain this project from your downloads. We'll close it right now, thanks!