Application Launcher (Industry 8)

7/8/2014

Learn how to configure Application Launcher on your Windows Embedded 8 Industry (Industry 8) device.

You can use Windows 8 Application Launcher to start a Windows 8 app automatically after a user signs in to a Windows Embedded 8 Industry (Industry 8) device and to restart the app when the app exits. You can configure Windows 8 Application Launcher to launch different apps for different users.

If the Windows 8 app is written specifically to work with Windows 8 Application Launcher, you can configure Windows 8 Application Launcher to perform a specified action based on an exit value returned by the app. For example, you could configure Windows 8 Application Launcher to shut down or restart the device when the app exits.

  1. Launch a Windows 8 App
  2. Perform an Action When the App Exits
  3. Default Exit Action
  4. Standard Windows 8 Apps
  5. Specialized Windows 8 Apps
  6. Configure Windows 8 Application Launcher for Different User Accounts
  7. Notes

Launch a Windows 8 App

Before you can configure Windows 8 Application Launcher, you must know the Application User Model ID (AUMID) of the Windows 8 app that you want Windows 8 Application Launcher to launch.

The AUMID format is the package family name followed by an exclamation point and the application ID. See Guidelines for Developing Windows 8 Apps for Windows Embedded 8 Standard for more information about how to identify the AUMID.

Dn195617.note(en-us,WinEmbedded.81).gifImportant:
The app must be installed on the device for the current user for Windows 8 Application Launcher to launch the app. If Windows 8 Application Launcher can’t find the app, or launch the app for any reason, Windows 8 Application Launcher waits a very short period of time (100 milliseconds) and tries to relaunch the app. If Windows 8 Application Launcher cannot launch the app after the 10 attempts, Windows 8 Application Launcher signs out the current user.
You can modify this behavior by changing the FatalErrorAction registry key. See Windows 8 Application Launcher Registry Keys for more information about this registry key.

Perform an Action When the App Exits

When the launched app exits, Windows 8 Application Launcher can perform one of five app exit actions, based on the following action values:

Value

Action

0

Restart the app.

1

Restart the system.

2

Shut down the system.

3

Close Windows 8 Application Launcher.

4

Sign out.

When the launched app exits, Windows 8 Application Launcher can either restart the app or, if the app is designed specifically to work with Windows 8 Application Launcher, perform another action.

Default Exit Action

You must define a default exit action for Windows 8 Application Launcher. If you do not change the initial value, the default action is set to 0 (zero), which indicates that Windows 8 Application Launcher restarts the app when the app exits.

Standard Windows 8 Apps

Windows 8 apps that are not specifically designed to work with Windows 8 Application Launcher, including Windows Store apps, do not return an exit code when the app exits. In these cases, Windows 8 Application Launcher performs the default exit action when it detects that the app has stopped running.

Specialized Windows 8 Apps

If you create a specialized Windows 8 app designed to work with Windows 8 Application Launcher, you can have the app write a CustomExitCode key before it exits. This integer key is written to the app data local settings. If the app exits and Windows 8 Application Launcher detects a CustomExitCode key, Windows 8 Application Launcher can take a specific action based on the value of the CustomExitCode key.

For any given CustomExitCode value returned by the app, you configure the action that Windows 8 Application Launcher takes by mapping that custom exit code to one of the app exit actions.

For example, your specialized Windows 8 app might return CustomExitCode values of 0, 1, or 255 depending on how the app exits. You can configure Windows 8 Application Launcher to restart the system (1) when the app returns a value of 0, restart the app (0) when the app returns a value of 1, and shut down the system (2) when the app returns a value of 255. Your custom return code action mapping would look like this:

CustomExitCode

Action taken

0

1 (restart the system)

1

0 (restart the app)

255

2 (shut down the system)

If Windows 8 Application Launcher can’t find a CustomExitCode, or can’t find a mapping for the CustomExitCode value, Windows 8 Application Launcher performs the default exit action.

Configure Windows 8 Application Launcher for Different User Accounts

You can configure Windows 8 Application Launcher to launch different Windows 8 apps for specific users or groups. For example, you might configure a device to launch one Windows 8 app for customer accounts, but launch a different Windows 8 app for employee accounts.

For each user or group account, you can configure the following: the Windows 8 app to launch, the exit code mapping for specialized Windows 8 apps, and the default exit action.

Windows 8 Application Launcher follows the following order to determine the configuration to use:

  1. Current user account configuration. Windows 8 Application Launcher uses the configuration for the current user account, if one exists. It does not matter if the current user account is a member of the administrator group or not.
  2. Administrator account. If no specific user configuration exists and the current user account is an administrator account, Windows 8 Application Launcher exits without launching any app. If you want to launch an app for an administrator account, you must add a configuration for the specific user account that is a member of the administrator group.
  3. Group account configuration. If a configuration exists for a group that the current user account is a member of, Windows 8 Application Launcher uses the first matching configuration that it finds. The group account must not be a member of the administrator group, or else Windows 8 Application Launcher exits without launching any app.
    Dn195617.note(en-us,WinEmbedded.81).gifTip:
    The group account configuration order is not defined, so we recommend that you avoid assigning a user to multiple groups with different Windows 8 Application Launcher configurations.
  4. Global configuration. If Windows 8 Application Launcher cannot find any configurations defined for the user, Windows 8 Application Launcher uses the global configuration.

Notes

Windows 8 Application Launcher runs on top of the Windows 8 shell, so you may need to lock down any Windows 8 shell functionality that is not appropriate for your customized device.

