Overview

The Citrix VDA Upgrade Service is part of Citrix DaaS (Desktop as a Service). It supports the streamlined upgrade process of Virtual Delivery Agents (VDAs) within the Citrix environment. The service is designed for organizations using Citrix DaaS to manage and maintain virtual desktop environments, ensuring these environments stay up to date with the latest VDA versions. This update process is crucial because it improves performance, enhances security, and is compatible with new Citrix DaaS features. Administrators can use VUS to check for the latest updates, schedule upgrades, and monitor progress. They can initiate an upgrade immediately or set it for a specified date and time. This flexibility helps reduce downtime by allowing upgrades during off-peak hours. Upgrades can be scheduled through Citrix Web Studio or automated via PowerShell commands. The service lets admins view VDAs' current upgrade status within their catalog, identifying issues if upgrades don't proceed as expected.

The Citrix VDA Update Service PowerShell snap-in provides administrative functions for the VDA Update Service. In this article, we will focus on the available PowerShell commands.

Prerequisites

To use the Citrix VDA Upgrade Service PowerShell commands, you need the Citrix Remote PowerShell SDK version 7.43 or later. Go to Citrix Downloads to download the latest version.

Available PowerShell Commands

Below is the full list of PowerShell Cmdlets available with Citrix Remote PowerShell SDK for the Citrix VDA Upgrade Service. In total, there are 31 Cmdlets, 18 of which are for internal purposes only (noted with (1) above). In the ensuing section, the purpose of each Cmdlet is described in detail.

• Confirm-VusSelection
• Get-VusAvailableVdaVersion
• Get-VusCatalog
• Get-VusComponents
• Get-VusComponentVersion
• Get-VusDBConnection (1)
• Get-VusDBSchema (1)
• Get-VusDBVersionChangeScript (1)
• Get-VusEntityUnit (1)
• Get-VusInstalledDBVersion (1)
• Get-VusMachine
• Get-VusMachineSchedule (1)
• Get-VusRevision (1)
• Get-VusSchedule (1)
• Get-VusService (1)
• Get-VusServiceAddedCapability (1)
• Get-VusServiceInstance (1)
• Get-VusServiceStatus (1)
• New-VusCatalogSchedule
• New-VusMachineUpgrade
• Remove-VusCatalogUpgrade
• Remove-VusMachineUpgrade
• Remove-VusServiceMetadata (1)
• Reset-VusEnabledFeatureList (1)
• Reset-VusServiceGroupMembership (1)
• Set-VusCatalogUpgrade
• Set-VusCatalogUpgradeType
• Set-VusDBConnection (1)
• Set-VusMachineUpgrade
• Set-VusServiceMetadata (1)
• Test-VusDBConnection (1)

Confirm-VusSelection 

Validate the component selection choices at the catalog level that can be Included/Excluded during an upgrade using VDA Upgrade Service.

The Confirm-VusSelection cmdlet is used to verify and validate the component Selections (New Components to be included in the Upgrade), Exclusions (Installed Components that should not be upgraded), and features to be used in a Catalog Upgrade using the VDA Upgrade Service.

Confirm-VusSelection returns true if the Selection is Valid. If it is invalid, it returns false information as to why the selection is invalid.

Requires: -CatalogName, -CatalogUID, -CatalogUUID, -SelectedComponents, -ExcludedComponents and -Features parameters.

You will have to run the following command to retrieve the FeatureId:

$(Get-VusComponents -CatalogName catalog-name).AvailableFeatures | Format-List -Property *

The following commands must be run to configure the Components.

$EmptyParamList = @()

$ComponentA = [PSCustomObject]@{

    ComponentId = [System.guid]::new('396394b3-53f0-48e0-8d8c-61dad39e3f17')

    Parameters = $EmptyParamList

}

After, you can run the command by retrieving details for components and features.

Confirm-VusSelection -CatalogName “Windows 10 Static MC” -Features “44ff6e61-e3cc-45d0-be9b-f52b5ab72a08” -SelectedComponents $ComponentA

Get-VusAvailableVdaVersion

