ASP.NET Core launchSettings.json file

Back to: ASP.NET Core Tutorials For Beginners and Professionals

ASP.NET Core launchSettings.json file

In this article, I am going to discuss the use and importance of the ASP.NET Core launchSettings.json file in detail. Please read our previous article where we discussed the OuOfProcess Hosting Model in ASP.NET Core Web Application. In order to understand the ASP.NET Core launchSettings.json file, let us first create a new ASP.NET Core application with an empty template.

Creating a new Empty ASP.NET Core Web Application

First, open Visual Studio 2019 and then click on the “Create a new project” box as shown in the below image.

Once you click on the Create a new project box, then it will open the Create a new project window. From this window, you need to select the ASP.NET Core Web Application template and then click on the Next button as shown in the below image.

Once you click on the Next button, then it will open the “Configure Your New Project” window. Here, you need to give the name for your project, set the location of your project, give the solution name. In this example, I will give the name “FirstCoreWebApplication” and then click on the Create button as shown in the image below.

Once you click on the create button, then it will open the Create a new ASP.NET Core Web Application window. From this window, you need to select the Empty Project template and uncheck all the checkboxes from the Advanced section. Please make sure to select .NET Core and ASP.NET Core 3.1 from the respective dropdown list and finally click on the Create button as shown in the below image.

Once you click on the Create button, it will take some time and will create the Empty ASP.NET Core Web Application with the following file and folder structure.

As you can see from the above image, the ASP.NET Core Project has a file called launchSettings.json within the Properties folder. So, let us discuss the need and importance of this launchSettings.json file in the ASP.NET Core application.

Understanding LaunchSettings.json file in ASP.NET Core

The settings that are present within this file are going to be used when we run the .NET core application either from Visual Studio or by using .NET Core CLI.

The most important point that you need to keep in mind is this launchSettings.json file is only used within the local development machine. That means this file is not required when we publishing our asp.net core application to the production server.

If you have certain settings and you want your application to use such settings when you publish and deploy your asp.net core application to the production server, then you need to store such settings in the appsettings.json file. Generally, in the ASP.NET Core application, the configuration settings are going to be stored in the appsettings.json file. In our upcoming article, we will discuss the appsettings.json file in detail.

ASP.NET Core Application Profile settings in the launchSettings.json file:

If you open the launchSettings.json file, then by default you will find the following code or you can say settings within that file in ASP.NET Core 3.1 applications.

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:50409",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "FirstCoreWebApplication": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

In the above launchSettings.json file, within the profiles, we have two sections i.e. IIS Express and FirstCoreWebApplication as shown in the below image.

The point that you need to remember is when you run the application from Visual Studio either by pressing CTRL + F5 or just F5 then by default the profile with “commandName”: “IISExpress” is going to be used. On the other hand, if you run the ASP.NET Core application using .NET Core CLI (i.e. dotnet run command), then the profile with the “commandName”: “Project” is going to be used.  

However, if you want then you can choose which profile to use when you run the application by pressing CTRL + F5 or just F5, by clicking on the drop-down list in Visual Studio as shown below

The value of the commandName property of the launchSettings.json file can be any one of the following.  

1. IISExpress
2. IIS
3. Project

The CommandName property value of the launchSettings.json file along with the AspNetCoreHostingModel element value from the application’s project file will determine the internal and external web server (reverse proxy server) that are going to use and handle the incoming HTTP Requests. For better understanding, please have a look at the below table.

Modifying the Configure method of Startup class

Modify the Configure method of the Startup class file as shown below to display the Name of the worker process that is going to handle the request in the browser window.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGet("/", async context =>
        {
            await context.Response.WriteAsync("Worker Process Name : " +
                System.Diagnostics.Process.GetCurrentProcess().ProcessName);
        });
    });
}

Case1: CommandName as Project

When we use the CommandName as Project in the launchSettings.json file, then ASP.NET Core is going to ignore the AspNetCoreHostingModel value. The Kestrel is the only server that is going to host the application and handle the incoming request. Let’s prove this. Now, we need to set the launch Profile as FirstCoreWebApplication as shown below.

