Dynamic Profile Generators

Relevant source files

This page covers the subsystem that automatically discovers and creates terminal profiles at startup, without user configuration. It describes the generator interface, the built-in generator implementations (including WslDistroGenerator, PowershellCoreProfileGenerator, AzureCloudShellGenerator, VsDevCmdGenerator, VsDevShellGenerator, VisualStudioGenerator wrapper, SshHostGenerator), and the settings editor search index.

For context on how generated profiles are loaded and merged with user settings, see the Settings Model and Loading page (5.1). For the settings editor UI that consumes the search index, see the Settings Editor UI page (5.2).

Overview

When Windows Terminal starts, SettingsLoader (see 5.1) invokes a set of dynamic profile generators. Each generator inspects the local environment (such as the registry, the filesystem, or platform APIs) and emits zero or more Profile objects. These generated profiles are then merged with the user's settings.json.

The primary built-in dynamic profile generators in the Windows Terminal codebase are:

Generator Class	Namespace Constant	What It Discovers
`WslDistroGenerator`	`WslGeneratorNamespace`	Installed WSL distributions via the Windows registry
`PowershellCoreProfileGenerator`	`PowershellCoreGeneratorNamespace`	PowerShell Core installations: Store, Scoop, dotnet, and traditional
`AzureCloudShellGenerator`	`AzureGeneratorNamespace`	The Azure Cloud Shell connection type
`VsDevCmdGenerator`	`VisualStudioGeneratorNamespace`	Visual Studio Developer Command Prompt instances
`VsDevShellGenerator`	`VisualStudioGeneratorNamespace`	Visual Studio Developer PowerShell instances
`VisualStudioGenerator`	Wrapper around VsDevCmd and VsDevShell generators	Aggregates Visual Studio profiles
`SshHostGenerator`	`SshGeneratorNamespace`	SSH hosts defined in the user's `~/.ssh/config`

These generators work independently and the SettingsLoader merges their outputs into the global profile list.

Sources: src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp14-18 src/cascadia/TerminalSettingsModel/Microsoft.Terminal.Settings.ModelLib.vcxproj93-115

Generator Interface

All dynamic profile generators implement the IDynamicProfileGenerator interface specified in IDynamicProfileGenerator.h. This interface declares the following virtual functions:

Method	Return Type	Description
`GetNamespace()`	`std::wstring_view`	Returns a stable namespace string used for GUID generation
`GetDisplayName()`	`std::wstring_view`	Localized display name for the generator (shown in UI)
`GetIcon()`	`std::wstring_view`	URI for the icon representing the generator
`GenerateProfiles()`	`void`	Populates a vector with generated `Profile` objects

Each generator creates Profile objects using the helper CreateDynamicProfile defined in DynamicProfileUtils.h which accepts a profile name and outputs a Profile object with a deterministically generated stable GUID. These GUIDs are based on a combination of the generator's namespace and the profile's name, ensuring consistency across runs src/cascadia/TerminalSettingsModel/IDynamicProfileGenerator.h1 src/cascadia/TerminalSettingsModel/DynamicProfileUtils.cpp16-25

Class Hierarchy

Sources: src/cascadia/TerminalSettingsModel/IDynamicProfileGenerator.h1 src/cascadia/TerminalSettingsModel/WslDistroGenerator.h1 src/cascadia/TerminalSettingsModel/PowershellCoreProfileGenerator.h1 src/cascadia/TerminalSettingsModel/AzureCloudShellGenerator.cpp18-31 src/cascadia/TerminalSettingsModel/VsDevCmdGenerator.cpp1-69

WslDistroGenerator

The WslDistroGenerator generates profiles by enumerating installed WSL distributions. It reads Windows registry keys under the path:

HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss
  └─ {distroGuid}
       └─ DistributionName (REG_SZ): WSL distro name
       └─ Modern (DWORD): If 1, skip this entry (newer format not supported)

This registry path is defined by RegKeyLxss and the values by RegKeyDistroName and RegKeyModern in the source src/cascadia/TerminalSettingsModel/WslDistroGenerator.cpp22-24

