Migrate/upgrade RDS Deployment to new Connection Broker, even on Azure, using my new Powershell Module


[UPDATE 2019-03-10] I did an update on the module introducing some new features. You should read the update first before continuing here: ExportImportRdsDeployment module has been updated and it has Backup functionalities now

As documented in this article, the first step to upgrade your Windows Server 2012R2 Remote Desktop Services (RDS) deployment to Windows Server 2016 is upgrading your Connection Broker.
This can be done using an in-place upgrade, but this not always ideal:

  • The in-place upgrade takes quite some time depending on various factors, like hardware, installed software, etc.
  • The upgrade can fail, causing you to rollback and increases downtime
  • There are numerous articles that discourage an in-place upgrade due to performance issues, legacy application problems, …
  • On Azure, an in-place upgrade is not supported! So you cannot upgrade your Windows there.

ASPEX has a customer that was using a Windows 2012R2 RDS deployment and we told him about the HTML5 webclient that was in Public Preview at that time, which would be a great asset to the end users.
The big problem: the HTML5 webclient requires a 2016 RDS Deployment.
We suggested to upgrade the RDS deployment from 2012R2 to 2016, but the customer requested a minimal downtime and a phased migration.
This ruled out an in-place upgrade, so I started coding…

The solution

I created a Powershell module that contains 4 functions. Each function is a step in the process to migrate your RDS deployment from one Connection Broker to another.
The module will allow you to export your existing Session Collections and RD Servers with all configuration settings, and remove them from the old Connection Broker.
Then you can import everything back into the new Deployment, connecting the RD Servers to the new Connection Broker and recreate the Collections.

There are several scenario’s where you can use this module:

  1. Migrate from one Connection Broker to another
  2. Upgrade from a 2012R2 to 2016/2019 RDS deployment
  3. etc

The module has been made available in the Powershell Gallery, so you can easily install and use it on any Windows Server.

The module will only migrate these RD roles: RD Gateway, RD Web Access & RD Session Host
The other roles (RD Connection Broker & RD Licensing Server) should already be installed on the new Connection Broker


Only Session-based Desktop Deployments (Session Collections and Personal Session Desktops) are currently supported!
If you have a Virtual machine-based desktop deployment (using a Virtualization Host), you should not use this Module!

You should always make sure you have a backup of your Connection Broker config before you start.
Testing the module on your Dev environment is always a best-practice.


The overview

Deployment on the old Connection Broker

This is how my test deployment looks like:

1x server as old Connection Broker & Licensing: MICHA-P-RDB-001
1x server as Gateway & Web Access: 2019-TEST-RDG1
6x servers as Session Hosts: MICHA-P-RDH-001 ==> 006
Old CB Deployment Overview ServerManager

I have 3 Session Collections (1 with Remote Apps and 2 with Remote Desktops) and 1 Personal Session Desktop Collection.
These are all divided over the available Session Hosts, as you can see in the screenshots below.
Old CB Collections Overview ServerManager Old CB RemoteApp Collection Overview ServerManager Old CB Collections Overview Powershell

New Connection Broker

1x server as new Connection Broker & Licensing: 2019-TEST-CB
I only installed the 2 roles on the 2019-TEST-CB machine.
It is recommended to install the Licensing role on the new Connection Broker server.
New CB Installed Roles  New CB Deployment Overview ServerManagerNew CB Deployment Overview Powershell


For this blog, I’m going export the Session Collections, Sessions Hosts, Gateway and Web Access servers from MICHA-P-RDB-001 to 2019-TEST-CB

The migration


To install the Module, you simply run these 2 commands:

 Old CB Install & Import Module New CB Install & Import Module

The module is uploaded to the Powershell Gallery, therefor you can easily install it, and it is signed using a Code Signing certificate.
If you get a message regarding the Nuget provider, you should confirm to install
the module


Install Module

Install the module on the old Connection Broker:


First step is to export the Session Collections. The module will export the collections to a XMLfile, so it can be easily migrated to the new Connection Broker.
You export the collections using this command:

