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

The launchSettings.json file in ASP.NET Core is a configuration file used to configure how the application starts during development. It’s primarily used by development tools like Visual Studio, Visual Studio Code, and the .NET CLI (dotnet run) to configure how the application is launched during development. It’s located in the Properties folder of an ASP.NET Core project.

The launchSettings.json file contains configurations for different profiles, which specify how the application should be launched. Each profile can define settings such as the environment variables, the server to use (e.g., Kestrel, IIS Express), the application URL, and more. This allows developers to easily switch between different launch configurations without modifying the application code.

Key Settings of launchSettings.json file:

The following are some of the key primary settings that we are doing in the launchSettings.json file:

• Profile Configuration: Define multiple launch profiles for different scenarios (e.g., running with IIS Express, Kestrel, or using both IIS and Kestrel).
• Environment Variables: Specifies environment variables that are available when the application runs (e.g., Development, Staging, Production),
• Application URLs: Specify the URLs the application will listen on during development.
• Launch Browser: This setting determines whether a browser should be automatically launched when the application starts and which URL it should open.

Example to Understand launchSettings.json file in ASP.NET Core:

To understand the ASP.NET Core launchSettings.json file, first create a new ASP.NET Core application with an empty project template. To create a new Empty ASP.NET Core Web Application, open Visual Studio 2022 and click on the Create a new project tab as shown in the image below.

Once you click on the Create a new project box, it will open the “Create a new project” window. This window includes different .NET application templates. Here, we will create a simple Web application from scratch, so select the ASP.NET Core Empty Project template and then click on the Next button, as shown in the image below.

Once you click on the Next button, it will open the following Configure Your New Project window. Here, you need to 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 Next 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 8 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.

Once you click on the Create button, it will create a new ASP.NET Core Web Application in Visual Studio 2022 using .NET 8. The project will be created with the following file and folder structure in Visual Studio 2022.

As you can see in 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 most important point you need to remember is that this launchSettings.json file is only used within the local development machine when we run the application using Visual Studio, Visual Studio Code, and .NET CLI. 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 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 application-level configuration settings will be stored in the appsettings.json file.

ASP.NET Core launchSettings.json file:

The launchSettings.json file in an ASP.NET Core project defines various profiles (such as HTTP, HTTPS, and IIS Express) for running the application in different environments (like Development, Staging, or Production) with specific configurations. It allows developers to define settings like the server type, application URL, environment variables, and more, making it easy to run the application in different contexts during development.

The launchSettings.json file is located in the Properties folder of the ASP.NET Core project. It has a JSON structure and contains different profiles, each specifying how the application can be launched. When we create a new ASP.NET Core project, we typically find some default settings like the ones below:

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:53952",
      "sslPort": 44312
    }
  },
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:5066",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7107;http://localhost:5066",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Understanding ASP.NET Core LaunchSettings Profiles

Each profile under the “profiles” section provides a different way to launch the application during development. Profiles can specify settings like the application URL, environment variables, whether to launch the browser, and more. By default, it comes with the following three profiles:

HTTP Launch Profile:

The HTTP profile runs the application over HTTP without HTTPS and bypasses IIS Express.

• commandName: “Project” – This indicates that the application should be run directly using the Kestrel server (bypassing IIS/IIS Express).
• launchBrowser: true – If true, the browser will automatically open at the application root URL when the project starts. If false, the browser will not be opened.
• environmentVariables – These are used to set environment variables that are essential during the development phase. For example, the ASPNETCORE_ENVIRONMENT variable can be set to Development, Staging, or Production to simulate different environments on your development machine.
• dotnetRunMessages: true – This enables additional messages to be displayed when the project is built and run using the .NET CLI.
• applicationUrl – Specifies the URL for accessing the application here “http://localhost:5066”.

HTTPS Launch Profile:

Similar to the “http” profile, it includes configurations for both HTTP and HTTPS protocols.

• applicationUrl: “https://localhost:7107;http://localhost:5066” – This means the application will listen on both HTTP (http://localhost:5066) and HTTPS (https://localhost:7107). HTTPS is preferred for secure communication.

IIS Express Launch Profile:

The IIS Express profile runs the application using IIS Express, a lightweight version of IIS for development environments.

• commandName: “IISExpress” – This indicates that the application will run under IIS Express, a lightweight, self-contained version of IIS that is optimized for the development environment.
• launchBrowser: true – Automatically opens the browser to the application URL when the project starts, similar to other profiles.
• environmentVariables – Sets ASPNETCORE_ENVIRONMENT to “Development”.

Note: The IIS Express profile allows testing of how the application behaves in an IIS-hosted environment without deploying it on a full IIS server.

IIS Settings

The following are the settings that will be used by the IIS Express profile:

These settings are specific to IIS Express and affect how the application runs when using the IIS Express profile.

• windowsAuthentication: false – Indicates that Windows Authentication is disabled. If set to true, Windows Authentication is enabled.
• anonymousAuthentication: true – Specifies whether Anonymous Authentication is enabled for your application. Setting it to true means any user can access the application without credentials.
• applicationUrl: http://localhost:53952 – Specifies the base URL for the application under IIS Express, like “http://localhost:53952”.
• sslPort: 44312 – Specifies the port to use for SSL (HTTPS) traffic when using IIS Express. If the value is 0, the application cannot be accessed using HTTPS.