Detection Flow

The generator opens the registry key HKCU\Lxss, enumerates all subkeys (each a GUID for a distribution), and reads the DistributionName values. It skips distributions with names that start with certain prefixes (docker-desktop, rancher-desktop) to exclude utility distros created by Docker and Rancher tools.

For each valid distro name, it generates a profile with:

Commandline set to C:\Windows\System32\wsl.exe -d <distroName>.
StartingDirectory typically set to the Linux home directory ~ if the Windows build supports the --cd option for Linux paths (Windows 10 build 19041 or later); otherwise a default starting path.
An icon URI pointing to a WSL icon resource.
The path translation style set to WSL.

Sources: src/cascadia/TerminalSettingsModel/WslDistroGenerator.cpp22-24 src/cascadia/TerminalSettingsModel/WslDistroGenerator.cpp62-83 src/cascadia/TerminalSettingsModel/WslDistroGenerator.cpp92-105 src/cascadia/TerminalSettingsModel/WslDistroGenerator.cpp241-257

PowershellCoreProfileGenerator

This generator discovers PowerShell Core installations on the system. It supports multiple discovery paths, accounting for different installation methods:

Source Method	Flags Used	Typical Install Location or Pattern
`_accumulateStorePowerShellInstances()`	`Store` or `Store	Preview`
`_accumulatePwshExeInDirectory()`	`Dotnet` or `Scoop`	`%USERPROFILE%\.dotnet\tools\pwsh.exe`, `%USERPROFILE%\scoop\shims\pwsh.exe`
`_accumulateTraditionalLayoutPowerShellInstancesInDirectory()`	`Traditional`	`%ProgramFiles%\PowerShell\<version>\pwsh.exe`

Each discovered instance is recorded as a PowerShellInstance struct that contains:

The path to the pwsh executable
Major version
Flags indicating installation scope/type
Architecture info

All instances are sorted by a custom less-than operator that prioritizes by:

Descending major version (higher is preferred)
Ascending flags (0 is best, higher values are less preferred)
Alphabetical path sort fallback

This ensures that the best and most standard PowerShell Core version is preferred first.

Profiles are generated for each discovered instance with appropriate commandline, icon, and starting directory.

Sources: src/cascadia/TerminalSettingsModel/PowershellCoreProfileGenerator.cpp29-65 src/cascadia/TerminalSettingsModel/PowershellCoreProfileGenerator.cpp67-136

Visual Studio Generators

Visual Studio profiles are generated through a layered approach utilizing the VisualStudioGenerator wrapper, which in turn produces instances of VsDevCmdGenerator and VsDevShellGenerator.

These generators query Visual Studio installations using the VsSetupConfiguration API:

VsSetupConfiguration uses COM interfaces to enumerate installed VS instances.
For each Visual Studio instance, the generators check validity.
VsDevCmdGenerator creates profiles for the "Developer Command Prompt" by invoking cmd.exe /k "VsDevCmd.bat" with appropriate -arch and -host_arch flags depending on platform (x64 vs ARM64).
VsDevShellGenerator creates profiles for the "Developer PowerShell". It detects if pwsh.exe is available, else falls back to powershell.exe. It imports the Microsoft.VisualStudio.DevShell.dll and calls Enter-VsDevShell with the instance ID.

Visual Studio Profile Discovery Flow

Sources: src/cascadia/TerminalSettingsModel/VisualStudioGenerator.cpp32-60 src/cascadia/TerminalSettingsModel/VsDevCmdGenerator.cpp10-28 src/cascadia/TerminalSettingsModel/VsDevCmdGenerator.cpp43-61 src/cascadia/TerminalSettingsModel/VsDevShellGenerator.cpp21-42

AzureCloudShellGenerator

The AzureCloudShellGenerator generates a singular profile that connects to the Azure Cloud Shell. This is a specialized profile using a remote connection type to Azure's interactive shell service.

It overrides the GenerateProfiles() method to produce this specific profile with associated settings for Azure integration, such as connection commandline, icon, and display name localized through resources.

