Understanding launchSettings.json in .NET

by Tom Vaidyanin .NET, C#, Docker, Microsoft, Web Development, Windowson Posted on

launchSettings.json is a developer-time file that controls how your .NET project launches locally. Visual Studio / IIS Express and the dotnet run CLI read it to set environment variables, URLs, and browser launch behavior. It is not included in published output, and your app does not read it at runtime—production hosts (Azure App Service, containers, services, schedulers) ignore it.

TL;DR (Quick Reference)

  • Who reads it? Visual Studio, IIS Express, dotnet run when a profile is selected.
  • Who doesn’t? The compiled exe/dll, Windows Service, Task Scheduler, Azure App Service/WebJobs, Docker/Kubernetes, CI runners.
  • What’s inside? Launch profiles with commandName, applicationUrl, environmentVariables, and IIS Express settings.
  • Where? Properties/launchSettings.json in the project you actually start.
  • How to use? Select the profile in Visual Studio or run dotnet run --launch-profile "ProfileName".
  • Production? Ignore it. Configure app settings/environment variables in the real host (Azure, Docker env, Kubernetes env/Secrets, etc.).

File Location & Structure

Place the file under Properties/launchSettings.json. It usually contains an iisSettings section (for IIS Express) and a profiles section with one or more launch profiles.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:12345",
      "sslPort": 44321
    }
  },
  "profiles": {
    "MyApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "dotnetRunMessages": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "MyCustomSetting": "abc123"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "External Tool": {
      "commandName": "Executable",
      "executablePath": "C:\\tools\\someexe.exe",
      "commandLineArgs": "--flag"
    }
  }
}

Key Profile Properties

  • commandName: How the profile starts. Common: Project (run this project), IISExpress (Windows only), Executable (run another exe).
  • environmentVariables: Name/value pairs injected into the process environment by the tooling at launch.
  • applicationUrl: One or more (semicolon-separated) URLs to bind locally.
  • launchBrowser: Open a browser when launching.
  • dotnetRunMessages: Show “Now listening on …” messages.
  • executablePath, commandLineArgs: For Executable profiles—run a specific tool with args.

How It’s Applied (Dev-Time Only)

  • Visual Studio / IIS Express / dotnet run parse launchSettings.json, set env vars/URLs, then start your process.
  • Your app never opens this file; it simply sees the environment variables the tooling set.
  • If you run the compiled .exe or dotnet <app>.dll directly, the file is ignored.

Using It with dotnet run

If multiple profiles exist, select one explicitly:

dotnet run --launch-profile "MyApp"

Without --launch-profile, the CLI picks a default (often the first project profile). In Visual Studio, choose the profile from the debug dropdown.

Reading Values Inside Your App

If you use the generic host (Host.CreateDefaultBuilder), environment variables are already part of configuration. You can read them via IConfiguration or directly via Environment. If you build configuration manually, ensure you call .AddEnvironmentVariables().

var config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: true)
    .AddEnvironmentVariables() // include env vars if not using default host
    .Build();

var value = config["MyCustomSetting"];
var raw   = Environment.GetEnvironmentVariable("MyCustomSetting");

Workers & WebJobs (Console Projects)

For console-style projects (Worker Service, classic WebJobs), use a profile with commandName: "Project". Start from Visual Studio with that profile or run dotnet run --launch-profile "ProfileName". Running the built .exe/.dll directly won’t pick up launchSettings.json.

Why It Doesn’t Apply in Azure (App Service / WebJobs)

Azure App Service and the WebJobs host run your compiled assembly directly (e.g., dotnet MyApp.dll for framework-dependent deployments). They do not invoke dotnet run and do not parse launchSettings.json. To configure settings in Azure:

  • App Service → Configuration → Application settings: Add key/value pairs (these become environment variables).
  • Use your IaC (Bicep/ARM/Terraform) or Azure CLI to provision settings for repeatability.
  • For WebJobs in App Service, the same Application settings apply to the job process.

Common Pitfalls (and Fixes)

  • Problem: “My env var isn’t set.”
    Fix: You’re likely running the built binary directly. Launch from Visual Studio or use dotnet run --launch-profile. Also verify commandName is correct.
  • Problem: “Works in Dev, fails in Azure.”
    Fix: Move settings to real environment variables in Azure (App Service → Configuration) or appsettings files deployed with the app.
  • Problem: VS Code ignores it.
    Fix: VS Code doesn’t honor launchSettings.json by default. Put env vars in .vscode/launch.json (env block) or run tasks that call dotnet run --launch-profile.
  • Problem: Rider profile mismatch.
    Fix: Ensure Rider imported the launch settings or manually configure a run configuration with the same env vars.

VS Code / Rider Notes

VS Code: Add environment variables to .vscode/launch.json (C# debugger) or use a task that runs dotnet run --launch-profile "MyApp". EnlighterJS code blocks on your site don’t affect local debugging.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Launch (MyApp)",
      "type": "coreclr",
      "request": "launch",
      "program": "${workspaceFolder}/bin/Debug/net8.0/MyApp.dll",
      "cwd": "${workspaceFolder}",
      "env": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "MyCustomSetting": "abc123"
      }
    }
  ]
}

JetBrains Rider: Use “Import from Visual Studio” or create a .NET Project run configuration and add the same environment variables.

Best Practices

  • Dev-only convenience: Treat launchSettings.json as local run configuration, not application configuration.
  • No secrets: Don’t put credentials here. Use Secret Manager (dotnet user-secrets) for local secrets and the host’s secret store in prod.
  • Profiles for scenarios: Create multiple profiles (e.g., API only, UI + API, mock backends) with different URLs/env vars.
  • Commit or ignore? Many teams commit it (shared conventions). If machine-specific values cause churn, add it to .gitignore and use docs to standardize.
  • Be explicit in code: If you depend on env vars, fail fast with clear error messages when required values are missing.

FAQ

Does ASPNETCORE_ENVIRONMENT come from launchSettings.json?

Only when launched by tooling that reads the file (VS, IIS Express, dotnet run). In production you must set it via the host environment.

Can I pass command-line args from a profile?

Yes—add commandLineArgs to a Project profile, or use an Executable profile for external tools.

Why is my profile not used?

Ensure the correct startup project/profile is selected in Visual Studio, or pass --launch-profile on the CLI. Check that your launchSettings.json lives under the running project’s Properties folder.

Troubleshooting Checklist

  • ✅ File path is Properties/launchSettings.json in the startup project.
  • ✅ commandName is correct (Project for typical apps/workers).
  • ✅ You’re launching via Visual Studio, IIS Express, or dotnet run (not the compiled binary directly).
  • ✅ For custom host builders, you’ve included .AddEnvironmentVariables() (or are using Host.CreateDefaultBuilder which already does).
  • ✅ For Azure, you’ve copied needed values into App Service → Configuration (or IaC).

Conclusion

launchSettings.json is a developer launch profile manager, not a runtime configuration file. It streamlines local debugging by setting environment variables and binding URLs, but production environments must be configured independently. Use it to improve developer experience; rely on appsettings, environment variables, and your deployment platform for the real thing.

Leave a Comment

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