deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-06-17 19:33:37 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Update Assigned Access configuration and redirections

Browse Source
This commit is contained in:
Paolo Matarazzo
2024-02-29 09:28:45 -05:00
parent c3dd31df0c
commit a9d90e9096
5 changed files with 151 additions and 183 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
windows/configuration/assigned-access/configuration-file.md
View File

@ -358,7 +358,7 @@ This sample demonstrates that both UWP and Win32 apps can be configured to autom
Under `Configs`, define one or more user accounts and their association with a profile.
When the user account signs in on the device, the associated Assigned Access profile is enforced along with policy settings that are part of the restricted user experience.
When the user account signs in, the associated Assigned Access profile is enforced along with policy settings that are part of the restricted user experience.
You can assign:

1
windows/configuration/assigned-access/index.md
View File

@ -109,4 +109,5 @@ HKLM\SOFTWARE\Microsoft\Windows\AssignedAccessCsp
These locations contain the latest "evaluated" configuration for each sign-in user:
"HKCU\SOFTWARE\Microsoft\Windows\AssignedAccessConfiguration" (If it doesn't exist, it means no Assigned Access to be enforced for this user.)
-->

324
windows/configuration/assigned-access/shell-launcher/configuration-file.md
View File

@ -1,217 +1,179 @@
---
title: Create an Shell Launcher configuration file
title: Create a Shell Launcher configuration file
description: Learn how to create an XML file to configure a device with Shell Launcher.
ms.date: 02/12/2024
ms.topic: how-to
---
# Create an Shell Launcher configuration file
# Create a Shell Launcher configuration file
This article provides practical examples of Shell Launcher XML configuration files.
To configure Shell Launcher, you must create and apply a configuration XML file to your devices. The configuration file must conform to a schema, as defined in [Shell Launcher XML Schema Definition (XSD)](xsd.md).
Let's start by looking at the basic structure of the XML file.
This article describes how to configure a Shell Launcher configuration file, including practical examples.
- A configuration xml can define one or multiple `Profiles`
- Each profile has a unique `Profile Id` and defines a `Shell` elemnt, which is the application that executes when the user signs in
- A profile can define a default action to be taken when the application exits and may define actions to be taken when the application exits with a specific return code
- A profile must be associated to a user account to have an effect
- You can define a `Default profile` that is used when no other profile is associated to a user account
- A configuration xml can define one or multiple `configs`
- Each config associates a user account to a `profile Id`
- A profile has no effect if it's not associated to a user account
Let's start by looking at the basic structure of the XML file. A Shell Launcher configuration file contains:
You can start your file by pasting the following XML code into a text editor, and saving the file with an xml extension. For example, `kiosk.xml`.
- One or multiple `profiles`. Each `profile` defines:
- the application that replaces the standard Windows shell (`Explorer.exe`), which is executed when a user signs in
- default action to be taken when the application exits, and actions to be taken when the application exits with a specific return code
- One or multiple `configs`. Each `config` associates a user account to a `profile`
> [!NOTE]
> A profile has no effect if it's not associated to a user account.
Here's a basic example of a Shell Launcher configuration file, with one profile and one config:
```xml
<?xml version="1.0" encoding="utf-8" ?>
<ShellLauncherConfiguration
xmlns="http://schemas.microsoft.com/ShellLauncher/2018/Configuration"
xmlns:V2="http://schemas.microsoft.com/ShellLauncher/2019/Configuration">
<Profiles>
<!-- Add configuration here as needed -->
</Profiles>
<Configs>
<!-- Add configuration here as needed -->
</Configs>
</ShellLauncherConfiguration>
```
## Profiles node
If you want to define a default profile, you can use the `DefaultProfile` element:
```xml
<Profiles>
<DefaultProfile>
<!-- Add configuration here as needed -->
</DefaultProfile>
</Profiles>
```
Each profile is identified by a unique identifier `Profile Id`, for example:
```xml
<Profiles>
<Profile Id="{EDB3036B-780D-487D-A375-69369D8A8F78}">
<!-- Add configuration here as needed -->
xmlns="http://schemas.microsoft.com/ShellLauncher/2018/Configuration"
xmlns:V2="http://schemas.microsoft.com/ShellLauncher/2019/Configuration">
<Profiles>
<Profile Id="{GUID}">
<!-- Add configuration here as needed -->
</Profile>
</Profiles>
```
### Shell node
The `Shell` node defines the application that executes when the user signs in:
- The `Shell` attribute is the path to the application
- The `V2:AppType` attribute defines the type of application
- The `V2:AllAppsFullScreen` attribute is a boolean value that defines if all applications are executed in full screen
```xml
<Shell Shell="" V2:AppType="" V2:AllAppsFullScreen="">
<ReturnCodeActions>
<ReturnCodeAction ReturnCode="" Action=""/>
</ReturnCodeActions>
<DefaultAction Action=""/>
</Shell>
```
```xml
<?xml version="1.0" encoding="utf-8" ?>
<ShellLauncherConfiguration
xmlns="http://schemas.microsoft.com/ShellLauncher/2018/Configuration"
xmlns:V2="http://schemas.microsoft.com/ShellLauncher/2019/Configuration">
<Profiles>
<DefaultProfile>
<Shell Shell=""/>
</DefaultProfile>
<Profile Id="">
<Shell Shell="" V2:AppType="" V2:AllAppsFullScreen="">
<ReturnCodeActions>
<ReturnCodeAction ReturnCode="" Action=""/>
</ReturnCodeActions>
<DefaultAction Action=""/>
</Shell>
</Profile>
</Profiles>
<Configs>
<Config>
<AutoLogonAccount/>
<Profile Id=""/>
</Config>
</Configs>
</Profiles>
<Configs>
<Config>
<!-- Add configuration here as needed -->
</Config>
</Configs>
</ShellLauncherConfiguration>
```
## Default action, custom action, exit code
## Profiles
A configuration file can contain one or more profiles. Each profile is identified by a unique identified `Profile Id` and, optionally, a `Name`. For example:
```xml
<Profiles>
<Profile Id="{EDB3036B-780D-487D-A375-69369D8A8F78}" Name="Microsoft Learn example">
<!-- Add configuration here as needed -->
</Profile>
</Profiles>
```
> [!TIP]
> The `Profile Id` must be unique within the XML file. You can generate a GUID with the PowerShell cmdlet `New-Guid`.
You can define a `Defaultprofile` that is used when no other profile is associated to a user account. This ensures that every user using the device uses the same application. Example:
```xml
<Profiles>
<DefaultProfile>
<!-- Add configuration here as needed -->
</DefaultProfile>
</Profiles>
```
### Shell
Each profile defines a `Shell` element, which contains details about the application to execute. The `Shell` element has the following properties:
| Property| Description | Details |
|-|-|-|
|`Shell`| Path to the application. ||
|`V2:AppType`| Defines the type of application. |Allowed values are `Desktop` and `UWP`.|
|`V2:AllAppsFullScreen` | Boolean value that defines if all applications are executed in full screen. |- When set to `True`, Shell Launcher will runs every app in full screen, or maximized for desktop apps<br>- When set to `False` or not set, only the custom shell app runs in full screen; other apps launched by the user run in windowed mode.|
Example:
```xml
<Profile Id="{GUID}">
<Shell Shell="" V2:AppType="" V2:AllAppsFullScreen="">
<!-- Add configuration here as needed -->
</Shell>
</Profile>
```
#### ReturnCodeActions
Shell Launcher defines four actions to handle app exits. You can customize Shell Launcher and use the actions based on different exit code.
| Value | Description |
|--|--|
| 0 | Restart the shell |
| 1 | Restart the device |
| 2 | Shut down the device |
| 3 | Do nothing |
| `0` | Restart the shell |
| `1` | Restart the device |
| `2` | Shut down the device |
| `3` | Do nothing |
These actions can be used as default action, or can be mapped to a specific exit code. Refer to [Shell Launcher](/windows-hardware/customize/enterprise/wesl-usersettingsetcustomshell) to see how these codes with Shell Launcher WMI.
These actions can be used as default action, or can be mapped to a specific exit code. Refer to [Shell Launcher](/windows-hardware/customize/enterprise/wesl-usersettingsetcustomshell) to see how use these codes with Shell Launcher WMI.
To configure these actions with Shell Launcher CSP, use below syntax in the Shell Launcher configuration xml. You can specify at most four custom actions mapping to four exit codes, and one default action for all other exit codes. When app exits and if the exit code is not found in the custom action mapping, or there is no default action defined, it will be no-op, i.e. nothing happens. So it's recommended to at least define DefaultAction. [Get XML examples for different Shell Launcher v2 configurations.](https://github.com/Microsoft/Windows-iotcore-samples/tree/develop/Samples/ShellLauncherV2)
``` xml
<ReturnCodeActions>
<ReturnCodeAction ReturnCode="0" Action="RestartShell"/>
<ReturnCodeAction ReturnCode="-1" Action="RestartDevice"/>
<ReturnCodeAction ReturnCode="255" Action="ShutdownDevice"/>
<ReturnCodeAction ReturnCode="1" Action="DoNothing"/>
</ReturnCodeActions>
<DefaultAction Action="RestartDevice"/>
Example:
```xml
<Profile Id="{GUID}">
<Shell Shell="" V2:AppType="" V2:AllAppsFullScreen="">
<ReturnCodeActions>
<ReturnCodeAction ReturnCode="0" Action="RestartShell"/>
<ReturnCodeAction ReturnCode="-1" Action="RestartDevice"/>
<ReturnCodeAction ReturnCode="255" Action="ShutdownDevice"/>
<ReturnCodeAction ReturnCode="1" Action="DoNothing"/>
</ReturnCodeActions>
<DefaultAction Action="RestartDevice"/>
</Shell>
</Profile>
```
## AllAppsFullScreen
In the XML for Shell Launcher v2, note the **AllAppsFullScreen** attribute. When set to **True**, Shell Launcher will run every app in full screen, or maximized for desktop apps. When this attribute is set to **False** or not set, only the custom shell app runs in full screen; other apps launched by the user will run in windowed mode.
### AppType
Allowed values are `Desktop` and `UWP`.
`AllAppsFullScreen` is a boolean value. If true, all applications are executed in full screen. If false...
**Desktop application**
:::row:::
:::column span="1":::
**Scenario**
:::column-end:::
:::column span="3":::
**Sample Xml**
:::column-end:::
:::row-end:::
:::row:::
:::column span="1":::
**Desktop application**
:::column-end:::
:::column span="3":::
In this example, Microsoft Edge is executed in full screen, opening a website. The website is reloaded after 2 minutes of inactivity.
```xml
<Profile Id="{EDB3036B-780D-487D-A375-69369D8A8F78}">
<Shell Shell="%ProgramFiles(x86)%\Microsoft\Edge\Application\msedge.exe --kiosk https://www.contoso.com --edge-kiosk-type=fullscreen --kiosk-idle-timeout-minutes=2" V2:AppType="Desktop" V2:AllAppsFullScreen="true">
<ReturnCodeActions>
<ReturnCodeAction ReturnCode="0" Action="RestartShell"/>
<ReturnCodeAction ReturnCode="-1" Action="RestartDevice"/>
<ReturnCodeAction ReturnCode="255" Action="ShutdownDevice"/>
</ReturnCodeActions>
<DefaultAction Action="RestartShell"/>
</Shell>
</Profile>
```
:::column-end:::
:::row-end:::
:::row:::
:::column span="1":::
**UWP application**
In this example, the Weather app is executed in full screen.
:::column-end:::
:::column span="3":::
```xml
<?xml version="1.0" encoding="utf-8"?>
<ShellLauncherConfiguration xmlns="http://schemas.microsoft.com/ShellLauncher/2018/Configuration"
xmlns:V2="http://schemas.microsoft.com/ShellLauncher/2019/Configuration">
<Profiles>
<DefaultProfile>
<Shell Shell="Microsoft.BingWeather_8wekyb3d8bbwe!App" V2:AppType="UWP">
<DefaultAction Action="RestartShell"/>
</Shell>
</DefaultProfile>
</Profiles>
<Configs/>
</ShellLauncherConfiguration>
```
:::column-end:::
:::row-end:::
In this example, Microsoft Edge is executed in full screen, opening a website. The website is reloaded after 2 minutes of inactivity.
## Kiosk example
```xml
<Profile Id="{EDB3036B-780D-487D-A375-69369D8A8F78}">
<Shell Shell="%ProgramFiles(x86)%\Microsoft\Edge\Application\msedge.exe --kiosk https://www.contoso.com --edge-kiosk-type=fullscreen --kiosk-idle-timeout-minutes=2" V2:AppType="Desktop" V2:AllAppsFullScreen="true">
<ReturnCodeActions>
<ReturnCodeAction ReturnCode="0" Action="RestartShell"/>
<ReturnCodeAction ReturnCode="-1" Action="RestartDevice"/>
<ReturnCodeAction ReturnCode="255" Action="ShutdownDevice"/>
</ReturnCodeActions>
<DefaultAction Action="RestartShell"/>
</Shell>
</Profile>
```
**UWP application**
In this example, the Weather app is executed in full screen.
```xml
<?xml version="1.0" encoding="utf-8"?>
<ShellLauncherConfiguration xmlns="http://schemas.microsoft.com/ShellLauncher/2018/Configuration"
xmlns:V2="http://schemas.microsoft.com/ShellLauncher/2019/Configuration">
<Profiles>
<DefaultProfile>
<Shell Shell="Microsoft.BingWeather_8wekyb3d8bbwe!App" V2:AppType="UWP">
<DefaultAction Action="RestartShell"/>
</Shell>
</DefaultProfile>
</Profiles>
<Configs/>
</ShellLauncherConfiguration>
```
## Configs
Under `Configs`, define one or more user accounts and their association with a profile.
You can specify a name, SID or AutologonAccount
When the user account signs in, the associated Shell Launcher profile is applied, loading the application specified in the profile.
```xml
<Configs>
<Config>
<AutoLogonAccount/>
<Profile Id=""/>
</Config>
</Configs>
```
## Example
[!INCLUDE [quickstart-xml](includes/quickstart-xml.md)]
<!--troubleshooting
Event Viewer
Run "eventvwr.msc"
Navigate to "Applications and Services Logs"
There are 2 areas of your interests:
"Microsoft-Windows-AssignedAccess"
"Microsoft-Windows-AssignedAccessBroker"
Before any repro, it's recommended to enable "Operational" channel to get the most of logs.
TraceLogging
<TBD>
Registry Key
These locations contain the latest Assigned Access Configuration:
HKLM\SOFTWARE\Microsoft\Windows\AssignedAccessConfiguration
HKLM\SOFTWARE\Microsoft\Windows\AssignedAccessCsp
These locations contain the latest "evaluated" configuration for each sign-in user:
"HKCU\SOFTWARE\Microsoft\Windows\AssignedAccessConfiguration" (If it doesn't exist, it means no Assigned Access to be enforced for this user.)
-->