Sources: src/cascadia/TerminalSettingsModel/AzureCloudShellGenerator.cpp18-31

SshHostGenerator

The SshHostGenerator reads the user's SSH configuration file, commonly located at ~/.ssh/config, to discover configured SSH hosts and generate corresponding SSH terminal profiles.

Key points:

It generates profiles with commandlines invoking ssh.exe <host>.
Uses a stable namespace SshGeneratorNamespace to generate deterministic profile GUIDs.
Generates SSH profiles only once per settings load to avoid duplicate entries; tracked through sshProfilesGenerated in SettingsLoader.
Integrates with the settings editor and main settings model for UI presentation.

Sources: src/cascadia/TerminalSettingsModel/SshHostGenerator.cpp1 src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp18 src/cascadia/TerminalSettingsModel/CascadiaSettings.h104

Settings Editor Search Index

The Windows Terminal settings editor provides a fuzzy-search UI for settings and profiles. The search index is constructed using models defined in the Microsoft.Terminal.Settings.Model library, which includes:

MatchProfilesEntry
ProfileEntry
Other entries representing individual profile and global settings

These entries populate the navigation and search features of the settings editor, enabling quick filtering and access to specific settings related to profiles or global configuration.

The index implementation lives alongside the dynamic profile generators in the settings model code and is integrated into the overall settings editor UI (see page 5.2).

Sources: src/cascadia/TerminalSettingsModel/CascadiaSettings.cpp1 src/cascadia/TerminalSettingsModel/Microsoft.Terminal.Settings.ModelLib.vcxproj46-48

Summary Diagram: Natural Language Concepts to Code Entities

Sources: src/cascadia/TerminalSettingsModel/WslDistroGenerator.cpp20-257 src/cascadia/TerminalSettingsModel/PowershellCoreProfileGenerator.cpp20-136 src/cascadia/TerminalSettingsModel/VsDevCmdGenerator.cpp1-68 src/cascadia/TerminalSettingsModel/VsDevShellGenerator.cpp11-42 src/cascadia/TerminalSettingsModel/SshHostGenerator.cpp1 src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp14-18

Detailed Data Flow of Profile Generation and Consumption

Sources: Aggregated from all generator implementations and settings model loading code.

References

src/cascadia/TerminalSettingsModel/WslDistroGenerator.cpp (lines 20-260)
src/cascadia/TerminalSettingsModel/PowershellCoreProfileGenerator.cpp (lines 25-136)
src/cascadia/TerminalSettingsModel/VsDevCmdGenerator.cpp (lines 1-69)
src/cascadia/TerminalSettingsModel/VsDevShellGenerator.cpp (lines 11-42)
src/cascadia/TerminalSettingsModel/VisualStudioGenerator.cpp
src/cascadia/TerminalSettingsModel/AzureCloudShellGenerator.cpp
src/cascadia/TerminalSettingsModel/SshHostGenerator.cpp
src/cascadia/TerminalSettingsModel/IDynamicProfileGenerator.h
src/cascadia/TerminalSettingsModel/DynamicProfileUtils.h
src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp
src/cascadia/TerminalSettingsModel/Microsoft.Terminal.Settings.ModelLib.vcxproj
src/cascadia/TerminalSettingsModel/CascadiaSettings.h
src/cascadia/TerminalSettingsEditor/SearchIndex.cpp

Dynamic Profile Generators

Relevant source files

Overview

The primary built-in dynamic profile generators in the Windows Terminal codebase are:

Generator Class	Namespace Constant	What It Discovers
`WslDistroGenerator`	`WslGeneratorNamespace`	Installed WSL distributions via the Windows registry
`PowershellCoreProfileGenerator`	`PowershellCoreGeneratorNamespace`	PowerShell Core installations: Store, Scoop, dotnet, and traditional
`AzureCloudShellGenerator`	`AzureGeneratorNamespace`	The Azure Cloud Shell connection type
`VsDevCmdGenerator`	`VisualStudioGeneratorNamespace`	Visual Studio Developer Command Prompt instances
`VsDevShellGenerator`	`VisualStudioGeneratorNamespace`	Visual Studio Developer PowerShell instances
`VisualStudioGenerator`	Wrapper around VsDevCmd and VsDevShell generators	Aggregates Visual Studio profiles
`SshHostGenerator`	`SshGeneratorNamespace`	SSH hosts defined in the user's `~/.ssh/config`

