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.