Monday, June 29, 2020

Getting started with REST API for WVD ARM (Spring) release, and sharing my GitHub examples!


The REST API reference for WVD ARM (Spring Update) was released publicly last week! Great news, as this allows us to interact with the WVD service by using REST API. This article covers guidance on how to get started with REST API for Windows Virtual Desktop.
The landing page for the WVD REST API reference can be found here and contains detailed information about the various REST operations to interact with the WVD service. Currently, the following REST Operation Groups are available for WVD.


What I really like about the REST API documentation on is that it allows you to test all the REST API code right from within your browser. For example, open the Hostpool page and click on Try It and log on with you Admin account that you use to manage Azure and WVD.

Now you can simply provide the Hostpool name and ResourceGroup and click Run.

This will output the detailed information about the Hostpool right from within your browser as shown below! This allows us to receive a JSON formatted output with all the parameters and values. Very helpful a quick reverse engineering step, because this allows us to get great insights in what we can specify in REST API PUT actions.

WVD REST API via PowerShell

Using REST API for WVD Spring (ARM) release, we’re able to Get, Create, Update and Delete the various WVD components similar to how we are able to manage them using PowerShell and Management GUI in the Azure Portal. REST API is great for repetitive tasks and automation!
I created and shared a PowerShell script on GitHub that contains functions and examples to interact with the WVD REST API interface. In this article I will cover how you can use the steps in the PowerShell script to get a Jump Start with REST API.
First we need an account or App Registration that has permissions to performs the actions on the WVD components in Azure. In my example, I created a dedicated App Registration for REST API as shown below. Simply create a new App Registration and once completed, create a new Secret and make sure you store both the App ID as well as the App Secret. And finally, use Azure RBAC to provide the App with permissions on the Resource Groups where your WVD resources are located (or will be created). In my example I provided the App with Contributor permissions on the WVD Resource Group I’m using.

GitHub Sample Code — retrieving an Hostpool

Once we have the App registration configured, we can dive into the REST API. In my case I’m using PowerShell. The first thing we need to do is set a couple of variables related to our Azure Environment and the App Registration we just created.

Next, we create a new API token for our App Registration using Invoke-RestMethod. We pass this API Token later on when communicating with the WVD REST API interface.

And finally, we construct a API Header containing the token type (Bearer), the token itself and the content-type which we set to “application/json”. Important note, later on in this article, we’ll will also be using another content-type.

If all goes well, the header should look something like below. We are now ready to use the REST API module for WVD, and when communicating, we’ll use the created header.

In my PowerShell script I have created 8 PowerShell functions as of right now. These 8 functions are able to get and create a WVD Hostpool, AppGroup, Workspace and Published Apps. Let’s take retrieving a Hostpool as the first example. The function contains all the info that is needed to launch the invoke-restmethod command and also constructs the URL that is needed.

This function assumes that $apiheader already contains a valid REST API header, as created based on the previous step. The function takes 3 basic parameters that it needs to retrieve the Hostpool which are the Azure Subscription ID, the ResourceGroup where the Hostpool resides and the name of the Host Pool. Here is an example of how to call the function.

The function returns the full output of the Invoke-RestMethod which, in the example above, we captured into the variable $WVDHostPool.

We can of course easily output and work with the values by accessing them like below.

The properties attribute is the most interesting as it contains all of the details of the WVD Hostpool that we also have access to via PowerShell and the Azure Portal. Below is the output in a more structured way.

GitHub Sample Code — creating a Hostpool

Let’s now take a look at creating a WVD object using REST API. The PowerShell script already contains ready to launch functions for creating Workspaces, Hostpools, AppGroups and Published Apps so again let’s take the Hostpool as an example.
Below is the function taken from the script. Similar to retrieving a Hostpool as we did in the previous example, this function also takes the Azure Subscription ID, the ResourceGroup and the name of the Host Pool as parameters.

