Citrix Virtual Apps and Desktops 2411 SDK

Set-ProvVM

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>]
Set-ProvVM -ProvisioningSchemeUid <Guid> -VMId <String> [-RevertToProvSchemeConfiguration] [-LoggingId <Guid>] [<CitrixCommonParameters>] [<CommonParameters>]
Set-ProvVM -ProvisioningSchemeUid <Guid> -VMName <String> [-CpuCount <Int32>] [-MemoryInMB <Int32>] [-CustomProperties <String>] [-ServiceOffering <String>] [-MachineProfile <String>] [-LoggingId <Guid>] [<CitrixCommonParameters>] [<CommonParameters>]
Set-ProvVM -ProvisioningSchemeUid <Guid> -VMName <String> [-RevertToProvSchemeConfiguration] [-LoggingId <Guid>] [<CitrixCommonParameters>] [<CommonParameters>]
Set-ProvVM -ProvisioningSchemeName <String> -VMId <String> [-CpuCount <Int32>] [-MemoryInMB <Int32>] [-CustomProperties <String>] [-ServiceOffering <String>] [-MachineProfile <String>] [-LoggingId <Guid>] [<CitrixCommonParameters>] [<CommonParameters>]
Set-ProvVM -ProvisioningSchemeName <String> -VMId <String> [-RevertToProvSchemeConfiguration] [-LoggingId <Guid>] [<CitrixCommonParameters>] [<CommonParameters>]
Set-ProvVM -ProvisioningSchemeName <String> -VMName <String> [-CpuCount <Int32>] [-MemoryInMB <Int32>] [-CustomProperties <String>] [-ServiceOffering <String>] [-MachineProfile <String>] [-LoggingId <Guid>] [<CitrixCommonParameters>] [<CommonParameters>]
Set-ProvVM -ProvisioningSchemeName <String> -VMName <String> [-RevertToProvSchemeConfiguration] [-LoggingId <Guid>] [<CitrixCommonParameters>] [<CommonParameters>]

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

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

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

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

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

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

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.

Set-ProvVM