launchSetting.json File in ASP.NET Core.

When you're building ASP.NET Core applications, your focus is usually on the core logic, APIs, UI, or database layers. But there's one small file quietly sitting in your project that can significantly improve your development experience, and that's the launchSettings.json file.

Suppose you've ever wondered how your app knows which port to run on, how to open Swagger by default when debugging, or how to simulate different environments like Development or Staging without changing your code. In that case, you're about to find your answer.

In this guide, you’ll learn what the launchSettings.json file does, how you can customize it, and how to use it to streamline your development workflow. Whether you're using Visual Studio, Visual Studio Code, or the .NET CLI, mastering this file will help you build, run, and test your applications more efficiently. Let's dive in!

What is launchSettings.json?

launchSettings.json is a development-only configuration file used by Visual Studio, Visual Studio Code, and the .NET CLI. It defines how your ASP.NET Core app starts during development, including which port to use, which server to run on (Kestrel or IIS Express), whether to open a browser, and even which environment variables to set.

This file allows you to configure:

Which server to use (like Kestrel or IIS Express)
What ports or URLs should your app listen to
Whether a browser should open when debugging starts
What environment variables should be set (like ASPNETCORE_ENVIRONMENT)
Which launch profile should be used (for different debugging scenarios)

It’s important to know that launchSettings.json is not used in production, and it only affects how your app runs locally while developing and debugging.

Where to Find launchSettings.json in ASP.NET Core?

When you create a new ASP.NET Core project using Visual Studio or the .NET CLI, a file named launchSettings.json is automatically created for you.

Path to Find:

YourProjectFolder/
└── Properties/
    └── launchSettings.json

So if your project is named MyWebApp, you’ll find the file at:

MyWebApp/Properties/launchSettings.json

If it's missing, don’t worry — you can create it manually inside the Properties folder, or let Visual Studio regenerate it by enabling project debugging or launch profiles.

Understanding the Structure of launchSettings.json.

launchSettings.json structure is designed around the concept of profiles, each representing a different way your app can be launched, such as through Kestrel, IIS Express, or Docker.

launchSettings.json File

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:9866",
      "sslPort": 0
    }
  },
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:5155",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Now let’s break down each part in detail.

1. Profiles Section

At the heart of the file is the profiles object. Think of each profile as a self-contained configuration unit that describes a launch mode.

Each profile has a name (e.g., "IIS Express", "MyApi").
Profiles are typically tied to how the developer intends to run or test the application in a specific context.
You might have one profile for API testing and another for UI debugging, all isolated yet contained in the same file.

You can select your profile from the start button of Visual Studio as shown below:

2. commandName

The commandName within a profile acts as the execution strategy. It determines what kind of host will launch your app.

Theoretical values include:

"Project": Indicates the app should run using the default Kestrel web server.
"IISExpress": Used when the app is hosted via IIS Express (Windows-specific).
"Docker": Used when your app is containerized and launched via Docker tools.
"Executable": Allows launching an external executable instead of a .NET project.

This abstraction allows your launch profiles to be agnostic of infrastructure and geared more toward intention (e.g., "run my app inside a container" vs. "run using the built-in server").

3. applicationUrl

This element defines the network bindings for the application during development. It tells the development host (like Kestrel) which ports and protocols (HTTP/HTTPS) the application should listen on.

The presence of both HTTP and HTTPS reflects:

A need for secure local testing
Compatibility with different local service consumers
Simulation of real-world hosting conditions

4. launchBrowser & launchUrl

These two elements describe the startup behavior of your development session:

launchBrowser specifies whether to automatically open a browser.
launchUrl defines the path or endpoint that the browser should navigate to after the app starts.

This abstracts the idea of launching your app into a specific state — such as the Swagger UI for APIs — giving you control over the first interaction with your running application.

5. environmentVariables

Environment variables represent runtime configuration values that are injected into the app process when launched.

From a theoretical view:

They enable environment-specific behaviors (e.g., showing debug info in Development mode).
They act as a loose coupling mechanism, allowing the app to adapt its behavior based on externalized values.
The primary variable you’ll often set is ASPNETCORE_ENVIRONMENT, which the ASP.NET Core framework uses to determine which appsettings.{Environment}.json file to load.

This section empowers you to simulate real-world deployment behaviors without altering code or core config files.

6. dotnetRunMessages

This optional flag enables diagnostic verbosity during command-line execution. It provides insight into listening addresses, host readiness, and runtime logs useful during CLI-based workflows.

Theoretically, this enhances developer observability during local execution and supports script-driven environments (CI/CD pipelines, custom launch scripts).

Bonus: Docker Launch Profile (Optional)

If you're using Docker, Visual Studio may add a profile like this:

"Docker": {
  "commandName": "Docker",
  "launchBrowser": true,
  "launchUrl": "{Scheme}://{ServiceHost}:{ServicePort}/swagger"
}

The {Scheme}, {ServiceHost}, and {ServicePort} are dynamically replaced during container startup.

Summary

You can think of launchSettings.json as your local run configuration manager. It lets you:

Control how your app launches (Kestrel, IIS Express, Docker)
Set URLs, ports, and environments
Auto-launch your browser to specific routes
Inject custom environment variables for development
Keep multiple profiles for different test and debug scenarios

Once you get comfortable with its structure, you’ll find it much easier to control and optimize your development setup.