Citrix Virtual Apps and Desktops SDK

Set-ProvVM

August 9, 2024

Contributed by:

Introduced in: Citrix Virtual Apps and Desktop 7 2308

Changes the configuration for a specific provisioned virtual machine.

Syntax

Set-ProvVM
   -ProvisioningSchemeUid <Guid>
   -VMId <String>
   [-CpuCount <Int32>]
   [-MemoryInMB <Int32>]
   [-CustomProperties <String>]
   [-ServiceOffering <String>]
   [-MachineProfile <String>]
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Set-ProvVM
   -ProvisioningSchemeUid <Guid>
   -VMId <String>
   [-RevertToProvSchemeConfiguration]
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Set-ProvVM
   -ProvisioningSchemeUid <Guid>
   -VMName <String>
   [-CpuCount <Int32>]
   [-MemoryInMB <Int32>]
   [-CustomProperties <String>]
   [-ServiceOffering <String>]
   [-MachineProfile <String>]
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Set-ProvVM
   -ProvisioningSchemeUid <Guid>
   -VMName <String>
   [-RevertToProvSchemeConfiguration]
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Set-ProvVM
   -ProvisioningSchemeName <String>
   -VMId <String>
   [-CpuCount <Int32>]
   [-MemoryInMB <Int32>]
   [-CustomProperties <String>]
   [-ServiceOffering <String>]
   [-MachineProfile <String>]
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Set-ProvVM
   -ProvisioningSchemeName <String>
   -VMId <String>
   [-RevertToProvSchemeConfiguration]
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Set-ProvVM
   -ProvisioningSchemeName <String>
   -VMName <String>
   [-CpuCount <Int32>]
   [-MemoryInMB <Int32>]
   [-CustomProperties <String>]
   [-ServiceOffering <String>]
   [-MachineProfile <String>]
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Set-ProvVM
   -ProvisioningSchemeName <String>
   -VMName <String>
   [-RevertToProvSchemeConfiguration]
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Description

Provides the ability to update the configuration of an existing persistent provisioned virtual machine.

These properties are specific customizations unique to the virtual machine and do not apply to any other VMs in the catalog. The final properties the machine will use are a combination of those currently set on the provisioning scheme combines with the settings specified here. Any properties set at the ProvVM-level with this command will override any settings at the ProvScheme-level.

To view the current specific configuration for a machine, use Get-ProvVMConfiguration

To view the final set of properties a machine will have applied (taking into account ProvScheme-level settings), use Get-ProvVMConfigurationResultantSet

Any configuration changes made will not apply right away to the machine. To apply the updates, set an update time window for the machine with Set-ProvVMUpdateTimeWindow and start the machine within the window. Currently, this feature is applicable only to the AWS and Azure environments.

Examples

EXAMPLE 1

Sets the configuration for machine1 to use 2 CPUs. Sets an update time window starting now and reboots the machine to apply the update.

Get-ProvVM -ProvisioningSchemeName MyScheme -VMName machine1 | select VMName, ProvVMConfigurationVersion
VMName      ProvVMConfigurationVersion
------      --------------------
machine1


Get-ProvVMConfiguration

Set-ProvVM -ProvisioningSchemeName MyScheme -VMName machine1 -CpuCount 2

Get-ProvVMConfiguration
CpuCount               : 2
CustomProperties       : 
MachineProfile         :
MemoryInMB             :
ProvisioningSchemeName : MyScheme
ProvisioningSchemeUid  : 378cece5-a824-41f7-9e92-74be76672be6
ServiceOffering        :
VMId                   : 0707da6d-2f0f-a8c7-ce92-3d64f824ac60
VMMetadata             :
VMName                 : machine1
Version                : 1

Get-ProvVM -ProvisioningSchemeName MyScheme -VMName machine1 | select VMName, ProvVMConfigurationVersion
VMName      ProvVMConfigurationVersion
------      --------------------
machine1

Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName MyScheme -StartsNow -DurationInMinutes -1