These generators work independently and the SettingsLoader merges their outputs into the global profile list.

Sources: src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp14-18 src/cascadia/TerminalSettingsModel/Microsoft.Terminal.Settings.ModelLib.vcxproj93-115

Generator Interface

All dynamic profile generators implement the IDynamicProfileGenerator interface specified in IDynamicProfileGenerator.h. This interface declares the following virtual functions:

Method	Return Type	Description
`GetNamespace()`	`std::wstring_view`	Returns a stable namespace string used for GUID generation
`GetDisplayName()`	`std::wstring_view`	Localized display name for the generator (shown in UI)
`GetIcon()`	`std::wstring_view`	URI for the icon representing the generator
`GenerateProfiles()`	`void`	Populates a vector with generated `Profile` objects

Class Hierarchy

WslDistroGenerator

The WslDistroGenerator generates profiles by enumerating installed WSL distributions. It reads Windows registry keys under the path:

HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss
  └─ {distroGuid}
       └─ DistributionName (REG_SZ): WSL distro name
       └─ Modern (DWORD): If 1, skip this entry (newer format not supported)

This registry path is defined by RegKeyLxss and the values by RegKeyDistroName and RegKeyModern in the source src/cascadia/TerminalSettingsModel/WslDistroGenerator.cpp22-24

Detection Flow

For each valid distro name, it generates a profile with:

Commandline set to C:\Windows\System32\wsl.exe -d <distroName>.
StartingDirectory typically set to the Linux home directory ~ if the Windows build supports the --cd option for Linux paths (Windows 10 build 19041 or later); otherwise a default starting path.
An icon URI pointing to a WSL icon resource.
The path translation style set to WSL.

PowershellCoreProfileGenerator

This generator discovers PowerShell Core installations on the system. It supports multiple discovery paths, accounting for different installation methods:

Source Method	Flags Used	Typical Install Location or Pattern
`_accumulateStorePowerShellInstances()`	`Store` or `Store	Preview`
`_accumulatePwshExeInDirectory()`	`Dotnet` or `Scoop`	`%USERPROFILE%\.dotnet\tools\pwsh.exe`, `%USERPROFILE%\scoop\shims\pwsh.exe`
`_accumulateTraditionalLayoutPowerShellInstancesInDirectory()`	`Traditional`	`%ProgramFiles%\PowerShell\<version>\pwsh.exe`

Each discovered instance is recorded as a PowerShellInstance struct that contains:

The path to the pwsh executable
Major version
Flags indicating installation scope/type
Architecture info

All instances are sorted by a custom less-than operator that prioritizes by:

Descending major version (higher is preferred)
Ascending flags (0 is best, higher values are less preferred)
Alphabetical path sort fallback

This ensures that the best and most standard PowerShell Core version is preferred first.

Profiles are generated for each discovered instance with appropriate commandline, icon, and starting directory.

Sources: src/cascadia/TerminalSettingsModel/PowershellCoreProfileGenerator.cpp29-65 src/cascadia/TerminalSettingsModel/PowershellCoreProfileGenerator.cpp67-136

Visual Studio Generators

Visual Studio profiles are generated through a layered approach utilizing the VisualStudioGenerator wrapper, which in turn produces instances of VsDevCmdGenerator and VsDevShellGenerator.

These generators query Visual Studio installations using the VsSetupConfiguration API:

VsSetupConfiguration uses COM interfaces to enumerate installed VS instances.
For each Visual Studio instance, the generators check validity.
VsDevCmdGenerator creates profiles for the "Developer Command Prompt" by invoking cmd.exe /k "VsDevCmd.bat" with appropriate -arch and -host_arch flags depending on platform (x64 vs ARM64).
VsDevShellGenerator creates profiles for the "Developer PowerShell". It detects if pwsh.exe is available, else falls back to powershell.exe. It imports the Microsoft.VisualStudio.DevShell.dll and calls Enter-VsDevShell with the instance ID.

