Skip to main content
What is launchsetting.json in ASP.NET Core

What is launchsetting.json in ASP.NET Core

I already posted about various json files with ASP.NET Core and a detailed article about project.json file. I briefly also mentioned about launchsetting.json in asp.net 5 ASP.NET Core in my post, but in this post let’s deep dive into it’s each section and understand it. BTW ASP.NET 5 is now ASP.NET Core 1.0.

What is launchsetting.json in ASP.NET Core

This json file holds project specific settings associated with each debug profile, Visual Studio is configured to use to launch the application, including any environment variables that should be used. You can define framework for your project for compilation and debugging for specific profiles. This file is placed in Properties folder.

Launchsetting json in Visual Studio solution explorer

In above paragraph, I mentioned about visual studio project debug profiles and environment variables. Before we move ahead, it’s important to understand about these 2.

Environment Variables

As mentioned on Wikipedia “Environment variables are a set of dynamic named values that can affect the way running processes will behave on a computer. They are part of the environment in which a process runs.” So similarly, there are various environment variables present in ASP.NET 5 which can be set that will affect various parts of the runtime. You can find the complete list here. But for this post, we are interested in ASPNET_ENV variable. This variable actually defines the environment the application is currently running in. There are 3 values are used by convention: Development, Staging, and Production. We are also allowed to set any value which we want.

And if you see Startup.cs class code, you will see these values are used.

public Startup(IHostingEnvironment env)
{
    // Set up configuration sources.
   var builder = new ConfigurationBuilder()
                .AddJsonFile("appsettings.json")
                .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);

   if (env.IsDevelopment())
   {
     // For more details on using the user secret store see http://go.microsoft.com/fwlink/?LinkID=532709
     builder.AddUserSecrets();
   }
   builder.AddEnvironmentVariables();
   Configuration = builder.Build();
}

The above code is checking if running environment is development or not env.IsDevelopment()

Visual Studio Project Debug Profiles

Visual studio supports multiple debug profiles, associated with IIS express and commands defined in project.json.

ASP.NET 5 ships with support for 3 different servers:

  • Microsoft.AspNet.Server.IIS
  • Microsoft.AspNet.Server.WebListener (WebListener)
  • Microsoft.AspNet.Server.Kestrel (Kestrel)

And the default web host for ASP.NET application created using Visual Studio 2015 is IIS/IIS express. Therefore, even for empty website, “Microsoft.AspNet.Server.IIS” dependency is defined in project.json. And in case of web site, there can be 3 different profiles. You can manage settings for each profile in debug tab of project property menu.

Visual Studio Debug Profiles setting

As per the screenshot, you can also define environment variables, launch URL, specific runtime to use for each profile. Please remember the value for ASPNET_ENV (or Hosting:Environment) is case insensitive. But when you try to define the same key again for a different value, you will get duplicate key error.

ASP.NET 5 environment variable duplicate key issue error

So when you modify the default settings for your project, changes are persisted in launchSettings.json. Now let’s take a look at launchsetting.json code.

launchsetting.json code

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:2137/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "Hosting:Environment": "Development"
      }
    },
    "web": {
      "commandName": "web",
      "environmentVariables": {
        "Hosting:Environment": "Staging"
      },
      "sdkVersion": "dnx-clr-win-x86.1.0.0-rc1-update1"
    },
    "kestrel": {
      "commandName": "kestrel",
      "environmentVariables": {
        "Hosting:Environment": "Production"
      },
      "sdkVersion": "dnx-clr-win-x86.1.0.0-rc1-update1"
    }
  }
}

The first part defines the IIS settings as IIS is the default web host choice. And there are 3 profiles “IIS Express”, “web” and “kestrel” in profile section. And for each profile, environment variable, runtime version to use and it’s command name is also defined. As mentioned earlier, command names are defined in project.json file. So when you launch your application using any of the option, setting defined in launchsetting will be used for your web application.

Selecting debug profile while launching the app

We can run the web command from a command prompt using dnx like dnx web. This will host your application and the settings will be picked up from commands.

Startup Conventions

As mentioned earlier that ASPNET_ENV can have 3 values convention: Development, Staging, and Production. And with ASP.NET 5, the Startup class is used for bootstraping the application and loading all your configuration. And there is also a convention exists for Startup.cs and ASPNET_ENV values. You are allowed to create Startup class with environment variable name Startup{EnvironmentName} (for example StartupDevelopment). So you can have StartupDevelopment, StartupStaging and StartupProduction. and based on the ASPNET_ENV environment variable value, that Startup class is used. Thus, it gives you the flexibility to configure Startup settings for different environment.

That’s all folks. Keep visiting this blog and share this in your network. Please put your thoughts and feedback in comments section.

PS: If you found this content valuable and want to return the favour, then Buy Me A Coffee

3 thoughts to “What is launchsetting.json in ASP.NET Core”

  1. I have an auto-generated :

    “commandName”: “Project”,

    What is that?
    A different way of using Kestrel?
    Plus, I have no `project.json`. 🙁

    1. commandName as “Project” means application uses kestrel server and this profile is used by dotnet runtime during CLI command dotnet run

Leave a Reply

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