From 06e0fa42c190d9699a317ae589747497f40bf7ae Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Fri, 29 May 2026 08:26:51 -0400 Subject: [PATCH 1/3] Add note on the .NET CLI default launch profile --- aspnetcore/blazor/debug.md | 2 ++ .../blazor/fundamentals/environments.md | 4 ++++ .../blazor/host-and-deploy/app-base-path.md | 2 ++ .../host-and-deploy/webassembly/index.md | 2 ++ aspnetcore/blazor/project-structure.md | 22 +++++++++++++++---- aspnetcore/blazor/tooling.md | 2 +- .../tutorials/movie-database-app/part-1.md | 2 ++ aspnetcore/fundamentals/environments.md | 6 +++-- .../default-launch-profile-for-dotnet-cli.md | 2 ++ 9 files changed, 37 insertions(+), 7 deletions(-) create mode 100644 aspnetcore/includes/default-launch-profile-for-dotnet-cli.md diff --git a/aspnetcore/blazor/debug.md b/aspnetcore/blazor/debug.md index 95552664e401..19e5fd200fe2 100644 --- a/aspnetcore/blazor/debug.md +++ b/aspnetcore/blazor/debug.md @@ -150,6 +150,8 @@ The `inspectUri` property: The placeholder values for the WebSocket protocol (`wsProtocol`), host (`url.hostname`), port (`url.port`), and inspector URI on the launched browser (`browserInspectUri`) are provided by the framework. +[!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + ## Packages :::moniker range=">= aspnetcore-8.0" diff --git a/aspnetcore/blazor/fundamentals/environments.md b/aspnetcore/blazor/fundamentals/environments.md index 93d199b5947e..fc1d8cbe7f0c 100644 --- a/aspnetcore/blazor/fundamentals/environments.md +++ b/aspnetcore/blazor/fundamentals/environments.md @@ -112,6 +112,8 @@ For a standalone Blazor WebAssembly app running locally, the development server :::moniker-end +[!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + For app's running locally in development, the app defaults to the `Development` environment. Publishing the app defaults the environment to `Production`. :::moniker range="< aspnetcore-5.0" @@ -206,6 +208,8 @@ Although the Blazor framework issues the header name in kebab case with mixed le For local development runs with Blazor's built-in development server, you can control the value of the `Blazor-Environment` header by setting the value of the `ASPNETCORE_ENVIRONMENT` environment variable in the project's `Properties/launchSettings.json` file. When running locally with the development server, the order of precedence for determining the app's environment is [`Blazor.start` configuration (`environment` key)](#set-the-client-side-environment-via-blazor-startup-configuration) > `Blazor-Environment` response header (`blazor.boot.json` file) > `ASPNETCORE_ENVIRONMENT` environment variable (`launchSettings.json`). You can't use the `ASPNETCORE_ENVIRONMENT` environment variable (`launchSettings.json`) approach for a deployed Blazor WebAssembly app. The technique only works with the development server on local runs of the app. +[!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + ### IIS In the following example for IIS, the custom header (`Blazor-Environment`) is added to the published `web.config` file. The `web.config` file is located in the `bin/Release/{TARGET FRAMEWORK}/publish` folder, where the `{TARGET FRAMEWORK}` placeholder is the target framework: diff --git a/aspnetcore/blazor/host-and-deploy/app-base-path.md b/aspnetcore/blazor/host-and-deploy/app-base-path.md index cc668ad86ffa..6ac3187572b2 100644 --- a/aspnetcore/blazor/host-and-deploy/app-base-path.md +++ b/aspnetcore/blazor/host-and-deploy/app-base-path.md @@ -214,6 +214,8 @@ In many hosting scenarios, the relative URL path to the app is the root of the a "ASPNETCORE_ENVIRONMENT": "Development" } ``` + + [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] For more information on the `launchSettings.json` file, see . For additional information on Blazor app base paths and hosting, see [`` or base-tag alternative for Blazor MVC integration (dotnet/aspnetcore #43191)](https://github.com/dotnet/aspnetcore/issues/43191#issuecomment-1212156106). diff --git a/aspnetcore/blazor/host-and-deploy/webassembly/index.md b/aspnetcore/blazor/host-and-deploy/webassembly/index.md index ad2c63ab1176..07fee2c3742f 100644 --- a/aspnetcore/blazor/host-and-deploy/webassembly/index.md +++ b/aspnetcore/blazor/host-and-deploy/webassembly/index.md @@ -397,6 +397,8 @@ The `--contentroot` argument sets the absolute path to the directory that contai "commandLineArgs": "--contentroot=/content-root-path" ``` + [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + * In Visual Studio, specify the argument in **Properties** > **Debug** > **Application arguments**. Setting the argument in the Visual Studio property page adds the argument to the `launchSettings.json` file. ```console diff --git a/aspnetcore/blazor/project-structure.md b/aspnetcore/blazor/project-structure.md index 24e6541987ab..12c2c21f0d8c 100644 --- a/aspnetcore/blazor/project-structure.md +++ b/aspnetcore/blazor/project-structure.md @@ -79,8 +79,7 @@ An `_Imports.razor` file in each of the server and `.Client` projects includes c The `Properties` folder of the server project holds [development environment configuration](xref:fundamentals/environments#development-and-launchsettingsjson) in the `launchSettings.json` file. -> [!NOTE] -> The `http` profile precedes the `https` profile in the `launchSettings.json` file. When an app is run with the .NET CLI, the app runs at an HTTP endpoint because the first profile found is `http`. The profile order eases the transition of adopting HTTPS for Linux and macOS users. If you prefer to start the app with the .NET CLI without having to pass the `-lp https` or `--launch-profile https` option to the `dotnet watch` (or `dotnet run`) command, simply place the `https` profile above the `http` profile in the file. +[!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] The `wwwroot` folder of the server project is the [Web Root](xref:fundamentals/index#web-root) folder for the server project that holds the app's public static assets. @@ -135,6 +134,8 @@ Project structure: * `Properties` folder: Holds [development environment configuration](xref:fundamentals/environments#development-and-launchsettingsjson) in the `launchSettings.json` file. + [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + * `Shared` folder: Contains the following shared components and stylesheets: * `MainLayout` component (`MainLayout.razor`): The app's [layout component](xref:blazor/components/layouts). * `MainLayout.razor.css`: Stylesheet for the app's main layout. @@ -181,6 +182,8 @@ The Blazor Server template creates the initial files and directory structure for * `Properties` folder: Holds [development environment configuration](xref:fundamentals/environments#development-and-launchsettingsjson) in the `launchSettings.json` file. + [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + * `Shared` folder: Contains the following shared components and stylesheets: * `MainLayout` component (`MainLayout.razor`): The app's [layout component](xref:blazor/components/layouts). * `MainLayout.razor.css`: Stylesheet for the app's main layout. @@ -226,6 +229,8 @@ The Blazor Server template creates the initial files and directory structure for * `Properties` folder: Holds [development environment configuration](xref:fundamentals/environments#development-and-launchsettingsjson) in the `launchSettings.json` file. + [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + * `Shared` folder: Contains the following shared components and stylesheets: * `MainLayout` component (`MainLayout.razor`): The app's [layout component](xref:blazor/components/layouts). * `MainLayout.razor.css`: Stylesheet for the app's main layout. @@ -273,6 +278,8 @@ The Blazor Server template creates the initial files and directory structure for * `Properties` folder: Holds [development environment configuration](xref:fundamentals/environments#development-and-launchsettingsjson) in the `launchSettings.json` file. + [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + * `Shared` folder: Contains the following shared components: * `MainLayout` component (`MainLayout.razor`): The app's [layout component](xref:blazor/components/layouts). * `NavMenu` component (`NavMenu.razor`): Implements sidebar navigation. Includes the [`NavLink` component](xref:blazor/fundamentals/navigation#navlink-component) (), which renders navigation links to other Razor components. The component automatically indicates a selected state when its component is loaded, which helps the user understand which component is currently displayed. @@ -349,8 +356,7 @@ Project structure: * `Properties` folder: Holds [development environment configuration](xref:fundamentals/environments#development-and-launchsettingsjson) in the `launchSettings.json` file. - > [!NOTE] - > The `http` profile precedes the `https` profile in the `launchSettings.json` file. When an app is run with the .NET CLI, the app runs at an HTTP endpoint because the first profile found is `http`. The profile order eases the transition of adopting HTTPS for Linux and macOS users. If you prefer to start the app with the .NET CLI without having to pass the `-lp https` or `--launch-profile https` option to the `dotnet watch` (or `dotnet run`) command, simply place the `https` profile above the `http` profile in the file. + [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] * `wwwroot` folder: The [Web Root](xref:fundamentals/index#web-root) folder for the app containing the app's public static assets, including `appsettings.json` and environmental app settings files for [configuration settings](xref:blazor/fundamentals/configuration) and sample weather data (`sample-data/weather.json`). The `index.html` webpage is the root page of the app implemented as an HTML page: * When any page of the app is initially requested, this page is rendered and returned in the response. @@ -387,6 +393,8 @@ Project structure: * `Properties` folder: Holds [development environment configuration](xref:fundamentals/environments#development-and-launchsettingsjson) in the `launchSettings.json` file. + [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + * `Shared` folder: Contains the following shared components and stylesheets: * `MainLayout` component (`MainLayout.razor`): The app's [layout component](xref:blazor/components/layouts). * `MainLayout.razor.css`: Stylesheet for the app's main layout. @@ -443,6 +451,8 @@ The Blazor WebAssembly template creates the initial files and directory structur * `Properties` folder: Holds [development environment configuration](xref:fundamentals/environments#development-and-launchsettingsjson) in the `launchSettings.json` file. + [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + * `Shared` folder: Contains the following shared components and stylesheets: * `MainLayout` component (`MainLayout.razor`): The app's [layout component](xref:blazor/components/layouts). * `MainLayout.razor.css`: Stylesheet for the app's main layout. @@ -495,6 +505,8 @@ The Blazor WebAssembly template creates the initial files and directory structur * `Properties` folder: Holds [development environment configuration](xref:fundamentals/environments#development-and-launchsettingsjson) in the `launchSettings.json` file. + [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + * `Shared` folder: Contains the following shared components and stylesheets: * `MainLayout` component (`MainLayout.razor`): The app's [layout component](xref:blazor/components/layouts). * `MainLayout.razor.css`: Stylesheet for the app's main layout. @@ -547,6 +559,8 @@ The Blazor WebAssembly template creates the initial files and directory structur * `Properties` folder: Holds [development environment configuration](xref:fundamentals/environments#development-and-launchsettingsjson) in the `launchSettings.json` file. + [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + * `Shared` folder: Contains the following shared components: * `MainLayout` component (`MainLayout.razor`): The app's [layout component](xref:blazor/components/layouts). * `NavMenu` component (`NavMenu.razor`): Implements sidebar navigation. Includes the [`NavLink` component](xref:blazor/fundamentals/navigation#navlink-component) (), which renders navigation links to other Razor components. The component automatically indicates a selected state when its component is loaded, which helps the user understand which component is currently displayed. diff --git a/aspnetcore/blazor/tooling.md b/aspnetcore/blazor/tooling.md index fcab24497cce..539c603bdada 100644 --- a/aspnetcore/blazor/tooling.md +++ b/aspnetcore/blazor/tooling.md @@ -426,7 +426,7 @@ dotnet watch The default browser is launched at `https://localhost:{PORT}`, which displays the app's UI. The `{PORT}` placeholder is the random port assigned at app creation. If you need to change the port due to a local port conflict, change the port in the project's `Properties/launchSettings.json` file. -When an app created from the Blazor Web App project template is run with the .NET CLI, the app runs at an HTTP (insecure) endpoint because the first profile found in the app's launch settings file (`Properties/launchSettings.json`) is the HTTP (insecure) profile, which is named `http`. The HTTP profile was placed in the first position to ease the transition of adopting SSL/HTTPS security for non-Windows users. +[!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] One approach for running the app with SSL/HTTPS is to pass the [`-lp`|`--launch-profile` option](/dotnet/core/tools/dotnet-run#options) with the `https` profile name to the `dotnet watch` command: diff --git a/aspnetcore/blazor/tutorials/movie-database-app/part-1.md b/aspnetcore/blazor/tutorials/movie-database-app/part-1.md index a64bf46d1e97..2b44ef40c851 100644 --- a/aspnetcore/blazor/tutorials/movie-database-app/part-1.md +++ b/aspnetcore/blazor/tutorials/movie-database-app/part-1.md @@ -163,6 +163,8 @@ The app is compiled and run. The app is launched at `http://localhost:{PORT}`, w Navigate the pages of the app to confirm that the app is working normally. +[!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + :::zone-end ## Stop the app diff --git a/aspnetcore/fundamentals/environments.md b/aspnetcore/fundamentals/environments.md index e7bada5a2d8c..a51269e8ccab 100644 --- a/aspnetcore/fundamentals/environments.md +++ b/aspnetcore/fundamentals/environments.md @@ -5,7 +5,7 @@ description: Learn how to set and control app behavior across runtime environmen monikerRange: '>= aspnetcore-3.1' ms.author: tdykstra ms.custom: mvc -ms.date: 09/19/2025 +ms.date: 05/29/2026 uid: fundamentals/environments --- # ASP.NET Core runtime environments @@ -203,12 +203,14 @@ Profiles can be selected in the Visual Studio UI next to the Start button (►). When a solution contains multiple projects, only set the environment for the startup project. -Alternatively, use the [`dotnet run`](/dotnet/core/tools/dotnet-run) command with the [`-lp|--launch-profile` option](/dotnet/core/tools/dotnet-run#options) set to the profile's name. *This approach only supports launch profiles based on the `Project` command.* +Alternatively, use the [`dotnet watch`](/dotnet/core/tools/dotnet-watch) or [`dotnet run`](/dotnet/core/tools/dotnet-run) command with the [`-lp|--launch-profile` option](/dotnet/core/tools/dotnet-run#options) set to the profile's name. *This approach only supports launch profiles based on the `Project` command.* ```dotnetcli dotnet run -lp "https" ``` +[!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] + When using [Visual Studio Code](https://code.visualstudio.com/) with the [C# Dev Kit for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) ([Getting Started with C# in VS Code](https://code.visualstudio.com/docs/csharp/get-started)), launch profiles are picked up from the app's `launchSettings.json` file. If the C# Dev Kit isn't used, set the `ASPNETCORE_ENVIRONMENT` environment variable in the `.vscode/launch.json` in the `env` section, along with any other environment variables set in the section: diff --git a/aspnetcore/includes/default-launch-profile-for-dotnet-cli.md b/aspnetcore/includes/default-launch-profile-for-dotnet-cli.md new file mode 100644 index 000000000000..7268b02fd1f6 --- /dev/null +++ b/aspnetcore/includes/default-launch-profile-for-dotnet-cli.md @@ -0,0 +1,2 @@ +> [!NOTE] +> In ASP.NET Core project templates, the `http` profile precedes the `https` profile in the `launchSettings.json` file. When an app is run with the .NET CLI, the app runs at an HTTP endpoint because the first profile found is `http`. The profile order eases the transition of adopting HTTPS for Linux and macOS users. If you prefer to start the app with the .NET CLI without having to pass the [`-lp https`/`--launch-profile https` option](/dotnet/core/tools/dotnet-run#options) to the [`dotnet watch`](/dotnet/core/tools/dotnet-watch) or [`dotnet run`](/dotnet/core/tools/dotnet-run) command, make the `https` profile the first profile in the file. From 6df40068064f1a70b1680c47dfe9573a1e8b2b63 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Fri, 29 May 2026 08:46:47 -0400 Subject: [PATCH 2/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- aspnetcore/includes/default-launch-profile-for-dotnet-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/includes/default-launch-profile-for-dotnet-cli.md b/aspnetcore/includes/default-launch-profile-for-dotnet-cli.md index 7268b02fd1f6..87ef0904cdea 100644 --- a/aspnetcore/includes/default-launch-profile-for-dotnet-cli.md +++ b/aspnetcore/includes/default-launch-profile-for-dotnet-cli.md @@ -1,2 +1,2 @@ > [!NOTE] -> In ASP.NET Core project templates, the `http` profile precedes the `https` profile in the `launchSettings.json` file. When an app is run with the .NET CLI, the app runs at an HTTP endpoint because the first profile found is `http`. The profile order eases the transition of adopting HTTPS for Linux and macOS users. If you prefer to start the app with the .NET CLI without having to pass the [`-lp https`/`--launch-profile https` option](/dotnet/core/tools/dotnet-run#options) to the [`dotnet watch`](/dotnet/core/tools/dotnet-watch) or [`dotnet run`](/dotnet/core/tools/dotnet-run) command, make the `https` profile the first profile in the file. +> When an app is run with the .NET CLI, the first launch profile in `launchSettings.json` whose `commandName` is `Project` is used by default. To use a different profile (for example, `https`), pass the [`-lp|--launch-profile` option](/dotnet/core/tools/dotnet-run#options) to [`dotnet watch`](/dotnet/core/tools/dotnet-watch) or [`dotnet run`](/dotnet/core/tools/dotnet-run), or move the preferred profile to the top of the file. From abb675b730f5c611f66887d8e9c4da800e4923d9 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Fri, 29 May 2026 08:48:13 -0400 Subject: [PATCH 3/3] Updates --- aspnetcore/includes/default-launch-profile-for-dotnet-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/includes/default-launch-profile-for-dotnet-cli.md b/aspnetcore/includes/default-launch-profile-for-dotnet-cli.md index 87ef0904cdea..bdd87bbaf626 100644 --- a/aspnetcore/includes/default-launch-profile-for-dotnet-cli.md +++ b/aspnetcore/includes/default-launch-profile-for-dotnet-cli.md @@ -1,2 +1,2 @@ > [!NOTE] -> When an app is run with the .NET CLI, the first launch profile in `launchSettings.json` whose `commandName` is `Project` is used by default. To use a different profile (for example, `https`), pass the [`-lp|--launch-profile` option](/dotnet/core/tools/dotnet-run#options) to [`dotnet watch`](/dotnet/core/tools/dotnet-watch) or [`dotnet run`](/dotnet/core/tools/dotnet-run), or move the preferred profile to the top of the file. +> When an app is run with the .NET CLI, the first launch profile in `launchSettings.json` whose `commandName` is `Project` is used by default. To use a different profile (for example, `https`), pass the [`-lp|--launch-profile` option](/dotnet/core/tools/dotnet-run#options) to [`dotnet watch`](/dotnet/core/tools/dotnet-watch) or [`dotnet run`](/dotnet/core/tools/dotnet-run) or move the preferred profile to the top of the file.