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 will discuss the ASP.NET Core LaunchSettings.json File with Examples. Please read our previous article, discussing the ASP.NET Core OutOfProcess Hosting Model with Examples. 

ASP.NET Core LaunchSettings.json File

In ASP.NET Core, the launchSettings.json file is a configuration file used to configure various aspects of how our application should be launched and debugged during development. This file is typically found in the “Properties” folder of our ASP.NET Core project and is used primarily by the Visual Studio IDE and the .NET CLI (Command-Line Interface). To understand the ASP.NET Core launchSettings.json file, first create a new ASP.NET Core application with an empty template.

Creating a new Empty ASP.NET Core Web Application

Create a new ASP.NET core application using the ASP.NET Core Empty template. To create a new Empty ASP.NET Core Web Application, open Visual Studio 2022 and click the Create a new project tab, as shown in the image below.

Once you click on the Create a new project tab, it will open the Create a new project window. You need to select the ASP.NET Core Empty project template from this window and click the Next button, as shown in the image below.

Once you click on the Next button, it will open the Configure Your New Project window. Here, you must provide the necessary information to create a new project. First, give an appropriate name for your project (FirstCoreWebApplication), set the location where you want to create this project, and the solution name for the ASP.NET Core Web application. And finally, click on the Create button, as shown in the image below.

Once you click on the Next button, it will open the Additional Information window. Here, you need to select .NET 6.0 as the Framework. You also need to check the Configure for HTTPS and Do not use top-level statements check boxes, and finally, click on the Create button as shown in the image below.

That’s it. Once you click the Create Button, the project will be created with the Empty template with the following folder and file 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 within the LaunchSettings.json file will be used when we run or launch the ASP.NET core application either from Visual Studio or by using .NET Core CLI. The most important point you need to remember is that this launchSettings.json file is only used within the local development machine. This file is not required when we publish our ASP.NET Core Application to the Production Server.

If you have certain settings and 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 will 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 6 (.NET 6) Applications.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:23307",
      "sslPort": 44333
    }
  },
  "profiles": {
    "FirstCoreWebApplication": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7017;http://localhost:5159",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "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 image below.

We can configure different profiles with different settings based on our development needs. When we run our ASP.NET Core application in Visual Studio or using the .NET CLI, we can select one of these profiles to specify how our application should be launched and debugged. Let us understand Each Property and its uses in the ASP.NET Core Web Applications:

CommandName: The value of the Command Name property of the launchSettings.json file can be any 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 is going to be used to host the application and handle the incoming HTTP Requests. For a better understanding, please have a look at the below table.

launchBrowser: This property determines whether to launch the browser and open the root URL. The value true indicates that it will launch the browser and the value false means it will launch the web browser once it hosts the application.

environmentVariables: This property allows us to declare configuration values. By default, it includes one configuration key called ASPNETCORE_ENVIRONMENT, using which we can specify the environment, such as Development, Production, and Staging.

dotnetRunMessages: The whole purpose of this setting, which is not officially documented anywhere as far as I can tell, is to give some immediate feedback upon running dotnet run or dotnet watch inside a terminal. Without it set to true, on the first run after creating a new .NET core/ .NET 5 app, it might take a few seconds before some actual text feedback is shown, which might confuse the user. Following is the Stack Overflow Reference: https://stackoverflow.com/questions/65923063/purpose-of-dotnetrunmessages-in-launchsettings-json

applicationUrl: The applicationUrl property specifies the application base URL(s) using which you can access the application. If you enable HTTPS while creating the project, you will get two URLs, i.e., one URL using HTTP protocol and another URL using HTTPS protocol.

sslPort: This property specifies the HTTPS Port number to access the application in the case of an IIS Express Server. The value 0 means you cannot access the application using HTTPS protocol.

windowsAuthentication: This property will specify whether Windows Authentication is enabled for your application. If true means Windows Authentication is enabled, and false means it is not enabled.

anonymousAuthentication: This property will specify whether Anonymous Authentication is enabled for your application or not. If true means Anonymous Authentication is enabled, and false means it is not enabled.

The point that you need to remember is when 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.  

On the other hand, you can decide which profile to use when you run the application using Visual Studio. That means you can choose which profile to use when you run the application in Visual Studio just by clicking on the drop-down list in Visual Studio, as shown below.

Modifying the Main Method of the Program Class

Now, modify the Main Method of the Program class as shown below to display the Name of the worker process that will handle the request in the browser window.

namespace FirstCoreWebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);
            var app = builder.Build();

            app.MapGet("/", () => $"Worker Process Name : {System.Diagnostics.Process.GetCurrentProcess().ProcessName}");

            app.Run();
        }
    }
}

Case 1: CommandName as Project

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

If you look at the launchSettings.json file, you will see that the FirstCoreWebApplication profile uses the “commandName”: “Project” value, and as well as please focus on the application URLs as shown below. My application’s URLs are https://localhost:7017;http://localhost:5159, and the port number might vary in your example. One URL is to handle the HTTP request, and another is to handle the HTTPS requests.

Add the AspNetCoreHostingModel Element with the value InProcess in the application’s project file, as shown below.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
  </PropertyGroup>

</Project>

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

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

Case 2: CommandName as IISExpress and AspNetCoreHostingModel as InProcess

If we use the CommandName as the 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.

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

In the application project file, 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. Also, have a look at the browser URL. This proves that IIS Express is the only Web Server hosting the application and handling the incoming HTTP Requests.

Case 3: CommandName as IISExpress and AspNetCoreHostingModel as OutOfProcess

If we use the CommandName as the 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 Web Server. 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 will process the request. Let us prove this.

As we already set the launch profile as IIS Express, we 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>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
  </PropertyGroup>

</Project>

That’s it. Run the application, which should display the project name as the worker process name, as shown in the image below, as the Kestrel Web Server handles the request internally.

Note: The other two cases will be discussed later when we host the application using IIS. If you want, 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 select the “Properties” option from the context menu. Once you open the project properties window, click the “Debug” tab, as shown in the image below.

Once you click on the Open debug launch profile UI, it will open the below window. You can see here we have two profiles. One is for IIS Express, and the other is for Kestrel Web Server. You can verify the App URL, Hosting Model, Environment Variable, etc, as shown in the image below.

Using the Graphical User Interface, we can also change the settings of the launchSettings.json file. 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 run 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 variable’s value. For example, consider the following code of the Main method of the Program class file.

It checks if the environment is in Development and then displays the Developer Exception Page. In our upcoming articles, we will discuss these environmental variables more. 

In the next article, I will discuss the ASP.NET Core AppSettings.json File with Examples. Here, in this article, I try to explain the ASP.NET Core launchSettings.json File in detail with Examples. I hope this article will help you to understand the need and use of the ASP.NET Core launchSettings.json file.