How to update launchSettings.json files

The launchSettings.json file is managed by the LaunchSettingsJsonTemplate. Template authors can influence its output by publishing events/requests via the IApplicationEventDispatcher. This document describes each available mechanism.

1. Add a Launch Profile - LaunchProfileRegistrationRequest

Adds a new named profile to launchSettings.json.

Namespace: Intent.Modules.Common.CSharp.Configuration

Properties

Property JSON field Description
Name (profile key) The profile name (required).
CommandName commandName e.g. "Project", "IISExpress", "Executable".
CommandLineArgs commandLineArgs Arguments passed to the process.
LaunchBrowser launchBrowser Whether to open a browser on launch.
LaunchUrl launchUrl URL opened in the browser. Supports {HttpPort} and {HttpsPort} tokens.
ApplicationUrl applicationUrl Listening URL(s), semicolon-separated. Supports {HttpPort} and {HttpsPort} tokens.
PublishAllPorts publishAllPorts Defaults to true (omitted from JSON).
UseSsl useSSL Defaults to true (omitted from JSON).
DotnetRunMessages dotnetRunMessages Display build messages on run.
InspectUri inspectUri Debugging URI for Blazor WebAssembly.
ExecutablePath executablePath Path to executable (for Executable command).
WorkingDirectory workingDirectory Working directory for the process.
EnvironmentVariables environmentVariables Key/value pairs added to this profile's environment variables.
ForProjectWithRole (routing) See Targeting a Specific Project.

Notes

  • If a profile with the same Name already exists in the file it is not overwritten (existing file entries take precedence).
  • The {HttpPort} and {HttpsPort} tokens in LaunchUrl and ApplicationUrl are replaced with the actual randomly-assigned or persisted port numbers.

Example

public override void BeforeTemplateExecution()
{
    ExecutionContext.EventDispatcher.Publish(new LaunchProfileRegistrationRequest
    {
        Name = "Docker",
        CommandName = "Docker",
        LaunchBrowser = true,
        LaunchUrl = "https://localhost:{HttpsPort}/swagger",
        ApplicationUrl = "https://localhost:{HttpsPort};http://localhost:{HttpPort}",
        EnvironmentVariables = new Dictionary<string, string>
        {
            ["ASPNETCORE_ENVIRONMENT"] = "Development"
        }
    });
}

2. Add an Environment Variable - EnvironmentVariableRegistrationRequest

Adds a key/value environment variable to one or more launch profiles.

Namespace: Intent.Modules.Common.CSharp.Configuration

Constructor

new EnvironmentVariableRegistrationRequest(
    key: "MY_SETTING",
    value: "my-value",
    targetProfiles: new[] { "MyApp", "IIS Express" }, // null = all profiles
    forProjectWithRole: null)
Parameter Description
key The environment variable name.
value The environment variable value.
targetProfiles Profile names to target. Pass null to apply to every profile.
forProjectWithRole See Targeting a Specific Project.

Notes

  • A variable is only added if the profile doesn't already contain an entry for that key (first-write wins).
  • The default ASPNETCORE_ENVIRONMENT=Development (or DOTNET_ENVIRONMENT=Development for Worker SDK projects) is injected automatically and will be skipped if you have already set it.

Example

ExecutionContext.EventDispatcher.Publish(
    new EnvironmentVariableRegistrationRequest(
        key: "ConnectionStrings__Default",
        value: "Server=localhost;Database=MyDb;",
        targetProfiles: new[] { "MyApp" }));

3. Set the Default Launch URL Path - DefaultLaunchUrlPathRequest

Sets the launchUrl path for the default project profiles (profiles whose name ends with .Api).

Namespace: Intent.Modules.Common.CSharp.Configuration

DefaultLaunchUrlPathRequest has an internal constructor; publish it via the provided extension methods.

Extension methods

Method When to use
template.PublishDefaultLaunchUrlPathRequest(urlPath, forProjectWithRole?) Use inside BeforeTemplateExecution(). Broadcasts globally and logs a warning if unhandled.
outputTarget.EmitDefaultLaunchUrlPathRequest(urlPath) Use when you want the request automatically scoped to projects that reference your output target.

Notes

  • Only one call may succeed per launchSettings.json; a second attempt throws InvalidOperationException.
  • If the file already exists the path is not updated (only applied on first generation).
  • The leading / is stripped automatically.

Example

public override void BeforeTemplateExecution()
{
    this.PublishDefaultLaunchUrlPathRequest("/swagger/index.html");
}

4. Require an HTTP Port in Application URLs - LaunchProfileHttpPortRequired

Publishing this event ensures every HTTPS-only profile gets an additional http://localhost:{port} entry appended to its applicationUrl.

Namespace: Intent.Modules.Constants

Usage

ExecutionContext.EventDispatcher.Publish(LaunchProfileHttpPortRequired.EventId);

This is useful for tooling (e.g. Docker, Aspire) that requires an explicit HTTP endpoint alongside HTTPS.

5. Suppress Generation - AddProjectPropertyEvent with NoDefaultLaunchSettingsFile

Setting the NoDefaultLaunchSettingsFile MSBuild property to true via AddProjectPropertyEvent causes the template to skip generation entirely for that project.

ExecutionContext.EventDispatcher.Publish(new AddProjectPropertyEvent(
    target: outputTarget.GetProject(),
    propertyName: "NoDefaultLaunchSettingsFile",
    propertyValue: "true"));

Targeting a Specific Project

When a solution contains multiple ASP.NET projects, each with its own launchSettings.json, you can route a request to the correct one by setting ForProjectWithRole to the name of a Role element defined under the target project in the Intent Architect Visual Studio designer.

new LaunchProfileRegistrationRequest
{
    ForProjectWithRole = "API",
    Name = "MyProfile",
    // ...
}

If ForProjectWithRole is null or empty, the request is accepted by every launchSettings.json template that processes it.