Migration from Fall 2019 to Spring update 2020




The PowerShell cmdlets named in the article aren’t available yet. We’ll update this article when we publish the cmdlets.

The Fall 2019 release of Windows Virtual Desktop provided PowerShell cmdlets and REST APIs to create a service environment. It also created service objects. When we talk about "objects" in the service environment, we mean objects Windows Virtual Desktop creates, such as tenants, host pools, application groups, and session hosts.

The one drawback of the Fall 2019 version of Windows Virtual Desktop is that it isn't automatically Azure integrated. This means that objects you create with the Fall 2019 release aren't automatically managed by the Azure portal, as they aren't connected to your Azure subscription.

The Spring 2020 update marks a shift in the Windows Virtual Desktop service towards full Azure integration. This means that any objects created with the Spring 2020 update are automatically managed by the Azure portal. In the future, all service objects will be integrated with the Azure service and the customer's Azure account.

This article will explain why you should migrate to the latest update of Windows Virtual Desktop, and how to do it.

Why migrate?

Major updates can be inconvenient, especially ones you have to do manually, so let’s see why migration couldn’t be done automatically:

  • Existing service objects made with the Fall 2019 release don't have any representation in Azure. Their scope doesn't extend beyond the Windows Virtual Desktop service.
  • When the Spring 2020 update became a first-party Azure service, the service's application ID changed. New Azure objects with Windows Virtual Desktop can’t be created, unless authenticated with the new application ID.

Let’s go through why migration to the Spring 2020 update is important. With the Spring 2020 update, you can:

  • Manage Windows Virtual Desktop through the Azure Portal.
  • Assign Azure Active Directory (AD) user groups to application groups.
  • Use the improved Log Analytics feature to troubleshoot your deployment.

Our team is committed to making the migration process as quick and easy as possible, so we’ve made sure your users can stay on their Windows Virtual Desktop sessions during the migration process.

Prepare for migration

Before you start the migration, make sure you have the following things:

  1. An Azure subscription where you’ll create new Azure service objects
  2. You need to be assigned the Contributor role to create Azure objects on your subscription, and the User Access Administrator role to assign users to application groups.
  3. You need at least RDS Contributor permissions on an RDS tenant or the specific host pools you’re migrating.
  4. The latest version of the PowerShell module for the Fall 2019 release.


Migration currently only creates service objects in the US geography. You can't migrate the objects to a different geography with the tools currently available. When the service supports creating objects in other geographies, follow the process in “Migrate to a new geography.”

Migrate using service-provided cmdlets

Migration will be done using the PowerShell cmdlets.

  1. Run Start-RdsHostPoolMigration.
  2. Input the following information:
  • Specify whether you're migrating all host pools within a tenant or just a single host pool.
  • Specify a user assignment mode for the existing user assignments:

Copy mode copies all user assignments from Fall 2019 app groups to Spring 2020 app groups, leaving the existing user assignments as-is. Users will be able to see feeds for both versions on their clients. Move mode copies all user assignments from Fall 2019 app groups to Spring 2020 app groups, then deletes the existing user assignments on Fall 2019 release app groups. Users will only be able to see the feed from the Spring 2020 app groups on their clients. None mode doesn't change the user assignments. You have the option to assign users or user groups to app groups with the tools provided by the Spring 2020 update, such as the Azure portal, PowerShell cmdlets or API.

Note: You can choose to output the topology mapping between the two sets of resources, without performing the actual migration.

Once you've entered the information, wait about 15 minutes for the service objects to be created in the subscription and resource groups you specified. If you copied or moved user assignments, that will take some extra time for the assignments to complete.

Once authentication is done, you should have the following:

  • Azure service objects for the tenant or host pool you specified.
  • Based on your input, users might have also been published to the newly created app groups.
  • Virtual machines will be available in both existing and new host pools to avoid user downtime during the migration process. This lets users connect to the same user session.
  1. Next, make sure you have all RBAC permissions and diagnostic setup for the new Azure service objects. Once initial user connections are validated, you can choose to also publish the app group to more users or user groups.
  2. Finally, run Complete-RdsHostPoolMigration to finish migration for the tenant or host pool you're moving into the Spring 2020 update. This will delete all service objects created by the Fall 2019 release. You'll be left with just the new Azure objects and users will only be able to see the feed for the newly created app groups on their clients.


If you aren't ready to finalize the migration and want to wait until a later date to migrate your Fall 2019 service objects, run Revert-RdsHostPoolMigration and your newly created service objects will be deleted. Users will only see the feed for the Fall 2019 version in their clients. If you chose Move in step 1, you won’t be able to revert the user assignment, which means you’ll have to republish the app groups to users.


If you don't want to get rid of your Fall 2019 service objects, you can run Set-RdsHostPoolHidden instead. This will hide the Fall 2019 user feed and the Fall 2019 service objects instead of deleting them. This gives you the option of reverting later if you choose to but operate as if you have completed the migration.


Migrate to a new geography

  1. The current migration process only migrates service objects to US geography. If your organization needs to store metadata in a different geography (when the service allows objects to be created in the geography of your choice), here's how to migrate manually: Create the whole environment using the Azure portal by following the instructions in Create a host pool with the Azure portal.
  2. If you want to repurpose the virtual machines you currently use, you can manually register them to the newly created host pool by following the instructions in Register the virtual machines to the Windows Virtual Desktop host pool.
  3. Create new RemoteApp app groups.
  4. Publish users or user groups to the new desktop and RemoteApp app groups.