With the creation however we also need to pass the additional settings, stored in the properties attribute. If you recall from the Get-WVDHostpool function, the properties attribute is of type JSON. This means we also need to provide the Hostpool properties in a JSON format as well. To make life easy I have already added the JSON code to the PowerShell script. Below is what this looks like

As you can see we specified mandatory properties like the e.g. location, name et cetera. On top of that we also added custom RDP properties to enable a couple of redirection settings. Similar to how we called the Get-WVDHostpool we also call the New-WVDHostpool and pass the parameter including the body with the properties as shown below.

And just like that we have created a new Hostpool in WVD Spring (ARM) release, including the properties we specified!

Up until now we have covered the scenarios to both get and create a WVD Hostpool via REST API. The get and create of Workspaces and AppGroups is very similar, check out the PowerShell Script on GitHub for more information.

GitHub Sample Code — retrieving Published Apps

Let’s change gears and cover dealing with WVD published applications (RemoteApp) via REST API! The PowerShell scripts contains the function Get-WVDApps. This function takes the Azure Subscription ID, the ResourceGroup and the name of the AppGroup as parameters.

Similar to the other functions we’ve covered we can run the function as shown below.

This function gets all published RemoteApps for the specified AppGroup and, in this example, shows the friendly name ,file path, icon path and commandline setting. The output looks like below. Of course other properties can be added to the select statement as needed.

GitHub Sample Code — Creating Published Apps

As another example scenario, let’s add Outlook as a Published App to this Appgroup. For adding a new application to an existing AppGroup I have create the function new-WVDApp. This function takes the parameters Azure Subscription ID, ResourceGroupName, AppGroup, Properties (stored inside the body) and the App Name.

IMPORTANT NOTE: The Invoke-RestMethod for Published Apps needs using a different API header! This is because it needs utf-8 to be able to parse all of the properties including escape characters. I created a second API header for this purpose in the script which sets the Content-Type to “application/json; charset=utf-8”

To publish Outlook as a new application we again need to construct a JSON containing all of the parameters as shown below.

Some of the parameters are mandatory, so make sure you specify at least those. Below is the end result, Outlook is published as a new RemoteApp inside the AppGroup we specified containing the properties we provided!

This concludes this article. To reiterate, we covered the REST API interface to communicate with Windows Virtual Desktop. We used the REST API interface to create and retrieve WVD ARM (Spring) release Objects in an automated way! Here is the a direct link to my GitHub page where I shared all the sample code :

- - happy coding 😎

Friday, June 19, 2020

New GitHub Script: Automating the transformation of MSIX packages into MSIX app attach, ready for WVD!


Last week I published an article on using MSIX app attach to deliver Google SketchUp to a GPU powered Desktop running in WVD. In that article I also touched on the steps you need to take to transform an MSIX package into an MSIX app attach (vhd) package. As explained in that article as well, the MSIX source can be a native MSIX package delivered by an ISV / application vendor or the output from the MSIX packaging tool. For both scenarios the steps of transforming an MSIX into MSIX app attach are the same. There is a great article on Microsoft Docs that described the manual steps needed. I decided to automate those steps into a single PowerShell script and share it on GitHub!
I’m sharing a PowerShell script on GitHub that automates the transformation of MSIX packages into MSIX app attach, ready to use within Windows Virtual Desktop or on any other Windows 10 Build 2004!
Important note since I get this question a lot: I’m using WVD as the destination environment for the MSIX app attach. However, WVD is not a requirement for MSIX app attach at all and neither is hosting the destination VM in Azure! MSIX app attach can be used on any Windows 10 2004 build (and up). When you are using Windows 10 Enterprise it can be hosted anywhere and can even be a physical device. When Windows 10 Enterprise Multi-Session is used, it has be hosted on Azure through WVD.

Variables you can specify

The PowerShell script takes the parameters as shown below. I used a Google Chrome MSIX package that was the end result of the MSIX packing tool as an example to provide you with some sample values.
First of all you provide the information (folder and file) where the source MSIX is located, in this case I’m using a local folder on my MSIX Transformation VM. Next you provide the maximum size of the MSIX app attach (dynamic vhd) disk. Make sure you have enough room to store the extracted MSIX package files. Then provide a label, this label will be set on the vhd disk to allow you to easily distinguish multiple attached disks later on. Next you can provide the name of the root folder on the disk. As explained in my previous article, a root folder is mandatory for MSIX to work. Then provide the location where msixmgr is installed, this tool is used to extract the MSIX into the root folder on the vhd disk we’ll be creating. Make sure you point to the location where msixmgr.exe, applyacls.dll et cetera reside. The container extension variable can be kept default.

Requirements that need to be in place

Do note that the machine that you run this script on needs to have access to the PowerShell Cmdlets that work with VHD files (Mount-VHD, Dismount-VHD et cetera) which are part of the hyper-v module. The script assumes that this module is and the msixmgr tool have been installed, it does not check for that requirement (yet).
Here is a list of the steps that the PowerShell script performs:
  • Create a new VHD file in the source location specified and configure it with the maximum disk size specified
  • Mount the created VHD
  • Initialize the created disk
  • Create a partition on the disk
  • Create the MSIX root folder on the Mounted Disk
  • Extract the specified MSIX package into the mounted disk (using msixmgr)
  • Grab and output the Volume ID and Package Name to allow for easy copying. These values are needed later for the MSIX app attach Staging & Registering steps.
  • Dismount the VHD

Transformation script in action!

Let’s see the script in action! Below is my starting point. I have several MSIX packages that have previously been transformed from msi/exe to MSIX using the MSIX packaging tool. I have the script in this folder as well and the hyper-v module as well as the msixmgr are installed.
For this example I want to transform the Google Chrome package into MSIX app attach, so I specify the following parameters.
In my case the entire transformation of Google Chrome MSIX towards MSIX app attach only took 32 seconds! Below is what the output looks like. The script also outputs the Volume ID and Package name which allows for easy copying because they are needed for the MSIX app attach Staging & Registering steps later.
Here is the end result, a Google Chrome MSIX app attach (.vhd) file ready to go!

Test drive the end result

It’s now time to test-drive the vhd file to see if we can attach it to a user session and actually use the application. As explained in my previous article, MSIX app attach consists of 4 different steps Staging, Registering, De-Registering, De-Staging and Microsoft provides sample scripts for these 4 steps. To reiterate, here is an explanation of the terminology again.
So, the next step is to place the created .VHD on a Share (File Server of Azure Files) that is accessible by the client (in my case a Windows 10 Enterprise Multi-Session via WVD Spring 2020 Update). In my case, I added it as a 3rd package in the MSIX app attach share.
Now we can test the first MSIX app attach step, Staging. My Transformation script outputs the VolumeGuid as well as the package name, paste those values in the Stage script and also enter the location of the vhd hosted on the app attach share, as well as the parent folder that was used. Running the scripts mounts the vhd and creates the junction point to have Windows “think” a MSIX was extracted in C:\Program Files\WindowsApps.
The staging step only takes a second to complete, and here is the result, a mounted disk
And a junction point towards the disk
Now that Staging is complete, we can Register the application for the end user. Again, simply update the package name variable and run the Register script.
And here is the end result! Google Chrome is not installed locally, but it is available in the start menu using MSIX app attach and is running in the user session!

Final notes and download!

We are of course running PowerShell CmdLets to Stage and Register MSIX app attach applications. Under production circumstances (when MSIX app attach comes out of public preview), you would run the staging part during the machine boot (e.g. via a Computer GPO) and the registering part during user login (e.g. via a User GPO setting). In the future it is Microsoft’s plan to further integrate MSIX app attach into the WVD Service. The diagram below shows the MSIX app attach proposed milestones.
And finally, here is a link to the full script on GitHub, and as always if you have suggestions for the script feel free to send in a pull request or reach out to me directly!
— Happy Transforming!