New-BrokerHostingPowerAction -Action "Restart" -MachineName machine1

Get-ProvVM -ProvisioningSchemeName MyScheme -VMName machine1 | select VMName, ProvVMConfigurationVersion
VMName      ProvVMConfigurationVersion
------      --------------------
machine1                       1
<!--NeedCopy-->

EXAMPLE 2

Clears existing configuration for machine1. Sets an update time window starting now and reboots the machine to clear the configuration.

Get-ProvVMConfiguration
CpuCount               : 8
CustomProperties       : 
MachineProfile         :
MemoryInMB             : 4096
ProvisioningSchemeName : MyScheme
ProvisioningSchemeUid  : 378cece5-a824-41f7-9e92-74be76672be6
ServiceOffering        :
VMId                   : 0707da6d-2f0f-a8c7-ce92-3d64f824ac60
VMMetadata             :
VMName                 : machine1
Version                : 7

Set-ProvVM -ProvisioningSchemeName MyScheme -VMName machine1 -RevertToProvSchemeConfiguration

Get-ProvVMConfiguration
CpuCount               : 
CustomProperties       : 
MachineProfile         :
MemoryInMB             :
ProvisioningSchemeName : MyScheme
ProvisioningSchemeUid  : 378cece5-a824-41f7-9e92-74be76672be6
ServiceOffering        :
VMId                   : 0707da6d-2f0f-a8c7-ce92-3d64f824ac60
VMMetadata             :
VMName                 : machine1
Version                : 8

Get-ProvVM -ProvisioningSchemeName MyScheme -VMName machine1 | select VMName, ProvVMConfigurationVersion
VMName      ProvVMConfigurationVersion
------      --------------------
machine1                       7

Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName MyScheme -StartsNow -DurationInMinutes -1

New-BrokerHostingPowerAction -Action "Restart" -MachineName machine1

Get-ProvVM -ProvisioningSchemeName MyScheme -VMName machine1 | select VMName, ProvVMConfigurationVersion
VMName      ProvVMConfigurationVersion
------      --------------------
machine1                       8
<!--NeedCopy-->

EXAMPLE 3

Configures machine1 to have a custom MachineProfile. ServiceOffering and CustomProperties were read from MachineProfile and set on the configuration

Get-ProvVMConfiguration
CpuCount               : 
CustomProperties       : <CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                         <Property xsi:type="StringProperty" Name="WBCDiskStorageType" Value="Premium_LRS" />
                         </CustomProperties>
MachineProfile         : 
MemoryInMB             :
ProvisioningSchemeName : MyScheme
ProvisioningSchemeUid  : 378cece5-a824-41f7-9e92-74be76672be6
ServiceOffering        : serviceoffering.folder\Standard_D2s_v5.serviceoffering
VMId                   : 0707da6d-2f0f-a8c7-ce92-3d64f824ac60
VMMetadata             :
VMName                 : machine1
Version                : 1

Set-ProvVM -ProvisioningSchemeName MyScheme -VMName machine1 -MachineProfile "XDHyp:\HostingUnits\AzureRes\machineprofile.folder\TestRG.resourcegroup\machineProfile.vm"

Get-ProvVMConfiguration
CpuCount               : 
CustomProperties       : <CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                         <Property xsi:type="StringProperty" Name="StorageType" Value="Premium_LRS" />
                         <Property xsi:type="StringProperty" Name="WBCDiskStorageType" Value="Premium_LRS" />
                         </CustomProperties>
MachineProfile         : machineprofile.folder\TestRG.resourcegroup\machineProfile.vm
MemoryInMB             :
ProvisioningSchemeName : MyScheme
ProvisioningSchemeUid  : 378cece5-a824-41f7-9e92-74be76672be6
ServiceOffering        : serviceoffering.folder\Standard_D2s_v3.serviceoffering
VMId                   : 0707da6d-2f0f-a8c7-ce92-3d64f824ac60
VMMetadata             :
VMName                 : machine1
Version                : 2
<!--NeedCopy-->

