Mastering launchSettings.json in .NET

Imagine a control panel for your application's launch configurations. That's precisely what launchSettings.json is. This JSON file resides in the Properties folder of your ASP.NET Core project and defines various profiles for running your application under different circumstances. It contains configuration settings for launching your application within development environments. These settings include environment variables, profiles, and which web server is used for hosting the application during debugging sessions.

Important Note: The launchSettings.json file is only used on the local development machine. It is not deployed to production or other environments. 

Here's why launchSettings.json is essential:

• Multiple Environments: Define separate launch profiles for development, staging, and even testing. Each profile can have its own specific settings, mimicking different deployment environments.
• Web Server Choice: Choose between launching with IIS Express (a lightweight development web server) or the built-in Kestrel web server.
• Configuration Overrides: Override system environment variables with profile-specific settings for a more controlled development experience.

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:36077",
      "sslPort": 44352
    }
  },
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "http://localhost:5242",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "https://localhost:7167;http://localhost:5242",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Let’s break down the important sections:

•  $schema: Provides a URL (http://json.schemastore.org/ launchsettings.json) to a JSON schema that describes the structure and constraints of the launchSettings.json file.
• iisSettings: Contains settings related to running the application on IIS Express, including URL bindings and authentication settings.
• profiles: Defines different profiles for launching the application. Each profile can have a unique configuration, allowing for flexibility in how you run the application (e.g., using IIS Express vs. running it directly using the .NET CLI)

iisSettings is a configuration section within launchSettings.json that specifically targets settings related to Internet Information Services (IIS) when running an ASP.NET Core application.

 "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:36077",
      "sslPort": 44352
    }
  }

Key Properties and Their use

1.  windowsAuthentication:  This is mostly not useful in most scenarios and by default it is false. This authentication method is typically used in intranet environments where users are part of a centralized directory, like Active Directory (AD). It allows the app to authenticate users automatically by leveraging their Windows credentials, without requiring them to re-enter their username and password.

    

2. anonymousAuthentication: This allows users to access the application without providing any credentials. It permits anyone to access the resources, and no authentication mechanism is triggered.

    

3. iisExpress: These settings are specifically related to IIS Express, a lightweight, local web server used in development environments to mimic the behavior of IIS in production.

    

   1. applicationUrl: This defines the URL where your application will be accessible when running on IIS Express. It’s specific to IIS Express and controls which HTTP port will be used when your app runs on this server.

       

   2. sslPort: Only applies when IIS Express is used as the local server and when testing over HTTPS is required.

The profiles section defines different configurations for launching your application. Each profile specifies settings such as the command to run, whether to launch a browser, the URL to use, and environment variables. These profiles help you run your application in different environments or configurations easily.  

Here is a brief explanation of each profile in your launchSettings.json: 

Note: The iisSettings section provides global settings for IIS Express, while the IIS Express profile in the profiles section specifies settings for launching the application using IIS Express. Both sections can coexist and serve different purposes.

"http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "http://localhost:5242",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },

When using the Project as the CommandName with HTTP, the ASP.NET Core app is hosted by Kestrel, regardless of the AspNetCoreHostingModel. This bypasses the IIS server entirely, making Kestrel the primary handler for HTTP requests.

Kestrel Hosting: Kestrel serves as the main web server, listening on the specified port (5242). This setup is ideal for development scenarios where you need a lightweight, cross-platform solution.

• commandName: "Project"
  This tells .NET to run the main project directly when debugging or running the app.
• dotnetRunMessages: true
  Enables more verbose output in the console during dotnet run, helping you monitor the startup process.
• launchBrowser: true
  Automatically opens the browser when the app starts, useful for web applications.
• launchUrl: "swagger"
  Specifies that the app should open at the Swagger UI, great for API documentation right out of the box.
• applicationUrl: "http://localhost:5242"
  Defines the local development URL where the app will be hosted. In this case, the app runs at http://localhost:5242.
