Configure Shell Launcher

• Koskee seuraavia::

  ✅ Windows 11, ✅ Windows 10

There are two ways you can configure Shell Launcher:

1. Using the ShellLauncher node of the Assigned Access Configuration Service Provider (CSP), which also automatically enables Shell Launcher on the device, if the device supports it
2. Using the Shell Launcher WMI providers directly in an application. When using this method, you must enable Shell Launcher first

You can configure the following options for Shell Launcher:

• Add/remove a shell configuration for a specific user or group
• Change the default shell configuration
• Get information on a shell configuration for a specific user or group

Note

Any changes don't take effect until a user signs in.

Enable Shell Launcher

Shell Launcher is an optional component in Windows that is not enabled by default. To configure it, you must first enable it. You can enable and configure Shell Launcher in a customized Windows image, or you can enable it before applying a provisioning package to configure it.

Note

When you configure Shell Launcher with the Assigned Access Configuration Service Provider (CSP), Shell Launcher is automatically enabled, if the device supports it. There's no need to enable Shell Launcher separately when you configure it using Assigned Access CSP.

There are multiple ways to enable Shell Launcher, select the method that best fits your needs to learn more.

Control Panel

To enable Shell Launcher using Control Panel, follow these steps:

1. Open Control Panel > Programs > Turn Windows features on or off or use the command optionalfeatures.exe
2. Expand Device Lockdown and select Shell Launcher
3. Select OK to enable Shell Launcher

PowerShell

To enable Shell Launcher using PowerShell, follow these steps:

1. Open a PowerShell window with administrator privileges

2. Run the following command:

   Enable-WindowsOptionalFeature -FeatureName Client-DeviceLockdown,Client-EmbeddedShellLauncher -Online
   

DISM

The following example uses a Windows image called install.wim, but you can use the same procedure to apply a provisioning package.

