Partager via

Microsoft-Windows-Embedded-ShellLauncher (Industry 8.1)

  • Article

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

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.

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

See Also

Concepts

Add lockdown and branding features to your image by using Windows SIM
Shell Launcher