If you look at the launchSettings.json file, then you will see that the FirstCoreWebApplication profile uses the “commandName”: “Project” value, and as well as please focus on the application URL as shown below. In my application the URL is http://localhost:5000 and the port number might be varying in your example.

Now change the AspNetCoreHostingModel element value to InProcess in the application’s project file as shown below.

<Project Sdk="Microsoft.NET.Sdk.Web">
 <PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
  <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
 </PropertyGroup>
</Project>

Now, if you run the project either by pressing CTRL + F5 or just F5, first it will launch the command prompt where it will host the application using the Kestrel server as shown below.

Once it launches the command prompt and hosts the application, then by default it opens your default browser and displays the worker process name as the project name i.e. FirstCoreWebApplication as shown in the below image. This is because when the CommandName value is Project then it ignores the AspNetCoreHostingModel value and Kestrel is the only server that is going to host and process the incoming requests.

Case2: CommandName as IISExpress and AspNetCoreHostingModel as InProcess

If we use the CommandName as IISExpress profile and if we set the AspNetCoreHostingModel value as InProcess in the applications project file, then IIS Express is the only server that is going to host and handle the incoming HTTP request. Let us prove this. First, use IIS Express as the lunch profile by selecting IIS Express from the drop-down list as shown below.

Now, if you look at the launchSettings.json file, then you will see that the IIS Express profile use the “commandName”: “IISExpress” value and also please keep the focus on the application URL which is coming from the iisSettings section as shown below

We already set the AspNetCoreHostingModel element value to InProcess. Now, when we run the application either by pressing CTRL + F5 or just F5, then it will display the value as iisexpress for the worker process name as shown in the below image and also have a look at the browser URL. This proves that IIS Express is the only web server that is going to host the application as well as handles the incoming HTTP Requests.

Case3: CommandName as IISExpress and AspNetCoreHostingModel as OutOfProcess

If we use the CommandName as IISExpress profile and if we set the AspNetCoreHostingModel value as OutOfProcess then ASP.NET Core uses IIS Express as the external web server and Kestrel is the internal webserver. The external web server i.e. IIS Express will receive the incoming HTTP Requests and then forward the request to the internal web server i.e. Kestrel which is going to process the request. Let us prove this.

As we already set the launch profile as IIS Express, we just need to change the AspNetCoreHostingModel element value to OutOfProcess in the application’s project file as shown below.

<Project Sdk="Microsoft.NET.Sdk.Web">
 <PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
 </PropertyGroup>
</Project>

That’s it. Run the application and it should display the project name as the worker process name as shown in the below image as the request is internally handled by Kestrel Web Server.

The rest two cases we will discuss in a later article when we host the application using IIS. If you want then you can also change the settings of the launchSettings.json file using the Graphical User Interface (GUI) provided by Visual Studio.

How to access the Graphical User Interface (GUI) in Visual Studio?

To do so, right-click on the project name in Solution Explorer and then select the “Properties” option from the context menu. Once you open the project properties window, click on the “Debug” tab on the as shown in the below image.

Using the Graphical User Interface, you can also change the settings of the launchSettings.json file. Now here you can see that the Environment Variable “ASPNETCORE_ENVIRONMENT” is set to “Development”. You can change this Environment Variable value to Staging or Production depending on where you are running your application.

If you want, then you can also add new environment Variables. These environment variables are available throughout your application. And if you want then you can also execute some code conditionally depending on the environment variables value. For example, consider the following Configure() method of Startup.cs file.

It checks if the environment is Development, then it is going to display the Developer Exception Page. In our upcoming articles, we are going to discuss more these environment variables. 

In the next article, I am going to discuss the ASP.NET Core Startup class in detail. Here, in this article, I try to explain the ASP.NET Core launchSettings.json file in detail. I hope this article will help you to understand the need and use of ASP.NET Core launchSettings.json file.