Global Settings

• $schema: This provides a URL (http://json.schemastore.org/launchsettings.json) to a JSON schema that helps IDEs validate the structure of launchSettings.json. This schema reference is useful for JSON structure validation in editors like Visual Studio.

Important Points:

Profiles Usage: Each profile can be selected when running the application, allowing developers to test the application in different environments (e.g., with HTTP, HTTPS, or under IIS Express). You can switch between profiles using Visual Studio or setting the appropriate launch settings in your terminal.

Environment Variables: The ASPNETCORE_ENVIRONMENT environment variable is crucial for running your application in different environments (e.g., Development, Staging, Production). Depending on the value of this variable, different configurations are loaded (such as connection strings, logging settings, etc.).

Modifying the Main Method of the Program Class

Now, modify the Program class, as shown below, to display the name of the worker process that will process 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: Using HTTP Profile

When we use the HTTP profile to launch our application, then Kestrel is the only Web Server that is going to host the application and process the incoming HTTP requests. Here, there will be no In-Process or Out-Of-Process hosting model.

If you look at the launchSettings.json file, then you will see that the HTTP profile uses the commandName as Project (project means Kestrel Web Server), and also, please focus on the application URL of the HTTP profile. In my case, the URL is http://localhost:5066, and the port number might vary in your case.

Now, run the project either by pressing CTRL + F5 or just F5. It will launch the command prompt, and it will host the application using the Kestrel Web Server, as shown below.

Once it launches the command prompt and hosts the application, it opens the default web browser. It displays the worker process name as the project name, i.e., FirstCoreWebApplication, as shown in the image below.

Case 2: Using HTTPS Profile

Similar to the HTTP Profile, when we use the HTTPS profile to launch the application, Kestrel is the only Web Server that will host the application and process the incoming HTTP requests.

If you look at the launchSettings.json file, for the HTTPS profile, it uses two URLs (https://localhost:7107; http://localhost:5066) separated by comma. That means, with this profile, we can access the application using both HTTP and HTTPS protocols.

Now, run the project with HTTPS launch profile, then first it will launch the command prompt where it will host the application using the Kestrel Web Server as shown below. Here, you can see we have two URLs to access the project. One uses HTTP, and the other one uses HTTPS protocol.

Once it launches the command prompt and hosts the application, then by default, it opens the default web browser with the HTTPS protocol. It displays the worker process name as the project name, i.e., FirstCoreWebApplication, as shown in the image below. You can also access the application using the HTTP protocol.

Case 3: Using IISExpress Profile with In-Process Hosting Model

If we use the IISExpress profile and set the hosting model to InProcess, IIS Express is the only web server to host the application and handle the incoming HTTP requests. To do so, first, modify the application project file as follows. Here, we are adding the AspNetCoreHostingModel element with the value as InProcess.

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

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

</Project>

Now, if you look at the IIS Settings, which the IIS Express profile will use, you will see that it uses the 53952 port number for the HTTP protocol and 44312 for the HTTPS Protocol. And, if you look at the IIS Express profile section, you will see it uses the “commandName”: “IISExpress.”

Now, run the application using the IIS Express profile. You will observe one thing: no command prompt is opened (as Kestrel Web Server is not used). In this case, IIS Express is the only Web Server that hosts and handles the incoming HTTP requests. If you look at the browser, it displays the worker process name as iisexpress.

Case 4: Using IISExpress Profile with OutOfProcess Hosting Model

If we use the IISExpress profile and set the hosting model as OutofProcess, ASP.NET Core uses IIS Express as the External Web Server, which will host the application, and Kestrel as the Internal Web Server, which will execute our application code.

In this case, the External Web Server, i.e., IIS Express, will receive the incoming HTTP Requests from the client and then forward that request to the Internal Web Server, i.e., Kestrel, which will process the request. To do so, first, modify the application project file as follows. Here, we are modifying the AspNetCoreHostingModel element with the value OutofProcess.

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

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
  </PropertyGroup>

</Project>

Now, run the application with the IIS Express profile, and it should display the project name as the worker process name, as shown in the below image, as the Kestrel Web Server internally processes the request.

Note: The launchSettings.json is primarily for development purposes. In production, environment variables are typically set through the hosting environment or deployment pipeline.

How Do We 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, the following window will open. You can see that we have three Launch Profiles here. One is for IIS Express, and the other two (HTTP and HTTPS) are for Kestrel Web Server. Here, you can also verify and modify the App URL, Hosting Model, Environment Variable, etc., as shown in the image below.

Points to Remember when working with GUI to update Launch Settings:

When we make changes to the launch settings in Visual Studio’s GUI, Visual Studio updates the launchSettings.json file accordingly. This means that the GUI is a convenient way to edit the launchSettings.json file. Since the GUI updates the launchSettings.json file, there is no conflict between the two; they are essentially two interfaces to the same set of configurations.

For example, if we specify an application URL, Hosting Model, or Environment name in both the Visual Studio GUI and the launchSettings.json file, the actual setting used when you launch the application will be the one reflected in the launchSettings.json file because the GUI edits this file.

In the next article, I will discuss the ASP.NET Core AppSettings.json File with Examples. In this article, I 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.