C# launch profiles

Aspire makes use of launch profiles defined in both the AppHost and service projects to simplify configuring multiple aspects of the debugging and publishing experience for Aspire-based distributed applications.

Note

This article applies to C# AppHosts and .NET service projects that use launchSettings.json. TypeScript AppHosts define profiles in aspire.config.json instead. For more information, see AppHost configuration and TypeScript AppHost project structure.

Launch profile basics

When you create a new .NET application from a template, you often see a Properties directory containing a file named launchSettings.json. The launch settings file contains a list of launch profiles. Each launch profile is a collection of related options that defines how dotnet should start your application.

The following JSON is an example of launch profiles in a launchSettings.json file for an ASP.NET Core application:

JSON — launchSettings.json

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5130",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "https://localhost:7106;http://localhost:5130",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

The preceding launchSettings.json file defines two launch profiles, http and https. Each has its own set of environment variables, launch URLs, and other options. When launching a .NET application, you can choose which launch profile to use:

Terminal

dotnet run --launch-profile https

If no launch profile is specified, the first launch profile is selected by default. You can also launch a .NET application without a launch profile using the --no-launch-profile option. Some fields from the launchSettings.json file are translated to environment variables. For example, the applicationUrl field is converted to the ASPNETCORE_URLS environment variable, which controls which address and port ASP.NET Core binds to.

When a .NET application is launched with a launch profile, the DOTNET_LAUNCH_PROFILE environment variable is set to the name of the launch profile that was used.

Launch profiles for C# AppHosts

In Aspire, the C# AppHost is a .NET application, so it has a launchSettings.json file just like any other .NET project. The following JSON is an example of the launchSettings.json file generated when creating a new Aspire project from the starter template (dotnet new aspire-starter):

JSON — launchSettings.json

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:17134;http://localhost:15170",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development",
        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21030",
        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22057"
      }
    },
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:15170",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development",
        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19240",
        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20154"
      }
    }
  }
}

The Aspire templates define a similar set of launch profiles to a regular ASP.NET Core application. When the C# AppHost project launches, it starts a DistributedApplication and hosts a web server used by the Aspire Dashboard to fetch information about the resources being orchestrated by Aspire.

AppHost launch profiles and .NET service projects

The C# AppHost is responsible for coordinating the launch of multiple service projects. When you run the AppHost — from the command line, Visual Studio, or another development environment — a launch profile is selected for the AppHost. In turn, the AppHost attempts to find a matching launch profile in the service projects it launches, and uses those options to control the environment and default networking configuration for the service project.

When the AppHost launches a service project, it doesn’t use the --launch-profile option directly. Instead, Aspire resolves an effective launch profile, sets DOTNET_LAUNCH_PROFILE for consistency with dotnet run and dotnet watch, and adjusts the ASPNETCORE_URLS environment variable (derived from the applicationUrl field in the launch profile) to use a different port. By default, Aspire inserts a reverse proxy in front of the ASP.NET Core application to support multiple instances via WithReplicas.

Other settings, such as environmentVariables, are passed to the application without modification.

Control launch profile selection

Ideally, you can align the launch profile names between the AppHost and its service projects so that switching profiles in the AppHost switches them across all coordinated projects at once. However, you can also specify which profile a particular project uses by passing launchProfileName to AddProject:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.InventoryService>(
    "inventoryservice",
    launchProfileName: "mylaunchprofile");

builder.Build().Run();

The preceding code launches the inventoryservice resource using the options from the mylaunchprofile launch profile. The launch profile precedence logic is as follows:

1. Use the launch profile specified by the launchProfileName argument if specified.
2. Use the launch profile with the same name as the AppHost (determined by reading the DOTNET_LAUNCH_PROFILE environment variable).
3. Use the default (first) launch profile in launchSettings.json.
4. Don’t use a launch profile.

To force a service project to launch without a launch profile, set the launchProfileName argument to null.

Launch profiles and endpoints for ASP.NET Core projects

When adding an ASP.NET Core project to the AppHost, Aspire parses the launchSettings.json file, selects the appropriate launch profile, and automatically generates endpoints in the application model based on the URLs in the applicationUrl field. To modify the automatically injected endpoints, use WithEndpoint:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.InventoryService>("inventoryservice")
    .WithEndpoint("https", endpoint => endpoint.IsProxied = false);

builder.Build().Run();

The preceding code disables the reverse proxy that Aspire deploys in front of the .NET application and allows the application to respond directly to requests over HTTP(S).

See also

• Project resources
• AppHost configuration
• TypeScript AppHost project structure
• Inner-loop networking
• .NET environments documentation