EXAMPLE 4

In this AWS example Set-ProvVM sets the configuration for machine1 to use T3 Large ServiceOffering. Sets an update time window starting now and reboots the machine to apply the update.

Get-ProvVM -ProvisioningSchemeName AWSScheme -VMName machine1 | select VMName, ProvVMConfigurationVersion
VMName      ProvVMConfigurationVersion
------      --------------------
machine1

Get-ProvVMConfiguration AWSScheme -VMName machine1

Set-ProvVM -ProvisioningSchemeName AWSScheme -VMName machine1 -ServiceOffering "XDHyp:\HostingUnits\AWSHostingUnit\T3 Large Instance.serviceoffering"

Get-ProvVMConfiguration AWSScheme -VMName machine1
CpuCount               : 
CustomProperties       : 
MachineProfile         :
MemoryInMB             :
ProvisioningSchemeName : AWSScheme
ProvisioningSchemeUid  : a13a9d94-a2a1-46ee-8363-1d225e9ef468
ServiceOffering        : T3 Large Instance.serviceoffering
VMId                   : i-0bdd24b3309920f3a
VMMetadata             :
VMName                 : machine1
Version                : 1

Get-ProvVM -ProvisioningSchemeName AWSScheme -VMName machine1 | select VMName, ProvVMConfigurationVersion
VMName     ProvVMConfigurationVersion
------     -------
machine1          

Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName AWSScheme -VMName machine1 -StartsNow -DurationInMinutes -1

New-BrokerHostingPowerAction -Action "Restart" -MachineName machine1

Get-ProvVM -ProvisioningSchemeName AWSScheme -VMName machine1 | select VMName, ProvVMConfigurationVersion
VMName     ProvVMConfigurationVersion
------     -------
machine1   1
<!--NeedCopy-->

EXAMPLE 5

In this AWS example -RevertToProvSchemeConfiguration clears existing configuration for machine1. Sets an update time window starting now and reboots the machine to clear the configuration.

Get-ProvVMConfiguration AWSScheme -VMName machine1
CpuCount               : 
CustomProperties       : 
MachineProfile         :
MemoryInMB             : 
ProvisioningSchemeUid  : a13a9d94-a2a1-46ee-8363-1d225e9ef468
ServiceOffering        : T3 Large Instance.serviceoffering
VMId                   : i-0bdd24b3309920f3a
VMMetadata             :
VMName                 : machine1
Version                : 1

Set-ProvVM -ProvisioningSchemeName AWSScheme -VMName machine1 -RevertToProvSchemeConfiguration


Get-ProvVMConfiguration AWSScheme -VMName machine1
CpuCount               : 
CustomProperties       : 
MachineProfile         :
MemoryInMB             :
ProvisioningSchemeName : AWSScheme
ProvisioningSchemeUid  : a13a9d94-a2a1-46ee-8363-1d225e9ef468
ServiceOffering        :
VMId                   : i-0bdd24b3309920f3a
VMMetadata             :
VMName                 : machine1
Version                : 2

Get-ProvVM -ProvisioningSchemeName AWSScheme -VMName machine1 | select VMName, ProvVMConfigurationVersion
VMName     ProvVMConfigurationVersion
------     -------
machine1   1

Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName AWSScheme -StartsNow -DurationInMinutes -1

New-BrokerHostingPowerAction -Action "Restart" -MachineName machine1

Get-ProvVM -ProvisioningSchemeName AWSScheme -VMName machine1 | select VMName, ProvVMConfigurationVersion
VMName      ProvVMConfigurationVersion
------      --------------------
machine1                       2
<!--NeedCopy-->

EXAMPLE 6

In this AWS example Set-ProvVM configures machine1 to have a custom MachineProfile. ServiceOffering was read from MachineProfile and set on the configuration

