|
| 1 | +--- |
| 2 | +title: Migrate MSIX packages from MSIX app attach to app attach - Azure Virtual Desktop |
| 3 | +description: Learn how to migrate MSIX packages from MSIX app attach to app attach in Azure Virtual Desktop using a PowerShell script. |
| 4 | +ms.topic: how-to |
| 5 | +author: dknappettmsft |
| 6 | +ms.author: daknappe |
| 7 | +ms.date: 02/28/2024 |
| 8 | +--- |
| 9 | + |
| 10 | +# Migrate MSIX packages from MSIX app attach to app attach |
| 11 | + |
| 12 | +> [!IMPORTANT] |
| 13 | +> App attach is currently in PREVIEW. |
| 14 | +> See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability. |
| 15 | +
|
| 16 | +App attach (preview) improves the administrative and user experiences over MSIX app attach. If you use MSIX app attach, you can migrate your MSIX packages to app attach using a PowerShell script. |
| 17 | + |
| 18 | +The migration script can perform the following actions: |
| 19 | + |
| 20 | +- Creates a new app attach package object and can delete the original MSIX package object, if necessary. |
| 21 | + |
| 22 | +- Copy permissions from application groups associated with the host pool and MSIX package. |
| 23 | + |
| 24 | +- Copy the location and resource group of the host pool and MSIX package. |
| 25 | + |
| 26 | +- Log migration activity. |
| 27 | + |
| 28 | +## Prerequisites |
| 29 | + |
| 30 | +To use the migration script, you need: |
| 31 | + |
| 32 | +- A host pool configured as a validation environment, with at least one MSIX package added with MSIX app attach. |
| 33 | + |
| 34 | +- An Azure account with the [Desktop Virtualization Contributor](rbac.md#desktop-virtualization-contributor) Azure role-based access control (RBAC) role assigned on the host pool. |
| 35 | + |
| 36 | +- A local device with PowerShell. Make sure you have the latest versions of [Az PowerShell](/powershell/azure/install-azps-windows) and [Microsoft Graph PowerShell SDK](/powershell/microsoftgraph/installation) installed. Specifically, the following modules are required: |
| 37 | + |
| 38 | + - Az.DesktopVirtualization |
| 39 | + - Az.Accounts |
| 40 | + - Az.Resources |
| 41 | + - Microsoft.Graph.Authentication |
| 42 | + |
| 43 | +## Parameters |
| 44 | + |
| 45 | +Here are the parameters you can use with the migration script: |
| 46 | + |
| 47 | +| Parameter | Description | |
| 48 | +|--|--| |
| 49 | +| `MsixPackage` | The MSIX package object to migrate to an app attach object. This value can be passed in via pipeline. | |
| 50 | +| `PermissionSource` | Where to get permissions from for the new app attach object. Defaults to no permissions granted. The options are:<ul><li>`DAG`: the desktop application group associated with the host pool and MSIX package</li><li>`RAG`: one or more RemoteApp application groups associated with the host pool and MSIX package</li></ul>Both options grant permission to all users and groups with any permission that is scoped specifically to the application group. | |
| 51 | +| `HostPoolsForNewPackage` | Resource IDs of host pools to associate new app attach object with. Defaults to no host pools. Host pools must be in the same location as the app attach packages they're associated with. | |
| 52 | +| `TargetResourceGroupName` | Resource group to store the new app attach object. Defaults to resource group of host pool that the MSIX package is associated with. | |
| 53 | +| `Location` | Azure region to create new app attach object in. Defaults to location of host pool that the MSIX package is associated with. App attach packages have to be in the same location as the host pool they're associated with. | |
| 54 | +| `DeleteOrigin` | Delete source MSIX package after migration. | |
| 55 | +| `IsActive` | Enables the new app attach object. | |
| 56 | +| `DeactivateOrigin` | Disables source MSIX package object after migration. | |
| 57 | +| `PassThru` | Passes new app attach object through. `Passthru` returns the object for the created package. Use this value if you want to inspect it or pass it to another PowerShell command. | |
| 58 | +| `LogInJSON` | Write to the log file in JSON Format. | |
| 59 | +| `LogFilePath` | Path of the log file, defaults to `MsixMigration[Timestamp].log` in a temp folder, such as `C:\Users\%USERNAME%\AppData\Local\Temp\MsixMigration<DATETIME>.log`. The path for logging is written to the console when the script is run. | |
| 60 | + |
| 61 | +## Download and run the migration script |
| 62 | + |
| 63 | +Here's how to migrate MSIX packages from MSIX app attach to app attach. |
| 64 | + |
| 65 | +> [!IMPORTANT] |
| 66 | +> In the following examples, you'll need to change the `<placeholder>` values for your own. |
| 67 | +
|
| 68 | +1. Open a PowerShell prompt on your local device. |
| 69 | + |
| 70 | +1. Download the PowerShell script `Migrate-MsixPackagesToAppAttach.ps1` and unblock it by running the following commands: |
| 71 | + |
| 72 | + ```powershell |
| 73 | + $url = "https://raw.githubusercontent.com/Azure/RDS-Templates/master/msix-app-attach/MigrationScript/Migrate-MsixPackagesToAppAttach.ps1" |
| 74 | + $filename = $url.Split('/')[-1] |
| 75 | +
|
| 76 | + Invoke-WebRequest -Uri $url -OutFile $filename | Unblock-File |
| 77 | + ``` |
| 78 | + |
| 79 | +1. Import the required modules by running the following commands: |
| 80 | + |
| 81 | + ```powershell |
| 82 | + Import-Module Az.DesktopVirtualization |
| 83 | + Import-Module Az.Accounts |
| 84 | + Import-Module Az.Resources |
| 85 | + Import-Module Microsoft.Graph.Authentication |
| 86 | + ``` |
| 87 | + |
| 88 | +1. Connect to Azure by running the following command and following the prompts to sign in to your Azure account: |
| 89 | + |
| 90 | + ```powershell |
| 91 | + Connect-AzAccount |
| 92 | + ``` |
| 93 | + |
| 94 | +1. Connect to Microsoft Graph by running the following command: |
| 95 | + |
| 96 | + ```powershell |
| 97 | + Connect-MgGraph -Scopes "Group.Read.All" |
| 98 | + ``` |
| 99 | +
|
| 100 | +The following subsections contain some examples of how to use the migration script. Refer to the [parameters](#parameters) section for all the available parameters and a description of each parameter. |
| 101 | +
|
| 102 | +> [!TIP] |
| 103 | +> If you don't pass any parameters to the migration script, it has the following default behavior: |
| 104 | +> - No permissions are granted to the new app attach package. |
| 105 | +> - The new app attach package isn't associated with any host pools and is inactive. |
| 106 | +> - The new app attach package is created in the same resource group and location as the host pool. |
| 107 | +> - The original MSIX package is still active isn't disable or deleted. |
| 108 | +> - Log information is written to the default file path. |
| 109 | +
|
| 110 | +### Migrate a specific MSIX package added to a host pool and application group |
| 111 | +
|
| 112 | +Here's an example to migrate a specific MSIX package added to a host pool from MSIX app attach to app attach. This example: |
| 113 | +
|
| 114 | + - Migrates the MSIX package to the same resource group and location as the host pool. |
| 115 | + - Assigns the MSIX package in app attach to the same host pool and the same users as the RemoteApp application group source. |
| 116 | + - Leaves the existing MSIX package configuration in MSIX app attach **active** on the host pool. If you want to disable the MSIX package immediately, use the `-DeactivateOrigin` parameter. |
| 117 | + - Sets the new MSIX package configuration in app attach **inactive**. If you want to enable the MSIX package immediately, use the `-IsActive` parameter. |
| 118 | + - Writes log information to the default file path and format. |
| 119 | +
|
| 120 | +1. From the same PowerShell prompt, get a list of MSIX packages added to a host pool by running the following commands: |
| 121 | +
|
| 122 | + ```powershell |
| 123 | + $parameters = @{ |
| 124 | + HostPoolName = '<HostPoolName>' |
| 125 | + ResourceGroupName = '<ResourceGroupName>' |
| 126 | + } |
| 127 | + |
| 128 | + Get-AzWvdMsixPackage @parameters | Select-Object DisplayName, Name |
| 129 | + ``` |
| 130 | + |
| 131 | + The output is similar to the following output: |
| 132 | + |
| 133 | + ```output |
| 134 | + DisplayName Name |
| 135 | + ----------- ---- |
| 136 | + MyApp hp01/MyApp_1.0.0.0_neutral__abcdef123ghij |
| 137 | + ``` |
| 138 | + |
| 139 | +1. Find the MSIX package you want to migrate and use the value from the `Name` parameter in the previous output: |
| 140 | + |
| 141 | + ```powershell |
| 142 | + $parameters = @{ |
| 143 | + HostPoolName = '<HostPoolName>' |
| 144 | + ResourceGroupName = '<ResourceGroupName>' |
| 145 | + } |
| 146 | + |
| 147 | + $msixPackage = Get-AzWvdMsixPackage @parameters | ? Name -Match '<MSIXPackageName>' |
| 148 | + $hostPoolId = (Get-AzWvdHostPool @parameters).Id |
| 149 | + ``` |
| 150 | + |
| 151 | +1. Migrate the MSIX package by running the following commands: |
| 152 | + |
| 153 | + ```powershell |
| 154 | + $parameters = @{ |
| 155 | + PermissionSource = 'RAG' |
| 156 | + HostPoolsForNewPackage = $hostPoolId |
| 157 | + PassThru = $true |
| 158 | + } |
| 159 | +
|
| 160 | + $msixPackage | .\Migrate-MsixPackagesToAppAttach.ps1 @parameters |
| 161 | + ``` |
| 162 | + |
| 163 | +### Migrate all MSIX packages added to a host pool |
| 164 | + |
| 165 | +Here's an example to migrate all MSIX packages added to a host pool from MSIX app attach to app attach. This example: |
| 166 | + |
| 167 | + - Migrates MSIX packages to the same resource group and location. |
| 168 | + - Adds the new app attach packages to the same host pool. |
| 169 | + - Sets all app attach packages to active. |
| 170 | + - Sets all MSIX packages to inactive. |
| 171 | + - Copies permissions from the associated desktop application group. |
| 172 | + - Writes log information to a custom file path at `C:\MsixToAppAttach.log` in JSON format. |
| 173 | + |
| 174 | +1. From the same PowerShell prompt, get all MSIX packages added to a host pool and store them in a variable by running the following commands: |
| 175 | + |
| 176 | + ```powershell |
| 177 | + $parameters = @{ |
| 178 | + HostPoolName = '<HostPoolName>' |
| 179 | + ResourceGroupName = '<ResourceGroupName>' |
| 180 | + } |
| 181 | + |
| 182 | + $msixPackages = Get-AzWvdMsixPackage @parameters |
| 183 | + $hostPoolId = (Get-AzWvdHostPool @parameters).Id |
| 184 | + ``` |
| 185 | + |
| 186 | +1. Migrate the MSIX package by running the following commands: |
| 187 | + |
| 188 | + ```powershell |
| 189 | + $logFilePath = "C:\Temp\MsixToAppAttach.log" |
| 190 | + |
| 191 | + $parameters = @{ |
| 192 | + IsActive = $true |
| 193 | + DeactivateOrigin = $true |
| 194 | + PermissionSource = 'DAG' |
| 195 | + HostPoolsForNewPackage = $hostPoolId |
| 196 | + PassThru = $true |
| 197 | + LogInJSON = $true |
| 198 | + LogFilePath = $LogFilePath |
| 199 | + } |
| 200 | +
|
| 201 | + $msixPackages | .\Migrate-MsixPackagesToAppAttach.ps1 @parameters |
| 202 | + ``` |
0 commit comments