The Get-VusAvailableVdaVersion cmdlet in Citrix’s VDA Update Service allows administrators to check the latest available VDA versions compatible with their current Citrix setup, specifically for VDA updates via Citrix Virtual Apps and Desktops service.

When this cmdlet is executed, it returns details about the compatible VDA versions to whichh the current catalog or machine can be upgraded based on the catalog’s lowest VDA version.

This cmdlet is useful for determining the upgrade paths for the current (CR) and long-term service releases (LTSR).

Using Get-VusAvailableVdaVersion helps ensure that administrators can select the best version for their needs, be it a more recent CR version for frequent updates or an LTSR version for stability.

This cmdlet is often combined with scheduling cmdlets such as New-VusCatalogSchedule and New-VusMachineUpgrade for the streamlined deployment of upgrades.

Example of a command:

Get-VusAvailableVdaVersion

Get-VusCatalog

The Get-VusCatalog cmdlet in Citrix’s VDA Upgrade Service is a PowerShell command used to retrieve and display information about a specific machine catalog in Citrix DaaS environments.

This cmdlet helps check the upgrade state and configuration of Virtual Delivery Agents (VDAs) in a catalog. Administrators can view details like the catalog's current VDA version, upgrade eligibility, and any scheduled upgrades.

Additionally, it provides insights into whether the catalog meets the requirements for specific upgrade paths, making it a valuable tool for managing and automating VDA upgrades across large deployments.

The Get-VusCatalog cmdlet also allows administrators to set the upgrade type at the catalog level (e.g., selecting LTSR or Current Release tracks), ensuring consistency and stability for VDAs in the catalog.

This flexibility enhances operational efficiency by enabling automated and scheduled upgrades, minimizing disruption for end users.

It’s often used alongside other cmdlets, like New-VusCatalogSchedule for scheduling upgrades or Set-VusCatalogUpgradeType to define upgrade preferences, supporting streamlined and effective VDA version management and catalog compatibility requirements.

Example of a command:

Get-VusCatalog

Get-VusComponents

The Get-VusComponents cmdlet in Citrix DaaS SDK retrieves information on all available upgradeable components for Virtual Delivery Agents (VDAs).

This command is essential in identifying the specific VDA components that can be targeted in a catalog upgrade.

When used, Get-VusComponents returns details such as component IDs and parameters required to specify which VDA components to include or exclude in an upgrade.

These identifiers are often used with other cmdlets, such as Confirm-VusSelection and New-VusCatalogSchedule, to customize the upgrade configuration for different VDAs in the environment.

For example, administrators can extract component details using Get-VusComponents and then pass those details to New-VusCatalogSchedule to schedule upgrades that include specific components or exclude others based on catalog requirements.

This modular setup streamlines the upgrade process, enabling granular control over component selection and version management.

This cmdlet is crucial for refining upgrade tasks as part of the Citrix Daas SDK, especially in large-scale environments where certain components may require different update timelines or configurations.

Requires: -CatalogName, -CatalogUID or -CatalogUUID parameter.

Example of a command:

Get-VusComponents -CatalogName “Windows 10 Static MC”

Get-VusComponentVersion

The Get-VusComponentVersion cmdlet is part of Citrix's VDA Upgrade Service management and retrieves the specific version information for components on Virtual Delivery Agents (VDAs) within a machine catalog.

This cmdlet verifies that a VDA has successfully reported its component versions to the VDA Update Service.

You typically pass the MachineId (or UUID) to this cmdlet to filter results for individual VDAs.

This can be critical in troubleshooting scenarios, especially when confirming that the VDA Upgrade Agent has accurately recorded and reported its version information.

If no version information is reported, it might indicate issues with the agent's connectivity or configuration, which may require restarting the VDA Upgrade Agent or checking its log files for errors.

For example, you can use Get-VusComponentVersion -MachineId <UUID> to retrieve the current version data for a specific VDA, which helps in planning or confirming upgrades across environments

Example of a command:

Get-VusComponentVersion

Get-VusMachine

The Get-VusMachine cmdlet in Citrix Virtual Apps and Desktops (VAD) is a PowerShell command designed to retrieve details about individual virtual desktop machines within a machine catalog.