To avoid or minimize downtime, register existing session hosts in small increments to the ARM-integrated host pool for the Spring 2020 update and slowly migrate users over to the new ARM-integrated app groups.

Continued support for Fall 2019 release

We'll continue supporting and maintaining the environment and tools for the Fall 2019 release for now. However, new features will only be added to the Spring 2020 update. To keep up with the latest Azure features in Windows Virtual Desktop, we recommend you migrate to the Spring 2020 update as soon as possible. If you have any feature suggestions, submit your idea along with your scenario on our UserVoice forum at https:///aka.ms/wvdfbk.

23 Replies

@Pavithra Thiruvengadam 

I tried manually migrating session hosts to a new host pool last week and it was incomplete.

Although it could be used as Windows Virutal Desktop, the resources of the host pool were not sufficient.


ARM Parmeter:vmTemplate and so on ware blank.As a result, I could not add session hosts from Azure portal.




Is it possible to modify a host pool resource?

If I choose to only migrate a single host pool as a test, will running Complete-RdsHostPoolMigration delete all service objects created with the Fall 2019 release or just those associated with the host pool that was chosen for migration?


Is there a documented manual migration path that can be used to test before the PowerShell cmdlets are available?


Thank you.

@Yuki398 This has been fixed.

@Ed Stalcup If you choose to complete migration for only 1 hostpool, you just need to pass that hostpool as a parameter to the complete cmdlet and we will leave other hostpools as is.

@Pavithra Thiruvengadam 

Thanks for fixing.But, unfortunately, it didn't fix properly.

The input form for adding a session host is now displayed and this has been fixed.

However, there seems to be an error in input validation.

Is this a problem for my environment?


Error message

The value of deployment parameter 'vmInitialNumber' is null. Please specify the value or use the parameter reference. See https://aka.ms/resource-manager-parameter-files for details.


Could you give me the following info:
Was the hsotpool completely empty when you started the Add VM workflow?
Were you asked to fill out the VM Prefix before seeing this error?
Do you have VMs in the resource group with or without the prefix?

I validated the fix prior to deploying it (had 3 different scenarios) and I was able to successfully create VMs. The scenarios were all around adding VM to an empty hostpool or a hostpool with a previously failed VM creation (due to domain error, etc.). This info will give me more info to repro the issue.

@Pavithra Thiruvengadam 

> Was the hsotpool completely empty when you started the Add VM workflow?

No. There is one session host.

I tried to add more session hosts from the Azure portal after manually adding a session host to the host pool.


> Were you asked to fill out the VM Prefix before seeing this error?

I couldn't type the Basic Tab, but I had to type everything else as usual.


> Do you have VMs in the resource group with or without the prefix?

I've seen some patterns, but it doesn't seem that the resource group is empty or the name of the VM has anything to do with it.


My scenario

1. Create a host pool. (Desktop Application Group is automatically created)

2. Create a windows 10 VM from Marketplace.

3. Join the domain in windows 10, and install a wvd agent and fill the registration key.

4. Add session hosts from Azure Portal. The error occurred at this time.

@Pavithra Thiruvengadam 


I have the same issue.


If host pool is completely empty, this error did not occur.

Only when session hosts already exist in host pool, the error occurred.

I retried 5 minutes ago.
It seems that this issue is resolved.

@Pavithra Thiruvengadam 


Your recommendation to upgrade to WVD v2 ASAP, isn't v2 still in public preview?  Are you recommending upgrading production workloads?  Any idea when v2 will become GA?

@Jae_kwon When WVD ARM goes GA, you should start the migration process. Prior to that, you are welcome to try manual migration for test workloads.

@Pavithra Thiruvengadam can you confirm when the WVD Spring 2020 update will go GA.


Also will MS perform the migration from Fall 2019 to Spring 2020 as part of GA or will this be a manual task.



@Pavithra Thiruvengadam 

Hi Pavithra,

Thanks for the great info!  I have a question.  So I started w/ 2019 non-arm wvd.  It was only a test and I have just a few users kicking the tires to help us understand it.


Fast forward to now.  I've deployed the ARM version (2020) of wvd (again a test), and I'd like to steer users to it.  Question: How do I dump the 2019 wvd setup and replace it with my 2020 version?  I've looked around, but haven't seen anyway to do it.  Do you have any suggestions?




@Pavithra Thiruvengadam Now that the Spring update 2020 has gone GA when can we expect the powershell commandlets to go GA? 

Any news on when there will do a process to migrate from Fall to spring, I am currently have this setup in the fall 2019, but my team does not show the correct time in the calendar. I need to get this fix because it is a project that i am going on and it stop me from migrating more users @no-va 

@Pavithra ThiruvengadamAny update when we can expect the cmdlets to be released?

@Deofex , 


actually there are already tools available which help you migrating your Host Pools to the WVD ARM based version. Have you ever tried Marcel Meurers WVDAdmin? 


It offers a lot of options to help you manage WVD and we have implemented it in nearly every deployment so far. 


You can find the tool and documentation on his page here: https://blog.itprocloud.de/Windows-Virtual-Desktop-Admin/


Have a nice weekend! 


@Pavithra Thiruvengadam do you have an estimate for when the updated article with cmdlets will be provided? We have several Fall release WVDs with problems and need to get them updated to Spring release. Thank you!


@Jesse Vaught  No ETA, yet. What is stopping the custoemr from setting up a new environment in Azure portal and migrate the VMs (if its personal) or create new VMs (if its pooled)?