Product Documentation


Sep 29, 2015

Creates a new action in the power action queue.


New-BrokerHostingPowerAction [-MachineName] <String> -Action <PowerManagementAction> [-ActualPriority <Int32>] [-LoggingId <Guid>] [-AdminAddress <String>] [<CommonParameters>]

Detailed Description

The New-BrokerHostingPowerAction cmdlet adds a new power action record into the queue of power actions to be performed. The power actions in the queue are processed on a priority basis and sent to the relevant hypervisor to change the power state of a virtual machine.

A power action record defines the action to be performed, the machine on which the action is to be performed, and an initial priority value for the action. Multiple actions may be created that relate to the same machine.

For a detailed description of the queuing mechanism, see 'help about_Broker_PowerManagement'.



Specifies the machine that the action is to be performed on.

The machine can be identified by DNS name or short name or SID or 'machine\domain' form name.

Required? true
Default Value  
Accept Pipeline Input? true (ByPropertyName)


Specifies the power state change action that is to be performed on the specified machine.

Valid values are: TurnOn, TurnOff, ShutDown, Reset, Restart, Suspend and Resume.

Required? true
Default Value  
Accept Pipeline Input? true (ByPropertyName)


Specifies an initial priority value for the action in the queue.

This priority is the current action priority; the 'base' priority for actions created via this cmdlet is always 30. Numerically lower priority values indicate more important actions that are processed in preference to actions with numerically higher priority settings.

Required? false
Default Value 30
Accept Pipeline Input? true (ByPropertyName)


Specifies the identifier of the high level operation that this cmdlet call forms a part of. Desktop Studio and Desktop 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.

Required? false
Default Value  
Accept Pipeline Input? false


Specifies the address of a XenDesktop controller that the PowerShell snapin will connect to. This can be provided as a host name or an IP address.

Required? false
Default Value Localhost. Once a value is provided by any cmdlet, this value will become the default.
Accept Pipeline Input? false

Input Type

None You cannot pipe input into this cmdlet.

Return Values


New-BrokerHostingPowerAction returns the newly created power action record.


-------------------------- EXAMPLE 1 --------------------------

C:\PS> New-BrokerHostingPowerAction -Action Shutdown -MachineName 'XD_VDA1'

Causes the machine called 'XD_VDA1' to be shut down.