This cmdlet is primarily used to track machines' upgrade readiness and version alignment within the catalog.

Specifically, Get-VusMachine outputs data such as:

• MachineName: The name of the virtual desktop machine.
• Uid: The unique identifier for the machine.
• UpgradeState: The current state of the machine regarding updates (e.g., UpToDate, Available, Scheduled or Unknown).
• UpgradeType: The update track, such as Current Release (CR) or Long Term Service Release (LTSR), applied to that machine.

This cmdlet is often combined with Set-VusMachineUpgrade to schedule upgrades based on machine-specific requirements. It enables administrators to automate, track, and manage upgrades across multiple machines in the Citrix environment.

Example of a command:

Get-VusMachine

New-VusCatalogSchedule

The New-VusCatalogSchedule cmdlet in Citrix's VDA Upgrade Service (VUS) sets up scheduled upgrades for Virtual Delivery Agent (VDA) versions within a specific catalog.

This scheduling process helps automate upgrades to maintain consistent software versions across a deployment.

To use this cmdlet, specify a scheduled time (ScheduledTimeInUtc) or set the upgrade to begin immediately (UpgradeNow).

Additionally, you can define DurationInHours, which sets the length of the upgrade process, allowing VDAs to be placed into maintenance mode as needed.

The upgrade schedule is configured for each catalog to help ensure compatibility with the chosen VDA version.

Other parameters include options for defining the VDA version from a local network share if you prefer this over direct cloud-based upgrades.

This allows more flexibility in managing the installation location, especially if certain network policies restrict cloud access for updates.

Requires at least parameters -CatalogName(UID,UUID) -UpgradeNow or -ScheduledTimeInUtc and DurationInHours.s

Example of a command:                                                                                                         

New-VusCatalogSchedule -CatalogName "Windows 10 Static MC" -ScheduledTimeInUtc ([System.DateTime]::ParseExact("11/01/2024 01:00 PM", 'MM/dd/yyyy hh:mm tt', $null)) -DurationInHours 4

New-VusMachineUpgrade

The New-VusMachineUpgrade cmdlet in Citrix configures Virtual Delivery Agents (VDAs) upgrades at the machine level.

This allows administrators to schedule or immediately initiate the upgrade process for a specific VDA, ensuring that the machines run the latest software.

Key Features:

• Machine Level Configuration: This cmdlet targets individual machines rather than the entire catalog.
• Scheduling: The ScheduledTimeInUtc parameter allows you to set upgrades to occur immediately or at a specified time.
• Logging: When the upgrade process is executed, it can log actions to help troubleshoot any issues that arise during the upgrade.
• Compatibility: The cmdlet also supports upgrades to compatible versions of the VDA based on the existing version running on the machine.

Requires at least parameters -MachineName(UID,UUID) -UpgradeNow or -ScheduledTimeInUtc, DurationInHours and UpgradeVersion.

Example of a command:

New-VusMachineUpgrade -MachineName LAB\LAB-CTX-W10S-06 -UpgradeNow -DurationInHours 2 -UpgradeVersion 2402.0.1100.1256

Remove-VusCatalogUpgrade

The Remove-VusCatalogUpgrade cmdlet in Citrix is used to cancel or remove an ongoing upgrade process for a machine catalog.

This is particularly useful when you want to halt an upgrade that is currently in progress or scheduled due to a change in strategy or issues arising during the upgrade process.

Invoking this cmdlet typically requires parameters that specify which catalog's upgrade you wish to remove.

This can include the catalog's unique identifier (UUID) or other identifiers associated with the upgrade process.

By executing this command, you ensure that the specified upgrade does not proceed, allowing for better control over your environment, especially in larger setups where managing multiple upgrades can become complex.

Requires at least parameters -CatalogName(UID,UUID)

Example of a command:

Remove-VusCatalogUpgrade -CatalogName “Windows 10 Static MC”

Remove-VusMachineUpgrade

The Remove-VusMachineUpgrade cmdlet in Citrix cancels or removes a scheduled upgrade for a specific Virtual Delivery Agent (VDA) machine.

