Product Documentation

Upgrade a deployment

Mar 27, 2018

Introduction

You can upgrade deployments to newer versions without having to first set up new machines or Sites; this is called an in-place upgrade. The following upgrade paths have been tested:

  • From Workspace Environment Management version 4.5 to the latest released (current) version
  • From Workspace Environment Management version 4.4 to the latest released (current) version

Tip

The Workspace Environment Management database, infrastructure service, and administration console must all be on the same version. If you need to roll-out Workspace Environment Management agents incrementally (for example, when upgrading), the use of agents which are no more than two versions older than the current release is supported but has not been tested.

The Workspace Environment Management components must be upgraded in the following order:

  1. Infrastructure services
  2. Database
  3. Administration console
  4. Agent

Step 1: Upgrade the infrastructure services

To upgrade the Workspace Environment Management infrastructure services, run the new Workspace Environment Management infrastructure services setup on your infrastructure server. The upgrade procedure is otherwise identical to the installation procedure.

Important

After you upgrade the Infrastructure Services, you must reconfigure the Infrastructure Services using the WEM Infrastructure Service Configuration utility. See Configure the infrastructure service.

Step 2: Upgrade the database

Important

The database upgrade process is not reversible. Ensure that you have a valid database backup before launching the upgrade process.

Important

SQL Server Always On availability groups. If your Workspace Environment Management database is deployed in an SQL Server Always On availability group, before upgrading the database you must remove it from the  availability group.

Tip

 You can also upgrade the database using the Workspace Environment Management PowerShell SDK module. For SDK documentation see Citrix Developer Documentation.

Use the WEM Database Management Utility to update the database. This is installed is installed on your Workspace Environment Management infrastructure server during the infrastructure services installation process.

Note: If you are using Windows authentication for your SQL Server, run the database upgrade utility under an identity that has sysadmin permissions.

1. From the Start menu select Citrix>Workspace Environment Management>WEM Database Management Utility.

2. Click Upgrade Database.

localized image

Server and instance name. Address of the SQL Server\instance on which the database is hosted. It must be reachable exactly as entered from the infrastructure server.

Database name. Name of the database to be upgraded.

Infrastructure service uses Windows authentication.

When this option is cleared (the default) the database expects the infrastructure service to connect to it using the vuemUser SQL user account. The vuemUser SQL user account is created by the installation process. This requires Mixed-Mode Authentication to be enabled for the SQL instance.

When this option is selected, the database expects the infrastructure service to connect to it using a Windows account. In this case the Windows account you select must not already have a login on the SQL instance. In other words, you cannot use the same Windows account to run the infrastructure service as you used to create the database.

The option Use integrated connection is selected by default. It allows the wizard to use the Windows account of the identity it is running under to connect to SQL and create the database. If this Windows account does not have sufficient permissions to create the database, you can either run the database management utility as a Windows account with sufficient privileges, or you can clear this option and provide an SQL account with sufficient privileges instead.

Click Upgrade to start the database upgrade process. Once you are notified that the database upgrade has completed successfully, you can exit the application.

If there are errors during the database upgrade, please check the VUEM Database Management Utility Log file in your Workspace Environment Management infrastructure services installation directory.

Step 3: Upgrade the administration console

All Workspace Environment Management settings configured with the Administration Console are stored in the database and are preserved during upgrade.

To upgrade the administration console, run the administration console setup executable. The procedure is otherwise identical to the installation procedure.

Step 4: Upgrade the agent

Important

Before upgrading an agent, make sure no users are logged in. This ensures that the upgrade process can modify the files on that machine.

To upgrade the agent, run the new agent setup executable on the target machine.

After upgrading the agent (via installer or private patch) run the following two commands to ensure that the Agent .dll files are correctly precompiled:

C:\Windows\Microsoft.NET\Framework64\v4.0.30319\ngen.exe update

C:\Windows\Microsoft.NET\Framework64\v4.0.30319\ngen.exe eqi 3

(Please note that for 32-bit operating systems, the path is instead
C:\Windows\Microsoft.NET\Framework\v4.0.30319\ngen.exe).

By design, agents are backward-compatible within the same major release version.