Microsoft-Windows-Embedded-ShellLauncher (Industry 8.1)

Article
12/14/2016

7/8/2014

Review the settings and examples of the Microsoft-Windows-Embedded-ShellLauncher feature package for Windows System Image Manager (SIM) in Windows Embedded 8.1 Industry (Industry 8.1).

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.

Important

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 a 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.

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 or 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.

Important

A custom shell is launched with the same level of user rights as the account that is 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, while a user without administrator rights cannot. If your shell application requires administrator rights and needs to be elevated, and User Account Control (UAC) is present on your device, you must disable UAC in order for Shell Launcher to launch the shell application.

Warning

Microsoft does not support having both Shell Launcher and Windows 8 Application Launcher enabled at the same time.

Settings available in Windows SIM

Default shell settings

The default shell settings are used when Shell Launcher is enabled but the security identifier (SID) of the user who is currently signed in does not match any custom defined Shell Launcher configurations.

Setting	Description
DefaultReturnCodeAction	Specifies what action to take, based on the return code.
Shell	Specifies the application or executable to use as the default custom shell.

UserSettings settings

Use the UserSettings settings to specify what custom shell and what default return code action to use for specific users or user groups.

Setting	Description
AccountName	Specifies the user or group account name the custom shell will be used for.
Action	Specifies whether to add, modify, or remove this user setting from the list.
DefaultReturnCodeAction	Specifies what action to take based on the return code.
Domain	Specifies account name's domain.
Key	Index key for this setting in the setting list.
Shell	Specifies the application or executable to use as the default custom shell.

CustomReturnCodeAction settings

Use these settings to map an exit code from a custom shell to a shell exit action. If the exit code does not match a defined value, Shell Launcher performs the default return action code.

Setting	Description
Action	Specifies the shell exit action to be performed.
Action	Specifies whether to add, modify, or remove the custom return code configuration from the list.
ReturnCode	Specifies the custom shell return code to map to the shell exit action.

Settings details

Default shell settings

DefaultReturnCodeAction

When a custom shell exits, Shell Launcher can perform one of four actions, based on the return codes.

Type
Int32

Values

Value

Description

0

Restart the shell.

This is the default value.

1

Restart the device.

2

Shut down the device.

3

Do nothing.

Value	Description
0	Restart the shell. This is the default value.
1	Restart the device.
2	Shut down the device.
3	Do nothing.

Parent hierarchy
Microsoft-Windows-Embedded-ShellLauncher | DefaultActionCodeAction

Valid passes
oobeSystem

XML example

<settings pass="oobeSystem">
    <component name="Microsoft-Windows-Embedded-ShellLauncher" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="NonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <Shell>testshell.exe</Shell>
        <DefaultReturnCodeAction>1</DefaultReturnCodeAction>
    </component>
</settings>

Shell

Type
String

Values

Value

Description

ExecutableFile

Specifies the name and path, if required, of the executable to use as the default custom shell.

The default value is cmd.exe.

Value	Description
ExecutableFile	Specifies the name and path, if required, of the executable to use as the default custom shell. The default value is cmd.exe.

Parent hierarchy
Microsoft-Windows-Embedded-ShellLauncher | Shell

Valid passes
oobeSystem

XML example

<settings pass="oobeSystem">
    <component name="Microsoft-Windows-Embedded-ShellLauncher" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="NonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <Shell>testshell.exe</Shell>
        <DefaultReturnCodeAction>1</DefaultReturnCodeAction>
    </component>
</settings>

UserSettings settings

AccountName

Specifies the user or group account name the custom shell will be used for.

Type
String

Values

Value

Description

UserOrGroupName

Specifies the name of the user or user group this custom shell will apply to.

Value	Description
UserOrGroupName	Specifies the name of the user or user group this custom shell will apply to.

Parent hierarchy
Microsoft-Windows-Embedded-ShellLauncher | UserSettings | User | AccountName

Valid passes
oobeSystem

XML example