Get-ProvVMConfiguration AWSScheme -VMName machine1
CpuCount               : 
CustomProperties       : 
MachineProfile         : 
MemoryInMB             :
ProvisioningSchemeName : AWSScheme
ProvisioningSchemeUid  : a13a9d94-a2a1-46ee-8363-1d225e9ef468
ServiceOffering        :
VMId                   : i-0bdd24b3309920f3a
VMMetadata             :
VMName                 : machine1
Version                : 2

Set-ProvVM -ProvisioningSchemeName AWSScheme -VMName machine1 -MachineProfile "XDHyp:\HostingUnits\AWSHostingUnit\LaunchTemplate1.launchtemplate\lt-version (4).launchtemplateversion"

Get-ProvVMConfiguration AWSScheme -VMName machine1
CpuCount               : 
CustomProperties       :
MachineProfile         : LaunchTemplate1.launchtemplate\lt-version (4).launchtemplateversion
MemoryInMB             :
ProvisioningSchemeName : AWSScheme
ProvisioningSchemeUid  : a13a9d94-a2a1-46ee-8363-1d225e9ef468
ServiceOffering        : T3 Medium Instance.serviceoffering
VMId                   : i-0bdd24b3309920f3a
VMMetadata             : {A, A, E, A...}
VMName                 : machine1
Version                : 3
<!--NeedCopy-->

Parameters

-ProvisioningSchemeName

The name of the provisioning scheme the VM is a part of

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

-VMName

The VM name

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

-VMId

The VM ID

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

-RevertToProvSchemeConfiguration

If supplied, all existing configuration is cleared for the given machine. It is mutally exclusive with parameters that apply configuration settings

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

-ProvisioningSchemeUid

The identifier of the provisioning scheme the VM is a part of

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

-CpuCount

The number of processors. Not supported for cloud hypervisors

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

-MemoryInMB

The maximum amount of memory in megabytes. Not supported for cloud hypervisors

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

-CustomProperties

The properties of the provisioned virtual machine that are specific to the target hosting infrastructure. See about_Prov_CustomProperties for more information. If a property name already exists its value is updated; otherwise it is added. These properties are merged with prior custom properties set.

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

-ServiceOffering

The cloud ServiceOffering to use. Not supported for on-prem hypervisors

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

-MachineProfile

A path to the template used to obtain hypervisor-specific settings to be applied to the VM. Some settings have a corresponding CustomProperty. If any properties are present in the MachineProfile but not the CustomProperties, values from the template will be written to the CustomProperties. See about_Prov_MachineProfile for more details.

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

-LoggingId

Specifies the identifier of the high-level operation this cmdlet call forms a part of. Citrix Studio and Director typically create high-level operations. PowerShell scripts can also wrap a series of cmdlet calls in a high-level operation by way of the Start-LogHighLevelOperation and Stop-LogHighLevelOperation cmdlets.

Type:	Guid
Position:	Named
Default value:	None
Required:	False
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

None

You can’t pipe objects to this cmdlet.

Outputs

None

By default, this cmdlet returns no output.

Notes

In the case of failure, the following errors can result.

Error Codes

ProvisioningSchemeNotFound

The specified provisioning scheme could not be located.

ProvisioningSchemeNotReady

The specified provisioning scheme is not in Ready state.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Set-ProvVM

August 9, 2024

Contributed by:

August 9, 2024

Contributed by:

Set-ProvVM

Syntax

Description

Examples

EXAMPLE 1

EXAMPLE 2

EXAMPLE 3

EXAMPLE 4

EXAMPLE 5

EXAMPLE 6

Parameters

-ProvisioningSchemeName

-VMName

-VMId

-RevertToProvSchemeConfiguration

-ProvisioningSchemeUid

-CpuCount

-MemoryInMB

-CustomProperties

-ServiceOffering

-MachineProfile

-LoggingId

CitrixCommonParameters

CommonParameters

Inputs

None

Outputs

None

Notes

Related Links

In this article