Visual Studio Profile Discovery Flow

AzureCloudShellGenerator

The AzureCloudShellGenerator generates a singular profile that connects to the Azure Cloud Shell. This is a specialized profile using a remote connection type to Azure's interactive shell service.

Sources: src/cascadia/TerminalSettingsModel/AzureCloudShellGenerator.cpp18-31

SshHostGenerator

The SshHostGenerator reads the user's SSH configuration file, commonly located at ~/.ssh/config, to discover configured SSH hosts and generate corresponding SSH terminal profiles.

Key points:

It generates profiles with commandlines invoking ssh.exe <host>.
Uses a stable namespace SshGeneratorNamespace to generate deterministic profile GUIDs.
Generates SSH profiles only once per settings load to avoid duplicate entries; tracked through sshProfilesGenerated in SettingsLoader.
Integrates with the settings editor and main settings model for UI presentation.

Sources: src/cascadia/TerminalSettingsModel/SshHostGenerator.cpp1 src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp18 src/cascadia/TerminalSettingsModel/CascadiaSettings.h104

Settings Editor Search Index

MatchProfilesEntry
ProfileEntry
Other entries representing individual profile and global settings

These entries populate the navigation and search features of the settings editor, enabling quick filtering and access to specific settings related to profiles or global configuration.

The index implementation lives alongside the dynamic profile generators in the settings model code and is integrated into the overall settings editor UI (see page 5.2).

Sources: src/cascadia/TerminalSettingsModel/CascadiaSettings.cpp1 src/cascadia/TerminalSettingsModel/Microsoft.Terminal.Settings.ModelLib.vcxproj46-48

Summary Diagram: Natural Language Concepts to Code Entities

Detailed Data Flow of Profile Generation and Consumption

Sources: Aggregated from all generator implementations and settings model loading code.

References

src/cascadia/TerminalSettingsModel/WslDistroGenerator.cpp (lines 20-260)
src/cascadia/TerminalSettingsModel/PowershellCoreProfileGenerator.cpp (lines 25-136)
src/cascadia/TerminalSettingsModel/VsDevCmdGenerator.cpp (lines 1-69)
src/cascadia/TerminalSettingsModel/VsDevShellGenerator.cpp (lines 11-42)
src/cascadia/TerminalSettingsModel/VisualStudioGenerator.cpp
src/cascadia/TerminalSettingsModel/AzureCloudShellGenerator.cpp
src/cascadia/TerminalSettingsModel/SshHostGenerator.cpp
src/cascadia/TerminalSettingsModel/IDynamicProfileGenerator.h
src/cascadia/TerminalSettingsModel/DynamicProfileUtils.h
src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp
src/cascadia/TerminalSettingsModel/Microsoft.Terminal.Settings.ModelLib.vcxproj
src/cascadia/TerminalSettingsModel/CascadiaSettings.h
src/cascadia/TerminalSettingsEditor/SearchIndex.cpp

Dynamic Profile Generators

Overview

Generator Interface

Class Hierarchy

WslDistroGenerator

Detection Flow

PowershellCoreProfileGenerator

Visual Studio Generators

Visual Studio Profile Discovery Flow

AzureCloudShellGenerator

SshHostGenerator

Settings Editor Search Index

Summary Diagram: Natural Language Concepts to Code Entities

Detailed Data Flow of Profile Generation and Consumption

References

On this page

Dynamic Profile Generators

Overview

Generator Interface

Class Hierarchy

WslDistroGenerator

Detection Flow

PowershellCoreProfileGenerator

Visual Studio Generators

Visual Studio Profile Discovery Flow

AzureCloudShellGenerator

SshHostGenerator

Settings Editor Search Index

Summary Diagram: Natural Language Concepts to Code Entities

Detailed Data Flow of Profile Generation and Consumption

References

On this page