Citrix Daas SDK

New-VusMachineUpgrade

Creates a new schedule for a machine or list of machines

Syntax

New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-IncludeAdditionalComponents <ComponentSelection[]>]
   [-ExcludeComponents <ComponentSelection[]>]
   [-Features <String[]>]
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineName <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-Features <String[]>]
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineName <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineName <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineName <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-IncludeAdditionalComponents <ComponentSelection[]>]
   [-ExcludeComponents <ComponentSelection[]>]
   [-Features <String[]>]
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineName <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-Features <String[]>]
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineName <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineName <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineName <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-IncludeAdditionalComponents <ComponentSelection[]>]
   [-ExcludeComponents <ComponentSelection[]>]
   [-Features <String[]>]
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUid <Int32[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-Features <String[]>]
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUid <Int32[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUid <Int32[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUid <Int32[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-IncludeAdditionalComponents <ComponentSelection[]>]
   [-ExcludeComponents <ComponentSelection[]>]
   [-Features <String[]>]
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUid <Int32[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-Features <String[]>]
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUid <Int32[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUid <Int32[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUid <Int32[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-IncludeAdditionalComponents <ComponentSelection[]>]
   [-ExcludeComponents <ComponentSelection[]>]
   [-Features <String[]>]
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUuid <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-Features <String[]>]
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUuid <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUuid <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   -ScheduledTimeInUtc <DateTime>
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUuid <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-IncludeAdditionalComponents <ComponentSelection[]>]
   [-ExcludeComponents <ComponentSelection[]>]
   [-Features <String[]>]
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUuid <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-Features <String[]>]
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUuid <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUuid <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-VusMachineUpgrade
   [-UpgradeNow]
   -DurationInHours <Int32>
   [-Features <String[]>]
   -IncludeAdditionalComponentsXml <String>
   -ExcludeComponentsXml <String>
   [-VdaWorkstationPackageUri <String>]
   [-VdaServerPackageUri <String>]
   [-UpgradeVersion <String>]
   [-LogoffOption <LogoffOption>]
   [-InstallOrUpgradeCWA]
   [-Reboot]
   -MachineUuid <String[]>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Description

The New-VusMachineUpgrade cmdlet creates a new schedule for a machine or list of machines.

The cmdlet syncs with broker service to determine if the machine actually is added to broker service and only then schedules the upgrade for it.

Examples

EXAMPLE 1

Create a new upgrade for the machine matching the given UUID.

NewVusMachineUpgrade -MachineUuid "26C82B4E-A8E7-4013-8055-9110FD9FFDC9" -ScheduledTimeInUtc ([System.DateTime]::ParseExact("10/23/2021 07:00 PM", 'MM/dd/yyyy hh:mm tt', $null)) -DurationInHours 4
<!--NeedCopy-->

EXAMPLE 2

Create a new upgrade for the machine matching the given UUID.

NewVusMachineUpgrade -MachineUuid "26C82B4E-A8E7-4013-8055-9110FD9FFDC9" -UpgradeNow -DurationInHours 4
<!--NeedCopy-->

EXAMPLE 3

Create a new upgrade for a list of machines matching the given list of UUIDs.

NewVusMachineUpgrade -MachineUuid @("26C82B4E-A8E7-4013-8055-9110FD9FFDC9","48C6D5FC-8547-449D-A779-124C7AAE3AC8") -UpgradeNow -DurationInHours 4
<!--NeedCopy-->

EXAMPLE 4

Create a new upgrade that will use a custom location to download the installer package from.

NewVusMachineUpgrade -MachineUuid "26C82B4E-A8E7-4013-8055-9110FD9FFDC9" -UpgradeNow -DurationInHours 4 -VdaWorkstationPackageUri "\\hostname\VDA-Packages\VDAWorkstationSetup_2308.exe"
<!--NeedCopy-->

EXAMPLE 5

Create a new upgrade using a custom download location for a list of machines containing a mix of workstation and server OSes.

NewVusMachineUpgrade -MachineUuid @("26C82B4E-A8E7-4013-8055-9110FD9FFDC9","48C6D5FC-8547-449D-A779-124C7AAE3AC8") -UpgradeNow -DurationInHours 4 -VdaWorkstationPackageUri "\\hostname\VDA-Packages\VDAWorkstationSetup_2308.exe" -VdaServerPackageUri "\\hostname\VDA-Packages\VDAServerSetup_2308.exe"
<!--NeedCopy-->

EXAMPLE 6

Schedule a upgrade on two machines and log off disconnected session before the upgrade begins. Other options are ActiveSessionsOnly, DoNotLogOff, ActiveAndDisconnectedSessions

NewVusMachineUpgrade -MachineUuid @("26C82B4E-A8E7-4013-8055-9110FD9FFDC9","48C6D5FC-8547-449D-A779-124C7AAE3AC8") -UpgradeNow -DurationInHours 4 -LogoffOption DisconnectedSessionsOnly
<!--NeedCopy-->

Parameters

-ScheduledTimeInUtc

Scheduled time in UTC when machine upgrade occurs

Type: DateTime
Position: Named
Default value: None
Required: True
Accept pipeline input: False
Accept wildcard characters: False

-DurationInHours

Hours available for upgrade

Type: Int32
Position: Named
Default value: None
Required: True
Accept pipeline input: False
Accept wildcard characters: False

-IncludeAdditionalComponentsXml

List of New Components(in XML format) that are to be included/added in the Upgrade for a single machine only. The XML Scehma definition(xsd) is provided in the examples section.ComponentId, ParameterId can be obtianed from the GetVusMachineAdditionalComponents cmdlet.

Type: String
Position: Named
Default value: None
Required: True
Accept pipeline input: False
Accept wildcard characters: False

-ExcludeComponentsXml

List of Installed Components that are to be excluded/omitted in the Upgrade for a single machine only.This parameter accepts XML string. The XML Scehma definition(xsd) is provided in the examples section. ComponentId, ParameterId can be obtianed from the GetVusMachineAdditionalComponents cmdlet.

Type: String
Position: Named
Default value: None
Required: True
Accept pipeline input: False
Accept wildcard characters: False

-UpgradeNow

Switch to start upgrade at current time in UTC

Type: SwitchParameter
Position: Named
Default value: None
Required: True
Accept pipeline input: False
Accept wildcard characters: False

-IncludeAdditionalComponents

List of New Components that are to be included/added in the Upgrade for a single machine only. This parameter accepts a List of Component PS Object. ComponentId and ParameterId can be obtianed from the GetVusMachineAdditionalComponents cmdlet.

Type: ComponentSelection[]
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-ExcludeComponents

List of Installed Components that are to be excluded/omitted in the Upgrade for a single machine only. This parameter accepts a List of Component PS Object. ComponentId and ParameterId can be obtianed from the GetVusMachineAdditionalComponents cmdlet.

Type: ComponentSelection[]
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-Features

List of string (FeatureId GUIDs) to be enabled on VDA. FeatureId can be obtained from the GetVusMachineAdditionalComponents cmdlet

Type: String[]
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-VdaWorkstationPackageUri

Custom location to download the VDA Workstation package from. Currently, only network shares (specified using a UNC path) are supported.

Type: String
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-VdaServerPackageUri

Custom location to download the VDA Server package from. Currently, only network shares (specified using a UNC path) are supported.

Type: String
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-UpgradeVersion

Upgrade Version to which the VDA needs to be Upgraded to.

Type: String
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-LogoffOption

Specify how the VDA Upgrade Service handles VDAs with active or disconnected sessions during the upgrade window. Logging off sessions to perform upgrades can increase the number of VDAs that are available to be upgraded but can result in users being logged off of their VDAs unexpectedly. Possible values are:

  • DoNotLogOff: Active and disconnected sessions are not logged off. VDA upgrades will be cancelled if an active or disconnected session is present on the VDA throughout the upgrade window.
  • ActiveSessionsOnly: If an active session is on the VDA during the scheduled upgrade window, the user will be logged off. A banner will display 10 minutes before the user is logged off to provide a warning. VDAs with disconnected sessions will not be logged off during the upgrade window. If the disconnected session remains throughout the upgrade window, that VDA upgrade will be cancelled.
  • DisconnectedSessionsOnly: If a disconnected session is present on the VDA during the scheduled upgrade window, the user will be logged off. Users are not notified that their disconnected session will be logged off. VDAs with active sessions will not be logged off during the upgrade window. If the active session remains throughout the upgrade window, that VDA upgrade will be cancelled.
  • ActiveAndDisconnectedSessions: If a disconnected or active session is on the VDA during the scheduled upgrade window, the user will be logged off. For active sessions, a banner will display 10 minutes before the user is logged off to provide a warning.

Note: Logging off active or disconnected sessions can result in unexpected user data loss.

Type: LogoffOption
Accepted values: DoNotLogoff, ActiveSessionsOnly, DisconnectedSessionsOnly, ActiveAndDisconnectedSessions
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-InstallOrUpgradeCWA

Switch to specify whether to Install or Upgrade CWA along with VDA Upgrades

Type: SwitchParameter
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-Reboot

Switch parameter to specify VDA needs to be rebooted before upgrade

Type: SwitchParameter
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-MachineName

Type: String[]
Position: Named
Default value: None
Required: True
Accept pipeline input: False
Accept wildcard characters: False

-MachineUid

Type: Int32[]
Position: Named
Default value: None
Required: True
Accept pipeline input: False
Accept wildcard characters: False

-MachineUuid

Type: String[]
Position: Named
Default value: None
Required: True
Accept pipeline input: False
Accept wildcard characters: False

CitrixCommonParameters

This cmdlet supports the common Citrix parameters: -AdminAddress, -AdminClientIP, -BearerToken, -TraceParent, -TraceState and -VirtualSiteId. For more information, see about_CitrixCommonParameters.

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

Guid

Citrix.VdaUpdateService.Sdk.ComponentSelection

Component Information for the Selected/Excluded Component

Citrix.VdaUpdateService.Sdk.ComponentParameter

Feature/Parameter information for the selected feature/parameter

Citrix.VdaUpdateService.Sdk.LogoffOption

Specify how the VDA Upgrade Service handles VDAs with active or disconnected sessions during the upgrade window. Logging off sessions to perform upgrades can increase the number of VDAs that are available to be upgraded but can result in users being logged off of their VDAs unexpectedly. Possible values are:

  • DoNotLogOff: Active and disconnected sessions are not logged off. VDA upgrades will be cancelled if an active or disconnected session is present on the VDA throughout the upgrade window.
  • ActiveSessionsOnly: If an active session is on the VDA during the scheduled upgrade window, the user will be logged off. A banner will display 10 minutes before the user is logged off to provide a warning. VDAs with disconnected sessions will not be logged off during the upgrade window. If the disconnected session remains throughout the upgrade window, that VDA upgrade will be cancelled.
  • DisconnectedSessionsOnly: If a disconnected session is present on the VDA during the scheduled upgrade window, the user will be logged off. Users are not notified that their disconnected session will be logged off. VDAs with active sessions will not be logged off during the upgrade window. If the active session remains throughout the upgrade window, that VDA upgrade will be cancelled.
  • ActiveAndDisconnectedSessions: If a disconnected or active session is on the VDA during the scheduled upgrade window, the user will be logged off. For active sessions, a banner will display 10 minutes before the user is logged off to provide a warning.

Note: Logging off active or disconnected sessions can result in unexpected user data loss.

Outputs

Citrix.VdaUpdateService.Sdk.MachineScheduleObject

Upgrade information for most recent machine schedule

New-VusMachineUpgrade