1. Open a command prompt with administrator privileges.
2. Copy install.wim to a temporary folder on hard drive (in the following steps, we assume it's called C:\wim)
3. Modify the following script to match your environment:

@echo off
REM Create a new directory
md c:\wim

REM Mount the image
dism /mount-wim /wimfile:c:\bootmedia\sources\install.wim /index:1 /MountDir:c:\wim

REM Enable the feature
dism /image:c:\wim /enable-feature /all /featureName:Client-EmbeddedShellLauncher

REM Commit the change
dism /unmount-wim /MountDir:c:\wim /Commit

For more information on DISM, see What Is Deployment Image Servicing and Management.

WMI

You can enable or disable Shell Launcher by calling the SetEnabled function in the Windows Management Instrumentation (WMI) class WESL_UserSetting.

For more information, see WESL_UserSetting.

Launch different shells for different user accounts

By default, Shell Launcher runs the default shell, which is specified when you create the OS image at design time. The default shell is set to the Windows Command Processor (Cmd.exe), but you can specify any executable file to be the default shell.

You can also configure Shell Launcher to launch a different shell for specific users or groups if you don't want to run the default shell. For example, you might configure a device to launch a custom application shell for guest accounts, but run the standard Windows Explorer shell for administrator accounts for servicing the device.

When the current signed in account belongs to two or more groups that have different configurations defined for each group, Shell Launcher uses the first configuration it finds. The search order isn't defined, so we recommend that you avoid assigning a user to multiple groups with different Shell Launcher configurations.

Note

If you use the WMI provider to configure Shell Launcher for a user or group at run time, you must use the security identifier (SID) for that security principal. You can't use the user name or group name.

For more information about common security identifiers, see Well-known SIDs.

Shell Launcher startup and exit behavior

Shell Launcher processes the Run and RunOnce registry keys before starting the custom shell, so your custom shell doesn't need to handle the automatic startup of other applications and services.

Shell Launcher also handles the behavior of the system when your custom shell exits. You can configure the shell exit behavior if the default behavior doesn't meet your needs. When a custom shell exits, Shell Launcher can perform one of four actions:

• 0: Restart the shell
• 1: Restart the device
• 2: Shut down the device
• 3: Do nothing

Important

Make sure that your shell application does not automatically exit and is not automatically closed by any features such as Dialog Filter, as this can lead to an infinite cycle of exiting and restarting, unless the return code action is set to do nothing.

Default return code action

You can define a default return code action for Shell Launcher with the DefaultReturnCodeAction setting. If you don't change the initial value, the default return code action is set to 0 (zero), which indicates that Shell Launcher restarts the shell when the shell exits.

Map the exit code to a Shell Launcher action

Shell Launcher can take a specific action based on the exit code returned by the shell. For any given exit code returned by the shell, you can configure the action that Shell Launcher takes by mapping that exit code to one of the shell exit actions.

If the exit code doesn't match a defined value, Shell Launcher performs the default return code action.

For example, your shell might return exit code values of -1, 0, 1, or 255 depending on how the shell exits. You can configure Shell Launcher to:

• restart the device (1) when the shell returns an exit code of value -1
• restart the shell (0) when the shell returns an exit code of value 0
• do nothing (3) when the shell returns an exit code of value 1
• shut down the device (2) when the shell returns an exit code of value 255

Your custom return code action mapping would look like this:

Exit code	Action
-1	1 (restart the device)
0	0 (restart the shell)
1	3 (do nothing)
255	2 (shut down the device)

Set your custom shell with the Assigned Access CSP

The configuration of Shell Launcher is done using an XML file. The XML file is applied to the device via the Assigned Access CSP, using one of the following options:

• A Mobile Device Management (MDM) solution, like Microsoft Intune
• Provisioning packages
• The MDM Bridge WMI Provider

Note

Configuring Shell Launcher using Assigned Access CSP, automatically enables Shell Launcher on the device, if the device supports it.

To learn how to configure the Shell Launcher XML file, see Create a Shell Launcher configuration file.

The following instructions provide details about how to configure your devices. Select the option that best suits your needs.

Intune/CSP

You can configure devices using a custom policy with the AssignedAccess CSP.

• Setting: ./Vendor/MSFT/AssignedAccess/ShellLauncher
• Value: content of the XML configuration file

Assign the policy to a group that contains as members the devices that you want to configure.

PPKG

You can configure Shell Launcher by creating a provisioning package and then applying the provisioning package during image deployment time or at runtime:

• If you're creating an installation media with settings for Shell Launcher included in the image, or you're applying a provisioning package during setup, you must enable Shell Launcher on the installation media with DISM for a provisioning package to successfully apply
• If exectuing the provisioning package at runtime, ensure to enable Shell Launcher before applying the provisioning package

Use the following settings to create a provisioning package:

Path	Setting name	Value
SMISettings/ShellLauncher/	Enable	ENABLE
SMISettings/ShellLauncher/	*	It depends on specific settings.

Apply the provisioning package to the devices that you want to configure.

PowerShell

Configure your devices using PowerShell scripts via the MDM Bridge WMI Provider.

Important

For all device settings, the WMI Bridge client must be executed as SYSTEM (LocalSystem) account.

To test the PowerShell script, you can:

1. Download the psexec tool
2. Open an elevated command prompt and run: psexec.exe -i -s powershell.exe
3. Run the script in the PowerShell session

$shellLauncherConfiguration = @"

# content of the XML configuration file

"@

$namespaceName="root\cimv2\mdm\dmmap"
$className="MDM_AssignedAccess"
$obj = Get-CimInstance -Namespace $namespaceName -ClassName $className
$obj.ShellLauncher = [System.Net.WebUtility]::HtmlEncode($shellLauncherConfiguration)
$obj = Set-CimInstance -CimInstance $obj -ErrorVariable cimSetError -ErrorAction SilentlyContinue
if($cimSetError) {
    Write-Output "An ERROR occurred. Displaying error record and attempting to retrieve error logs...`n"
    Write-Error -ErrorRecord $cimSetError[0]

    $timeout = New-TimeSpan -Seconds 30
    $stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
    $eventLogFilterHashTable = @{ LogName='Microsoft-Windows-AssignedAccess/Admin' }
    do{
        $events = Get-WinEvent -FilterHashtable $eventLogFilterHashTable -ErrorAction Ignore
    } until ($events.Count -or $stopwatch.Elapsed -gt $timeout) # wait for the log to be available

    if($events.Count) {
        $events | ForEach-Object {
            Write-Output "$($_.TimeCreated) [$($_.LevelDisplayName.ToUpper())] $($_.Message -replace "`n|`r")"
        }
    } else {
        Write-Warning "Timed-out attempting to retrieve event logs..."
    }

    Exit 1
}

Write-Output "Successfully applied Shell Launcher configuration"

For more information, see Use PowerShell scripting with the WMI Bridge Provider.

Tip

For practical examples, see the Quickstart: configure a kiosk experience with Shell Launcher.

User experience

After the settings are applied, the users that are configured to use Shell Launcher will execute the custom shell after sign-in.

Depending on your configuration, you can have a user to automatically sign in to the device.

Remove Shell Launcher

Here are the options to remove Shell Launcher, select the method that best fits your needs:

Intune/CSP

Unassign or delete the policy that contains the configuration.

PPKG

Uninstall the provisioning package that contains the configuration.

PowerShell

$namespaceName="root\cimv2\mdm\dmmap"
$className="MDM_AssignedAccess"
$obj = Get-CimInstance -Namespace $namespaceName -ClassName $className
$obj.Configuration = $null
Set-CimInstance -CimInstance $obj

Next steps

Learn how to configure the Shell Launcher XML file:

Create a Shell Launcher configuration file