ASP.NET Core LaunchSettings.json File

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

Understanding Program.cs Class File in ASP.NET Core

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.

What is a Host in ASP.NET Core?

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.

What is Program Class?

Once you click on the Next button, the Additional Information window will open. 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 click the Create button, as shown in the image below.

ASP.NET Core Main Method in .NET 6

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.

LaunchSettings.json file in ASP.NET Core

As you can see from the above image, the ASP.NET Core Project has a file called launchSettings.json within the Properties folder. Let us discuss the need and importance of this 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 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 them when you publish and deploy your ASP.NET Core Application to the Production Server, you need to store them in the appsettings.json file. Generally, the configuration settings in the ASP.NET Core application are 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"
      }
    }
  }
}
Profiles:

The file contains different profiles for launching the application. Each profile can specify different settings like the application URL, environment variables, command line arguments, etc. These profiles help set up different environments for development, like testing the application in different configurations without changing the code.

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.

ASP.NET Core Application Profile Settings in the launchSettings.json file

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 will host the application and handle incoming HTTP Requests. For a better understanding, please have a look at the table below.

Internal and External Web Server in ASP.NET Core

launchBrowser: A boolean value determining whether a browser is launched when the application starts. That means this property determines whether to launch the browser and open the root URL or not. The value true indicates that it will launch the browser, and the value false means it will not launch the web browser once it hosts the application.

environmentVariables: This is used to set the environment variables that are important during the development phase. 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 dotnetRunMessages property in the launchSettings.json file of an ASP.NET Core project is a relatively less commonly used setting. Its primary function is to enable or disable the display of certain messages when the application is launched using the dotnet run command. The dotnetRunMessages property is typically a boolean value (true or false). Setting it to false suppresses certain run-time messages that are usually displayed when you start the application.

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: one using the HTTP protocol and another using the HTTPS protocol. So, it specifies the URLs on which the application will listen when it’s running. This is useful for testing applications on different ports or host names during development.

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

windowsAuthentication: This property will specify whether Windows Authentication is enabled for your application. If true, it 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. If true, it means Anonymous Authentication is enabled, and false means not.

You need to remember that when you run the ASP.NET Core Application using the .NET Core CLI (i.e., the dotnet run command), the profile with the “commandName”: “Project” will 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.

ASP.NET Core launchSettings.json file

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 that hosts the application and handles incoming requests. Let’s prove this. We need to set the launch Profile as FirstCoreWebApplication, as shown below.

CommandName as Project

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

CommandName as Project

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 and then host the application using the Kestrel Web Server, as shown below.

Hosting the Application using the Kestrel Web Server

Once it launches the command prompt and hosts the application, it opens your default browser by default. 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.

ASP.NET Core launchSettings.json file with Examples

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.

CommandName as IISExpress and AspNetCoreHostingModel as InProcess

The launchSettings.json file shows that the IIS Express profile uses the “commandName”: “IISExpress” value. Please also keep the focus on the application URL, which comes from the iisSettings section, as shown below.

CommandName as IISExpress and AspNetCoreHostingModel as InProcess

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, it will display the value as iisexpress for the worker process name, as shown in the image below. 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.

ASP.NET Core launchSettings.json file

Case 3: CommandName as IISExpress and AspNetCoreHostingModel as OutOfProcess

If we use the CommandName as the IISExpress profile and set the AspNetCoreHostingModel value as OutOfProcess, then ASP.NET Core uses IIS Express as the External Web Server and Kestrel as the Internal Web Server. The External Web Server, i.e., IIS Express, will receive the incoming HTTP Requests and then forward them 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.

ASP.NET Core launchSettings.json file with Examples

Note: The other two cases will be discussed later when we host the application using IIS. You can also change the settings of the launchSettings.json file using the Visual Studio graphical User Interface (GUI).

How do you 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.

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

Once you click on the Open debug launch profile UI button, the window below will open. You can see we have two profiles here: one for IIS Express and the other for Kestrel Web Server. As shown in the image below, you can verify the app URL, hosting model, environment variable, etc.

Setting Launch Profile using Visual Studio GUI

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. Depending on where you run your application, you can change this Environment Variable value to Staging or Production.

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 for the Main method of the Program class file.

Need and Use of ASP.NET Core launchSettings.json file

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

In the next article, I will discuss the ASP.NET Core AppSettings.json File with Examples. 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 understand the need for and use of the ASP.NET Core launchSettings.json file. 

11 thoughts on “ASP.NET Core LaunchSettings.json File”

  1. blank

    Hi,
    When we host the application as apservice in azure.
    Is the Kestrel server is only come in picture for handling request

  2. blank

    I am always confused with this configuration file and the appSettings.json file, I am not able to understand in everything what the Microsoft documentation describes. This tutorial really helps a lot, and it will be one of my favorite bookmarks.

    Thank you!

  3. blank

    Hello, I’m a problem… Can you help me? Come on, I need to access an api that I’m developing from another finish within my network, but when I publish it is always listened to by http://localhost:5000, and I need it was available on the ip of my machine, how do I make it work?

  4. blank

    We are trying to deploy a web api using load balancer (asp.net core 3.1 version), we have firewall access, connection is established .We are also able to access the web api using swagger ui individually from both the nodes while browsing it from IIS but not able to access from the common external URL…please help

  5. blank

    Excellent article again. I was experimenting with hosting a ASP.NET core web api application onto azure kubernates last night and in the yaml kubernates deployment file it deployed onto a NGINX which I had no clue what it was until tonight I understand that since the launchsetting.json file isnt used when it is deployed, it is using a OutOfProcess hosting which links the NGINX load balancer on top of the kestral within the microservice that I deployed my .NET Core web api application onto. Excellent article.

  6. blank

    IIS Express + OutOfProcess we should get iisexpress not Kestrel(our app name) ,because the external web-sv is IISExpress and the internal one is Kestrel.
    Please , is i’m wrong correct me ,becasue i tested it and it gove me the resultat i decripbed above.

  7. blank

    In my case, the properties window looks completely different. I can’t find the settings there which are shown here.

Leave a Reply

Your email address will not be published. Required fields are marked *