If a Windows 8 app closes itself, Windows treats it as a crash. If the Windows 8 app crashes, Industry 8 may display a Watson error message on the screen. You can configure Watson to hide the UI. For more information, see WER Settings on MSDN.

Enable Windows 8 Application Launcher

Windows 8 Application Launcher is enabled on Industry 8 by adding a registry key to HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Run. To simplify the process you can create a script file that follows and save it to the root of your system drive as AppLauncher_Enable.reg.

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run]
"EmbeddedAppLauncher"="EmbeddedAppLauncher.exe"

  1. Open an elevated command prompt.

  2. At the command prompt, type the following:

    Reg import %systemdrive%\AppLauncher_Enable.reg
    

Determine the Application User Model ID (AUMID) of Your Application

Before you can configure Windows 8 Application Launcher, you must know the following information:

  • The AUMID of the Windows 8 application to launch.
    The WEMSAL_AppXInformation Windows Management Instrumentation (WMI) provider class contains information about all Windows 8 applications installed on a device. You can use this class to find the AUMID of any installed Windows 8 application on the device and then use this AUMID to configure Windows 8 Application Launcher to launch the application. See WEMSAL_AppXInformation
  • The list of CustomExitCode values, if any, that the Windows 8 application can write to indicate an exit code status.

Configure Global Settings for Windows 8 Application Launcher

The global settings for the Windows 8 Application Launcher are configurable through the WEMSAL_GlobalSetting WMI provider class. You must configure the global settings for the Windows 8 Application Launcher before configuring user-specific or group-specific settings for the Windows 8 Application Launcher. See WEMSAL_GlobalSetting for more information.

Configure Windows 8 Application Launcher for a specific user or group

The user-specific settings for the Windows 8 Application Launcher are configurable through the WEMSAL_UserSetting WMI provider class.

You must configure the global settings for the Windows 8 Application Launcher before configuring user-specific or group-specific settings for the Windows 8 Application Launcher.

See WEMSAL_UserSetting for more information.

The following PowerShell script demonstrates how to use this class to add or update a user specific configuration for Windows 8 Application Launcher. This example configures Windows 8 Application Launcher to launch Internet Explorer 10 when a specific user (“Cashier” in this example) signs in, and restart the app when the app exits.

#
#---Define variables---
#

$COMPUTER = "localhost"
$NAMESPACE = "root\standardcimv2\embedded"

# Define actions to take when the shell program exits.

$ActionRestartApp = 0
$ActionRestartDevice = 1
$ActionShutdownDevice = 2
$ActionCloseMSAL = 3
$ActionLogoff = 4

# Define a user account to configure. 
# To use a different account, change $UserAccount to a user account that is present on your device.

$UserAccount = "Cashier"

# Define the Windows 8 app to launch, in this example, use the Application Model User ID (AUMID) for Internet Explorer 10.
# To use a different Windows 8 app, change $Win8AppAUMID to the AUMID of the Windows 8 app to launch.

$Win8AppAUMID = "DefaultBrowser_NOPUBLISHERID!Microsoft.InternetExplorer.Default"

# Define the default action for Windows 8 Application Launcher to take when the app exits.

$AppExitAction = $ActionRestartApp

#
#---Define helper functions---
#

# Create a function to retrieve the SID for a user account on a machine.
# This function does not check to verify that the user account actually exists.

function Get-UsernameSID($AccountName) {

    $NTUserObject = New-Object System.Security.Principal.NTAccount($AccountName)
    $NTUserSID = $NTUserObject.Translate([System.Security.Principal.SecurityIdentifier])

    return $NTUserSID.Value
    
}

# Get the SID for the user account.

$UserSID = Get-UsernameSID($UserAccount)

# Check to see if a configuration already exists for the user, and if so, update it.

$UserConfig = get-WMIObject -namespace $NAMESPACE -computer $COMPUTER -class WEMSAL_UserSetting | 
    where {
        $_.SID -eq $UserSID
    }

if ($UserConfig) {

    # Configuration already exists.  Update it.

    $UserConfig.AppUserModelId = $Win8AppAUMID;
    $Userconfig.DefaultReturnCodeAction = $AppExitAction;
    $UserConfig.Put() | Out-Null;
    
    "Updated user setting for Windows 8 Application Launcher."
    "  SID = " + $UserConfig.Sid
    "  AUMID = " + $UserConfig.AppUserModelId
    "  App exit action = " + $UserConfig.DefaultReturnCodeAction

    } else {

    # Create a new configuration for the user to launch IE10, and log out the user if the app exits.

    Set-WmiInstance -class WEMSAL_UserSetting -ComputerName $COMPUTER -Namespace $NAMESPACE -Argument @{
        Sid = $UserSID;
        AppUserModelId = $Win8AppAUMID;
        DefaultReturnCodeAction = $AppExitAction } | Out-Null;
    
    # Confirm that the settings were created properly.    
    
    $UserConfig = get-WMIObject -namespace $NAMESPACE -computer $COMPUTER -class WEMSAL_UserSetting | 
    where {
        $_.SID -eq $UserSID
    }

    if ($UserConfig) {
        
        "Created new user setting for Windows 8 Application Launcher."
        "  SID = " + $UserConfig.Sid
        "  AUMID = " + $UserConfig.AppUserModelId
        "  App exit action = " + $UserConfig.DefaultReturnCodeAction
    
    } else {
    
        "Could not create user setting for Windows 8 Application Launcher."
    }
}
Show: