Windows Virtual Desktop Script Integration

Windows Virtual Desktop (WVD) is a desktop and app virtualization service that runs in the cloud. It’s a service from Microsoft Azure that brokers users to desktops or applications from anywhere in the world. With these scripts, you don't have to switch between consoles to manage your WVD configuration.

ControlUp has developed a series of scripts that natively integrate into the ControlUp console, allowing you to manage your WVD session hosts and host pools, and all from a single pane of glass.

You don't have to log onto the Azure portal and can manage these resources directly from the ControlUp console. Using ControlUp, you can perform actions like setting a maximum session limit on the host pool, getting Azure image information, or sending a message to a user through the WVD service.

To run the ControlUp Script Actions for WVD, you must prepare both Azure and your ControlUp environment. Perform these procedures as described in this article:

  1. Configure Azure App Registration and Service Principal Object for ControlUp Script Actions. Create an Azure user with the necessary role and permissions to enable the integration.
  2. Synchronize Your ControlUp Organization Tree with Your WVD Directory. (Optional) Sets up synchronization so that your ControlUp organization tree reflects your WVD directory. This is an optional advanced step that should be done before the next step but is not mandatory for the integration to work. 
  3. Configure Your ControlUp Console to Monitor and Manage Your WVD Environment

Once the integration is complete, you’ll be able to:

  • Run the script actions against your WVD environment from your ControlUp console.
  • Configure the load balancing algorithm in real-time.
  • Create triggers for automation to change in response to metrics such as the number of users, CPU load, or nearly anything else.

Part I - Configure Azure App Registration and Service Principal Object for ControlUp Script Actions

To use the script actions, a Service Principal account must be created and configured in Azure. This enables running PowerShell scripts against WVD in Azure. The WVD Script Actions use an Azure Service Principal to connect to Azure and run the script. This way, the script actions do not have to start with a popup window that asks for your Azure Credentials.

Note: The steps here are based on the latest Azure implementation dated 22 July 2020. As this is third-party software, we cannot guarantee the specific field names and steps but are giving you the most updated information as of the date we are publishing this article.

Create a Service Principal Account in Azure Active Directory

To create a Service Principal account in Azure Active Directory, you have to create a new registration and secret:

  1. Log onto the Azure portal and use the hamburger menu to navigate to Azure Active Directory > App Registrations. Click New Registration.
  2. Give your account a meaningful name.
  3. Select Accounts in this organization's directory only. Click Register.
  4. Take note of the Application (client) ID and the Directory (tenant) ID information as they are needed in the next procedure for configuring ControlUp.
  5. Click Certificate & secrets to create a secret and click New client secret.
  6. In the Description field, give a meaningful description (i.e. ControlUp secret), select from the Expires options, and click Add.
  7. Copy the secret value to a password manager or temporary file. This is the only time it is displayed and can be copied from the Azure portal. If you don't copy this secret value, you will have to delete this secret and create a new one to ensure you have a valid secret for authentication.

Assign the Service Principal the required permissions in the Azure AD and for your Azure Subscription

To ensure the Script Actions can retrieve the assigned WVD resources for a user, the Service Principal account must be assigned a specific role in the Azure Active Directory.

  1. Log onto the Azure portal and use the hamburger menu to navigate to Azure Active Directory > Roles and administrators.
  2. Use the filter to find the Privileged role administrator.
  3. Click Add assignments.
  4. Use the Search filter to search for the ControlUp Service Principal account you just created. Select it and click Add to assign the role to this account.

In addition to the Azure Active Directory, the Service Principal account must also be assigned a specific role for your Azure Subscription.

  1. Log onto the Azure portal and use the hamburger menu to navigate to Subscriptions > <your subscription name> > Access Control (IAM).
  2. Click Add and select Add role assignment
  3. Under Role, select Contributor, and under Selected members, select the ControlUp Service Principal you just created. 
  4. Click Save to assign this role.

Part II - Synchronize your ControlUp organization tree with your WVD directory (optional)

This process is optional and requires some advanced procedures, along with several synchronization scripts that you download from our GitHub repository. It is performed primarily on the ControlUp monitor server and is not mandatory for the integration to work. If you are currently not yet in production with your WVD environment, you can easily skip this whole step and go here.  


  • A ControlUp monitor server
  • The following PowerShell modules installed on the ControlUp monitor server:
    • Az.Accounts - from Microsoft
    • Az.DesktopVirtualization - from Microsoft
    • ControlUp.PowerShell.User - installed when you add a ControlUp monitor
  • An Azure Service Principal with sufficient permissions to manage WVD (AppID, DirID & secret) - created in Part I
  • The following WVD synchronization scripts from our ControlUp GitHub repository in the Environment_Synchronization_Scrips folder.
    • WVD_Sync.ps1
    • WVD_Functions.ps1
    • Build_CUTree.ps1
    • Store-AzPSCredentials.ps1

Prepare the ControlUp monitor server