• ASPNETCORE_ENVIRONMENT: "Development"
  Sets the environment variable to Development, which activates development-specific settings like detailed error pages and relaxed security.

Tip: Use this configuration to experiment with Kestrel’s performance under heavy loads or SSL termination, as Kestrel is also used in production behind reverse proxies like Nginx or Apache.

"https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "https://localhost:7167;http://localhost:5242",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },

Dual URLs (HTTP & HTTPS): This allows you to run the app over both secure (7167) and non-secure (5242) channels. With the HTTPS profile, you can test secure communication locally. For example, you can inspect how SSL termination impacts response times in Kestrel.

• applicationUrl: "https://localhost:7167; http://localhost:5242"
  Here's the key difference: this configuration supports both HTTPS (https://localhost:7167) and HTTP (http://localhost:5242). By including both URLs, the app is accessible securely over HTTPS and also via HTTP for backward compatibility or testing in environments without SSL.

"IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }

• commandName: "IISExpress"
  This indicates the use of IIS Express to run the application. IIS Express is commonly used for testing and debugging ASP.NET Core apps in a local environment, mimicking the behavior of a full IIS server.
• launchUrl: "swagger"
  The Swagger UI remains the default launch page, consistent with the "http" and "https" setups for easy access to API documentation.
• environmentVariables: { "ASPNETCORE_ENVIRONMENT": "Development" }
  As before, the environment is set to Development, enabling debugging-friendly features and detailed error messages.

When using IIS Express as the host, ASP.NET Core allows you to either run the app InProcess or OutOfProcess. 

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
  </PropertyGroup>
</Project>

• InProcess Hosting: Here, the app runs inside the IIS worker process (w3wp.exe), giving it direct access to IIS’s request pipeline. This improves performance by removing the overhead of reverse-proxy communication between IIS and Kestrel.
• Worker Process: The worker process name will be iisexpress, as the requests are handled directly by IIS.

Tip: In-process hosting is generally faster because it avoids the additional HTTP layer between IIS and Kestrel. Use this for higher performance in scenarios where IIS is expected to be the front-facing server.

In the OutOfProcess hosting model, IIS Express is still the external server, but it forwards requests to the internal Kestrel server, which actually runs your app code. This is the default hosting model for ASP.NET Core.

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
  </PropertyGroup>
</Project>

• OutOfProcess Hosting: Here, Kestrel is used as the internal web server, processing requests forwarded by IIS Express. The main advantage is the cross-platform nature of Kestrel and its simplicity.
• Worker Process: The process name will now reflect dotnet, as Kestrel is responsible for handling the requests after IIS forwards them.

Tip: While out-of-process hosting offers more flexibility, in certain high-throughput applications, this additional forwarding can introduce latency. Profiling tools like dotnet-counters can help you measure the impact of IIS-to-Kestrel handoff.

1. Simulating Different Environments Locally: Although launchSettings.json is only used during local development, specifying ASPNETCORE_ENVIRONMENT allows you to simulate different environments (like Development, Staging, or Production) without needing a full production setup. This is crucial for testing how the app behaves under different conditions.

2. Loading Environment-Specific Configuration: ASP.NET Core loads different configuration files based on the environment:

   • appsettings.Development.json
   • appsettings.Staging.json
   • appsettings.Production.json

   By specifying ASPNETCORE_ENVIRONMENT in launchSettings.json, you ensure the correct configuration file is loaded when debugging locally.

3. Development-Specific Features: The Development environment, as specified in launchSettings.json, enables developer-friendly features like detailed error pages, hot-reloading, and debugging tools, which you wouldn't want in production. This ensures you get an optimal debugging experience locally.
4. Prepares for Environment Transitions: Even though the app runs in Development locally, specifying ASPNETCORE_ENVIRONMENT lets you test production-like behaviors in certain scenarios. For instance, you might want to temporarily switch to Staging or Production in your local machine to test features like performance optimizations or limited error logging.