Shell Launcher (Industry 8.1)
December 16, 2014
Learn how to enable, disable, and configure Shell Launcher on your Windows Embedded 8.1 Industry (Industry 8.1) device.
You can use Shell Launcher to replace the default Windows 8.1 shell with a custom shell. You can use any application or executable as your custom shell, such as a command window or a custom dedicated application.
Warning
You may specify any executable file to be the default shell except C:\Windows\System32\Eshell.exe. Using Eshell.exe as the default shell will result in a blank screen after user signs in.
You can also configure Shell Launcher to launch different shell applications for different users or user groups.
Important
You cannot use Shell Launcher to launch a Windows Store app as a custom shell. However, you can use Windows 8 Application Launcher to launch a Windows Store app at startup. For more information, see Windows 8 Application Launcher.
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 does not meet your needs.
Turn Shell Launcher on or off
By default, Shell Launcher is not turned on. You can turn Shell Launcher on or off for your Industry 8.1 device by using the following steps:
To turn Shell Launcher on or off by using Control Panel
In Control Panel, click Programs and Features.
In the Programs and Features window, click Turn Windows features on or off.
In the Windows Features window, expand the Embedded Features node, and check or clear the checkbox for Shell Launcher.
To turn Shell Launcher on or off by using DISM
Open a command prompt with administrator rights.
At the command prompt, type the following command to turn on Shell Launcher:
Dism /online /Enable-Feature /FeatureName:ISKU-Shell-Launcher-or-
Type the following command to turn off Shell Launcher:
Dism /online /Disable-Feature /FeatureName:ISKU-Shell-Launcher
After you turn on Shell Launcher, you must then enable Shell Launcher.
Turning on Shell Launcher does not require a device restart.
Enable or disable Shell Launcher
By default, Shell Launcher is not enabled. You can enable or disable Shell Launcher by calling the WESL_UserSetting.SetEnabled function in the Windows Management Instrumentation (WMI) class WESL_UserSetting. If you enable or disable Shell Launcher, the changes do not affect any sessions that are currently signed in; you must sign out and sign back in.
Warning
Microsoft does not support having both Windows 8 Application Launcher and Shell Launcher enabled at the same time.
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 Cmd.exe, but you can specify any executable file to be the default shell.
You can configure Shell Launcher to launch a different shell for specific users or groups if you do not want to run the default shell. For example, you might configure a device to run a custom application shell for guest accounts, but run the standard Windows Explorer shell for administrator accounts in order to service the device.
If you use the WMI providers to configure Shell Launcher for a user or group at run time, you must use the security identifier (SID) for that user or group; you cannot use the user name or group name. If you use Embedded Lockdown Manager (ELM) to configure Shell Launcher, ELM converts user and group names to their SID value.
For more information about common security identifiers, see Well-known SIDs. For more information about ELM, see Embedded Lockdown Manager.
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 is not defined, so we recommend that you avoid assigning a user to multiple groups with different Shell Launcher configurations.
Perform an action when the shell exits
When a custom shell exits, Shell Launcher can perform one of four actions, based on the following return codes:
Return code |
Action |
|---|---|
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 do not 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 does not match a defined value, Shell Launcher performs the default return code action.
For example, your shell might return exit code values of -1, 0, or 255 depending on how the shell exits. You can configure Shell Launcher to restart the system (1) when the shell returns a value of -1, restart the shell (0) when the shell returns a value of 0, and shut down the system (2) when the shell returns a value of 255. Your custom return code action mapping would look like this:
Exit code |
Action |
|---|---|
-1 |
1 (restart the system) |
0 |
0 (restart the app) |
255 |
2 (shut down the system) |
For more information see WESL_UserSetting.SetCustomShell.
Configure Shell Launcher
You can configure the following options for Shell Launcher:
- Enable or disable Shell Launcher.
- Specify a shell configuration for a specific user or group.
- 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.
Any changes do not take effect until a user signs in.
You can use the Shell Launcher WMI providers directly in a Windows PowerShell script or in an application to configure Shell Launcher. You can also use ELM to configure Shell Launcher. The ELM can generate Windows PowerShell scripts that use the WMI providers.
For more information about Shell Launcher WMI providers, see WESL_UserSetting.
For more information about the ELM, see Embedded Lockdown Manager.
Remarks
Warning
If your shell application requires administrator rights, needs to be elevated, and User Account Control (UAC) is present on your device, you must disable UAC so that Shell Launcher can launch the shell application.
Note
Per KB #3008582: If you configure Shell Launcher to launch explorer.exe for an account that does not have administrator rights, Shell Launcher will not launch the File Explorer. Instead, Shell Launcher will launch explorer.exe with the full desktop experience.
Custom shell launches with the same level of user rights as the account that signed in. This means that a user with administrator rights can perform any system action that requires administrator rights, including launching other applications with administrator rights. A user without administrator rights cannot perform any system action that requires administrator rights.