To set up the synchronization, prepare the ControlUp monitor server with the proper PowerShell modules and the WVD synchronization scripts.

  1. To set up the monitor server, log onto the ControlUp monitor server with an account that has Administrator privileges.
  2. Open a PowerShell prompt with elevated privileges.
  3. Run the following commands:
    1. Install-Module Az.Accounts -Scope AllUsers
    2. Install-Module Az.DesktopVirtualization -Scope AllUsers
  4. Confirm you have the latest ControlUp PowerShell modules with Get-CUFolders. For details, see ControlUp Powershell Commands.
  5. Download and extract the Environment_Synchronization_Scripts folder from our GitHub repository onto your ControlUp Monitor server.
  6. To store the Service Principal credentials in an encrypted file, so it can be used by the script actions (or other PowerShell scripts that need a connection to Azure), run this script:
  7. Enter the required information. 
  8. Start the WVD_Sync.ps1 script with the folder path of the directory you want to sync into ControlUp and with the -Preview parameter to see which commands it outputs.  Ensure the folder path parameter ends with \WVD. For example:
    PS C:\Sync> . .\WVD_Sync.ps1 -folderPath "VDI_and_SBC\WVD" 
    -Delete -LogFile C:\swinst\WVD2020-07-22.log -Preview
  9. Once you are comfortable with the proposed changes in the output, remove the -Preview parameter to commit the changes to the organizational tree in the ControlUp console.

Optional - Set up a scheduled task to periodically perform the synchronization

You can configure a Windows task to periodically run these scripts so the organizational tree in your ControlUp console is synchronized with your WVD.

Note: The steps here were run on a Windows Server 2019 machine running the ControlUp monitor. Keep in mind that the Az.DesktopVirtualization PowerShell module requires PowerShell version 5.1 or up and .NET Framework version 4.7.2 or later. These are the most updated steps for these versions as of the date we are publishing this article.

  1. Open the Windows Task Scheduler on the ControlUp monitor server machine and select Create Task...
  2. In the General tab, give the task a name, such as Synchronize WVD to ControlUp.
  3. Under Security options:
    1. Check that the user account is the same as the one you used to run the Set-AzSPCredentials.ps1 script.
      Or you can rerun the credential script under the account you want to use for this periodic synchronization.
    2. Select the option to Run whether user is logged on or not. 
  4. In the Triggers tab, create a new trigger and set the schedule for running this task.
  5. In the Actions tab, create a new action with the following options and parameters:
    Action Start a program
    Program/script powershell.exe
    Add arguments (optional) -file C:\Sync\WVD_Sync.ps1 -folderPath "VDI_and_SBC\WVD" -Delete -LogFile C:\swinst\WVDSync.log
    Start in (optional) C:\Sync

  6. Run the scheduled task and review the log file to validate the operation.

Part III - Configure the ControlUp Console to manage Windows Virtual Desktop (WVD) resources

This section configures the integration between the ControlUp Console and your WVD environment so you can monitor and manage your WVD resources directly from ControlUp.

Note: If you chose not to perform Part II, you can perform this configuration but you must manually name a folder in your ControlUp organization tree: \WVD.


WVD is a cloud service so there are some prerequisites that must be installed alongside your ControlUp Console to activate these management actions. 

  • The following PowerShell modules installed on the console server and the machine running the script actions (if it's not the console):
    • Az.Account
    • Az.Resources
    • Az.DesktopVirtualization
    • AzureAD
      Note: The modules can be installed from the PowerShell Gallery using the Install-Module cmdlet. Administrator rights are required to install modules. (In Windows 10, you can install the modules in the scope of the current user which works for virtual machines if you don't have local admin permissions.)
  • PowerShell session is set to use at least TLS1.2 for the communication to the PowerShell Gallery when installing the modules.
  • An Azure Service Principal with sufficient permissions to manage WVD with the required Service Principal properties (AppId, DirId, and Secret) - created in Part I
  • .NetFramework 4.7.2 - required for the Az PowerShell Module

Run the WVD Set Azure Service Principal Credentials script action

To run the different WVD script actions that are available to ControlUp, you must first run the WVD Store Azure Service Principal Credentials script. This script stores the required Service Principal information in a local encrypted file which is linked to the username and machine running the script.

For details on using script-based actions in ControlUp, you can read this article.

In your ControlUp Console in machine view, right-click a machine (recommended under the \WVD folder) and select Script Actions > WVD Store Azure Service Principal Credentials


When you run this script action, you are asked for the required Azure Service Principal information in this popup window: 


Enter the information that you previously stored for the Service Principal.

This information is stored (locally) on the machine running the script in an XML file with an encrypted app secret. To validate that the correct secret appears, access the XML and check that the UserName and Value fields are not empty: 

XMLcheck.jpgThis stored Service Principal information is used by the other WVD Script Actions, such as the WVD Get Hostpool.




1-on-1 Demo
Schedule now
Price Quote
Get it now
Need a Script?
Get it here
Powered by Zendesk