<settings pass="oobeSystem">
    <component name="Microsoft-Windows-Embedded-ShellLauncher" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="NonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <UserSettings>
            <User wcm:action="add">
                <AccountName>Tester1</AccountName>
                <DefaultReturnCodeAction>0</DefaultReturnCodeAction>
                <Domain>TestDomain</Domain>
                <Key>1</Key>
                <Shell>cmd.exe</Shell>
            </User>
    </component>
</settings>

Action

Specifies whether to add, modify, or remove this user setting from the list.

Values

Value

Description

AddListItem

Add a new custom configuration to the list.

Modify

Modify an existing custom configuration.

RemoveListItem

Remove a custom configuration from the list.

Value	Description
AddListItem	Add a new custom configuration to the list.
Modify	Modify an existing custom configuration.
RemoveListItem	Remove a custom configuration from the list.

Parent hierarchy
Microsoft-Windows-Embedded-ShellLauncher | UserSettings | User | Action

Valid passes
oobeSystem

XML example

<settings pass="oobeSystem">
    <component name="Microsoft-Windows-Embedded-ShellLauncher" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="NonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <UserSettings>
            <User wcm:action="add">
                <AccountName>Tester1</AccountName>
                <DefaultReturnCodeAction>0</DefaultReturnCodeAction>
                <Domain>TestDomain</Domain>
                <Key>1</Key>
                <Shell>cmd.exe</Shell>
            </User>
    </component>
</settings>

DefaultReturnCodeAction

Specifies what action to take based on the return code.

Type
Int32

Values

Value

Description

0

Restart the shell.

1

Restart the device.

2

Shut down the device.

3

Do nothing.

Value	Description
0	Restart the shell.
1	Restart the device.
2	Shut down the device.
3	Do nothing.

Parent hierarchy
Microsoft-Windows-Embedded-ShellLauncher | UserSettings | User | DefaultReturnCodeAction

Valid passes
oobeSystem

XML example

<settings pass="oobeSystem">
    <component name="Microsoft-Windows-Embedded-ShellLauncher" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="NonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <UserSettings>
            <User wcm:action="add">
                <AccountName>Tester1</AccountName>
                <DefaultReturnCodeAction>0</DefaultReturnCodeAction>
                <Domain>TestDomain</Domain>
                <Key>1</Key>
                <Shell>cmd.exe</Shell>
            </User>
    </component>
</settings>

Domain

Specifies account name's domain.

Type
String

Values

Value

Description

UserOrGroupDomain

Specifies the domain of the user or user group this custom shell will be used for.

Value	Description
UserOrGroupDomain	Specifies the domain of the user or user group this custom shell will be used for.

Parent hierarchy
Microsoft-Windows-Embedded-ShellLauncher | UserSettings | User | Domain

Valid passes
oobeSystem

XML example

<settings pass="oobeSystem">
    <component name="Microsoft-Windows-Embedded-ShellLauncher" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="NonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <UserSettings>
            <User wcm:action="add">
                <AccountName>Tester1</AccountName>
                <DefaultReturnCodeAction>0</DefaultReturnCodeAction>
                <Domain>TestDomain</Domain>
                <Key>1</Key>
                <Shell>cmd.exe</Shell>
            </User>
    </component>
</settings>

Key

Index key for this setting in the setting list.

Type
Uint32, min 1

Values

Value

Description

IntegerKey

Specifies the unique key of this user setting in the list.

Value	Description
IntegerKey	Specifies the unique key of this user setting in the list.

Parent hierarchy
Microsoft-Windows-Embedded-ShellLauncher | UserSettings | User | Key

Valid passes
oobeSystem

XML example

<settings pass="oobeSystem">
    <component name="Microsoft-Windows-Embedded-ShellLauncher" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="NonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <UserSettings>
            <User wcm:action="add">
                <AccountName>Tester1</AccountName>
                <DefaultReturnCodeAction>0</DefaultReturnCodeAction>
                <Domain>TestDomain</Domain>
                <Key>1</Key>
                <Shell>cmd.exe</Shell>
            </User>
    </component>