You must specify the ConnectionBroker and optionally the XmlFile. And if you add -Verbose, you will get detailed steps in the progress
Old CB Export Collections Start

When finished, you will get the location of the XMLFile (default: in C:\temp, unless specified otherwise).
Old CB Export Collections Finished


Next step is to export the Deployment (including the servers).
You export the deployment using this command:

You must specify the ConnectionBroker and optionally the XmlFile. And if you add -Verbose, you will get detailed steps in the progress
Note: You have to confirm that you exported the Session Collections before running this step.
Old CB Export Deployment Start

When finished, you will get the location of the XMLFile (default: in C:\temp, unless specified otherwise).
The error message (as displayed below) is default behavior due to the removal of the Gateway Role from the deployment.
Old CB Export Deployment Finished

Export Files

When both exports are completed, you will find the XMLfiles in the export location.
These files should be used when importing to the new Connection Broker.
Old CB Export XmlFiles


Install Module

Install the module on the new Connection Broker

Import Files

Copy the XMLfiles to the new Connection Broker, unless exported to a shared network location.
You also need the certificate(s) for all 4 roles in the deployment: RDGateway, RDWebAccess, RDPublishing & RDRedirector
In this test migration, I used a wildcard certificate for all 4 roles.
I placed all files in the C:\temp folder
New CB Xml & Pfx Files


First step is to import the Deployment (including the servers).
You import the deployment using these commands:

You must specify the ConnectionBroker and the XmlFile, and the 4 certificate locations and passwords. And if you add -Verbose, you will get detailed steps in the progress.
New CB Import Deployment Start

When finished, you will get an summary of the imported deployment.
New CB Import Deployment Finished


Next step is to import the Session Collections.
You import the collections using this command:

You must specify the ConnectionBroker and the XmlFile. And if you add -Verbose, you will get detailed steps in the progress.
New CB Import Collections Start

When finished, you will see all Collections that are imported, including the published RemoteApps.
New CB Import Collections Finished

Overview after the migration

When you review the Server Manager, you will see that the entire Deployment is migrated.
New CB Deployment Overview ServerManager After Import

Also the Collections are completely migrated.
New CB Collections Overview ServerManager

And the Personal Session Desktop Collection is also available again.
New CB Collections Overview Powershell


Using this module, you are able to migrate your entire deployment in a controlled manner, on any platform (like Azure) and faster than performing an in-place upgrade.

You also completed step 1 and 2 from the guide in this article.

You can simple follow the guide further, or you can install your new Session Hosts, Gateway(s) and Web Access servers, and replace these in the new Deployment.


  1. Does this script work when the connection broker is already set to HA? I’ve been trying to migrate using the MS doc, but I’ve been unsuccessful.

    1. Hi Kirt,

      Yes, this should work even if the Connection Broker is already in HA. This script will migrate only your setup (Gateway & Certificate setup) and collections to a new Connection Broker (which you will need to setup before the migration), so the old Connection Broker setup does not matter.

      Let me know if you have any other questions or suggestions.

      Kind regards,

    1. Hi Casper,

      You can install the module on the new broker, or execute the cmdlets from a remote server, specifying the new connection broker name in the parameters.
      Only requirement is that the RDS-cmdlets are installed on the server where you execute the module.

      Kind regards,

  2. Great article…we have an existing WDI based broker pair in Domain A that we have migrated to Domain B and of course it is non-functional now.

    Would this ps support the config import if the domain membership changes on the new brokers?

    Thanks so much.

  3. Great article, thank you for your work! I`ve got one question. I have a 2012r2 and an 2016 rds environment, parallel and separate installed. And now, i want to migrate first the 2012r2 to the 2016 and after that, the the 2016 to a new 2019 rds environment. Can i migrate the 2012r2 environment to the 2016 without losing the actual 2016 rds configuration with this script? Or is that possible only to an “empty” 2016 installation? Best regards and have a nice day

Leave a Reply