What is LaunchSettings JSON file?

Launch Settings Image

The use of JSON files as a configuration provider has been a highlight of ASP.NET Core web application development. The JSON files have replaced the ‘.config’ files, used in the ASP.NET framework, and provide the configuration as key-value pairs in a hierarchical structure.

One of the configuration providers, the launchsettings.json file plays an important role to configure and launch a web application on the local development machine. It provides configurable profiles to choose a hosting server for the web application to run.

These profiles can be configured for different environments to reflect the development life cycle of an application. The Hosting environment in the application can dynamically choose the middleware based on the environment variables set up for a profile.

The environment settings can also aid in the display of selective content to users with the help of Environment Tag Helpers.


There are two ways(usu.) to develop and launch a web application using ASP.NET core, these are :

  1. using an Integrated Development Environment(IDE) like Visual Studio, Visual Studio Code, JetBrains Rider, OmniSharp, etc, and/or
  2. using .NET Core Command-line interface (CLI), “a cross-platform toolchain for developing, building, running, and publishing .NET applications“.

For this article, I have used Visual Studio 2019 IDE with .Net Core 3.1 framework. It provides the developer with an IISExpress server to launch and run a web application on the local development machine.

The server is a lightweight, self-contained IIS server, used for the development and testing of web applications, and is the default server for hosting a web application in Visual Studio. For other IDEs like Rider, you may need to download the IISExpress.

For applications developed and launched from .NET CLI, it uses the Kestrel server to host the application. Kestrel is a cross-platform web server for ASP.NET Core, and is included by default in ASP.NET Core project templates.

The launchSetting.json is located in the Properties folder of the ASP.NET core Web application project. We can view and edit the file in the Solution Explorer of Visual Studio 2019, as shown in the following figure.

launchSettings.json file
Location of ‘launchSettings.json’ file in Visual Studio 2019 Solution Explorer.

Note: This settings file has no role in publishing the web application. The web application variables and/or configurations that need to be deployed and published, can be set up in another configuration provider, the ‘appsettings.json’ file.

The ‘launchSettings.json’ file has two sections:

  1. The ‘iisSettings’ section, provides configuration for the IIS or IISExpress servers, like URL with the port number, SSL port, and authentication information, and
  2. The ‘profiles‘ section, has information of the Hosting server long with the command name, environment, and host URL.
Sections in LaunchSettings.json file

The ‘profiles’ section has the IISExpress and ‘Project name’ named profiles by default in the settings file, and is described below:

  1. IISExpress:
    Default profile for running an application in Visual Studio. It uses the IIS Express to host the web application.
    The ‘commandName’ property for this profile is set to ‘IISExpress’.
  2. Project name (The project name of the Web application):
    This profile uses the Kestrel server for hosting.
    The ‘commandName’ property for this profile is set to ‘Project’.

The ‘commandName‘ property in each of the profiles section determines if Kestrel or IIS server is used to host the application. The ‘commandName’ property for a .NET Core web application can be of the following types:
1. IISExpress
2. Project
3. IIS

The Visual Studio IDE contains both the profiles and it uses the ‘IISExpress’ profile by default for web hosting. When we opt for the ‘Project name‘ profile in the IDE, it spawns a .NET Core CLI command, and the CLI in turn launches the Kestrel server to host the web application. Apart from these two profiles, a developer can set up many more named profiles, however confining the ‘commandName‘ property to only those mentioned above. In Visual Studio 2019, we can set up the profile from the UI as shown below:

In .NET Core CLI, we can use the following command to launch the application for a given profile name defined in the settings:
dotnet run –launch-profile “profileName”.

environmentVariables property in launchSettings.json file.

The ‘environmentVariables‘ property in the profiles section holds the ‘ASPNETCORE_ENVIRONMENT‘ variable. This variable can be assigned values reflecting the stages in the application development life cycle. ‘Development’, Staging’ and ‘Production’ are provided by the framework, however, the variable can hold any value like ‘UAT’, ‘Staging2’ etc.

The value assigned to ASPNETCORE_ENVIRONMENT for a given profile is loaded into the Hosting environment during startup and can be used to selectively load middleware like the DeveloperException page for an environment type. Extension methods in the application help to determine the predefined/provided framework environment variables to select the required middleware. Also, based on the Hosting environment chosen, the Environment Tag Helpers can be used to selectively display information to the user.

The Launch settings file should not contain User secrets and it should be configure in the secrets.json file on each development machine.


The launchSettings.json file is a configuration provider for hosting profiles on a local development machine. The hosting profiles use IIS, IISExpress or Kestrel server based on the ‘commandName’ opted in each of the profile sections.

Any number of profiles can be provided based on the development team’s needs. Each of the profiles has the ASPNETCORE_ENVIRONMENT variable, which can be used by the Hosting Environment of the application during application startup.

It can also be used to show environment-specific information to the end-user using the Environment Tag Helpers. Although, the launchSettings.json file is for a local development machine, it can not be used to store User secrets.

Please do let me know of your views in the comment section. If you like the article, please do share it on social.

Leave a Reply

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