</settings>

Shell

Specifies the application or executable to use as the default custom shell.

Type
String

Values

Value

Description

ExecutableFileName

Specifies the name and path, if required, of the executable to use as this user's custom shell.

Value	Description
ExecutableFileName	Specifies the name and path, if required, of the executable to use as this user's custom shell.

Parent hierarchy
Microsoft-Windows-Embedded-ShellLauncher | UserSettings | User | Shell

Valid passes
oobeSystem

XML example

<settings pass="oobeSystem">
    <component name="Microsoft-Windows-Embedded-ShellLauncher" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="NonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <UserSettings>
            <User wcm:action="add">
                <AccountName>Tester1</AccountName>
                <DefaultReturnCodeAction>0</DefaultReturnCodeAction>
                <Domain>TestDomain</Domain>
                <Key>1</Key>
                <Shell>cmd.exe</Shell>
            </User>
    </component>
</settings>

CustomReturnCodeAction settings

Maps a custom shell's return code to a shell exit action code.

Action

Specifies the shell exit action to perform.

Type
Int32

Values

Value

Description

0

Restart the shell.

This is the default value.

1

Restart the device.

2

Shut down the device.

3

Do nothing.

Value	Description
0	Restart the shell. This is the default value.
1	Restart the device.
2	Shut down the device.
3	Do nothing.

Parent hierarchy
Microsoft-Windows-Embedded-ShellLauncher | UserSettings | User | CustomReturnCodeAction | CodeAction | Action

Valid passes
oobeSystem

XML example

<settings pass="oobeSystem">
    <component name="Microsoft-Windows-Embedded-ShellLauncher" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="NonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <Shell>testshell.exe</Shell>
        <DefaultReturnCodeAction>1</DefaultReturnCodeAction>
    </component>
</settings>

Action

Specifies whether to add, modify, or remove the custom return code configuration from the list.

Values

Value

Description

AddListItem

Add a new custom configuration to the list.

Modify

Modify an existing custom configuration.

RemoveListItem

Remove a custom configuration from the list.

Value	Description
AddListItem	Add a new custom configuration to the list.
Modify	Modify an existing custom configuration.
RemoveListItem	Remove a custom configuration from the list.

Parent hierarchy
Microsoft-Windows-Embedded-ShellLauncher | UserSettings | User | CustomReturnCodeAction | CodeAction | Action

Valid passes
oobeSystem

XML example

<settings pass="oobeSystem">
    <component name="Microsoft-Windows-Embedded-ShellLauncher" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="NonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <Shell>testshell.exe</Shell>
        <DefaultReturnCodeAction>1</DefaultReturnCodeAction>
    </component>
</settings>

ReturnCode

Type
String

Values

Value

Description

CustomReturnCode

Specifies the return code to map to the indicated shell exit code.

Value	Description
CustomReturnCode	Specifies the return code to map to the indicated shell exit code.

Parent hierarchy
Microsoft-Windows-Embedded-ShellLauncher | UserSettings | User | CustomReturnCodeAction | CodeAction | ReturnCode

Valid passes
oobeSystem

XML example

<settings pass="oobeSystem">
    <component name="Microsoft-Windows-Embedded-ShellLauncher" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="NonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <Shell>testshell.exe</Shell>
        <DefaultReturnCodeAction>1</DefaultReturnCodeAction>
    </component>
</settings>

Microsoft-Windows-Embedded-ShellLauncher (Industry 8.1)

Settings available in Windows SIM

Default shell settings

UserSettings settings

CustomReturnCodeAction settings

Settings details

Default shell settings

DefaultReturnCodeAction

Shell

UserSettings settings

AccountName

Action

DefaultReturnCodeAction

Domain

Key

Shell

CustomReturnCodeAction settings

Action

Action

ReturnCode

See Also

Concepts

Additional resources