This command can be beneficial if you need to halt an upgrade process previously scheduled due to changes in your deployment plans or if you've identified issues requiring the upgrade to be postponed.

Key Features of Remove-VusMachineUpgrade:

• Targeted Removal: This option allows you to specify the machine by its UUID (Universally Unique Identifier) to target which upgrade should be canceled precisely.
• Usage Context: This cmdlet is typically used in environments where upgrades to VDAs are managed through PowerShell, particularly in automated or scripted scenarios.

It requires at least the following parameters: MachineName(UID,UUID).

Example of a command:

Remove-VusMachineUpgrade -MachineName LAB\LAB-CTX-W10S-06

Set-VusCatalogUpgrade

The Set-VusCatalogUpgrade cmdlet in Citrix's Virtual Apps and Desktops (formerly Citrix DaaS) environment modifies an already scheduled catalog upgrade's date, time, and duration.

This cmdlet allows administrators to specify the upgrade type (such as Current Release (CR) or Long Term Service Release (LTSR)) for the catalog. The change is made at the catalog level and influences how the Virtual Delivery Agents (VDAs) within that catalog are upgraded.

Here's a brief overview of its functionality:

• Upgrade Type: You can set the upgrade type to dictate whether VDAs in the catalog receive upgrades as part of the CR or LTSR tracks. This helps manage the updated strategy based on organizational needs.
• Catalog Level: The command operates at the machine catalog level, affecting all machines within the specified catalog rather than individual machines.
• Pre-requisites: Before using this cmdlet, you must ensure that the catalog is set up correctly and that you have the necessary permissions to make changes.

Using Set-VusCatalogUpgrade is part of the broader strategy for managing VDA upgrades effectively. This strategy ensures that the virtual environment remains up to date while adhering to organizational policies regarding software updates.

Example of a command:

Set-VusCatalogUpgrade -CatalogName “Windows 10 Static MC” -UpgradeNow -DuractionInHours 8

Set-VusCatalogUpgradeType

The Set-VusCatalogUpgradeType cmdlet in Citrix's VDA Upgrade Service specifies the upgrade type for a machine catalog.

The upgrade types can typically be set to Continuous Release (CR) or Long-Term Service Release (LTSR). This cmdlet can only be applied at the machine catalog level.

Key Features:

• Upgrade Type Selection: You can select between CR and LTSR, which determines how upgrades will be handled for the virtual desktops in that catalog.
• Scheduled Upgrades: Once the upgrade type is set, it can help schedule upgrades according to the chosen release track, whichh is crucial for managing the lifecycle of virtual desktop environments.

It requires at least the following parameters: CatalogName(UID,UUID) and UpgradeType.

Example of a command:

Set-VusCatalogUpgradeType -CatalogName “Windows 10 Static MC” -UpgradeType CR

Set-VusMachineUpgrade

The Set-VusMachineUpgrade cmdlet in Citrix manages the upgrade process for Virtual Delivery Agents (VDAs) at the machine level.

This cmdlet lets administrators specify upgrade options for individual machines within a catalog.

Key Features of Set-VusMachineUpgrade:

1. 1. Parameters:
      • MachineUuid: Specifies the UUID of the machine you want to upgrade.
      • ScheduledTimeInUtc: Sets a specific time in UTC for the upgrade.
      • UpgradeNow: A switch parameter that, when used, triggers the upgrade immediately rather than at a scheduled time.
      • DurationInHours: This option allows the administrator to specify how long the upgrade should take, which can help manage resources and downtime effectively.
      • LoggingId*: This optional parameter tracks and logs the operation for future reference.
   2. Behavior:
      • If the upgrade is already in progress, the new settings will affect only the machines that have yet to begin the upgrade.
      • This cmdlet is helpful for quickly scheduling or rescheduling upgrades to ensure that VDAs are updated to the desired version while managing potential disruptions.

Requires at least parameters -MachineName(UID,UUID), UpgradeNow and DurationInHours.

Example of a command:

Set-VusMachineUpgrade -MachineName “LAB\LAB-CTX-W10S-06” -UpgradeNow -DurationInHours 4