Citrix Virtual Apps and Desktops SDK

New-BrokerMachineCommand

Creates a new command to deliver to a desktop.

Syntax

New-BrokerMachineCommand
   -Category <String>
   -CommandName <String>
   [-CommandData <Byte[]>]
   [-DesktopGroups <DesktopGroup[]>]
   [-SendTrigger <MachineCommandTrigger>]
   -User <String>
   [-SendDeadline <TimeSpan>]
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-BrokerMachineCommand
   -Category <String>
   -CommandName <String>
   [-CommandData <Byte[]>]
   [-SendTrigger <MachineCommandTrigger>]
   -MachineUid <Int32>
   [-SendDeadline <TimeSpan>]
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-BrokerMachineCommand
   -Category <String>
   -CommandName <String>
   [-CommandData <Byte[]>]
   [-SendTrigger <MachineCommandTrigger>]
   -SessionUid <Int64>
   [-SendDeadline <TimeSpan>]
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-BrokerMachineCommand
   -Category <String>
   -CommandName <String>
   [-CommandData <Byte[]>]
   [-Synchronous]
   -MachineUid <Int32>
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Description

Create a new command queued for delivery to a desktop. Commands are sent to a specific handler installed on the desktop using the Category parameter. Each handler has its own list of commands identified by the CommandName parameter. Optional command data can be provided using the CommandData parameter in a format specified by the handler.

Commands are targeted at a specific user, session or machine. Commands targeted at a user can be further be restricted to one or more desktop groups.

The SendTrigger is used to restrict the command to a specific event related to the target. For example, when the target machine registers or when the target user reconnects to a session. The command will be sent to the machine when the SendTrigger occurs for the target.

If the Synchronous switch is provided, the target must be a machine and no SendTrigger can be specified. The command is sent immediately to the machine if it is currently registered and fails if the machine is not registered.

Note that the combined length of the Category and CommandName is limited to 64 characters. The Category and CommandName must both be entirely alphanumeric and not include any white space.

Examples

EXAMPLE 1

Instruct the User Profile Manager service to execute the “ResetUpmProfile” command using the encoded $byteArray command data when user domain1\user1 logs on to any machine in desktop group 1

New-BrokerMachineCommand -Category UserProfileManager -CommandName "ResetUpmProfile" -DesktopGroups 1 -CommandData $byteArray -SendTrigger logon -user domain1\user1
<!--NeedCopy-->

EXAMPLE 2

Instruct the monitor service to immediately execute the “EnableLogging” command on the machine having Uid 13.

New-BrokerMachineCommand -Synchronous -Category "MonitorService" -CommandName "EnableLogging" -MachineUid 13
<!--NeedCopy-->

Parameters

-Category

The service on the desktop to send the command to.

Type: String
Position: Named
Default value: None
Required: True
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: True

-CommandName

The name of the command to send (as defined by the service).

Type: String
Position: Named
Default value: None
Required: True
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: True

-User

User whose desktop or session should receive the command.

Type: String
Position: Named
Default value: Any user.
Required: True
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: True

-MachineUid

Specific machine that should receive the command.

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

-SessionUid

Currently logged on user session that should receive the command.

Type: Int64
Position: Named
Default value: Any session.
Required: True
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-Synchronous

Send the command immediately and block while waiting for the reply.

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

-CommandData

Optional additional data to include with the command.

Type: Byte[]
Position: Named
Default value: None
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-LoggingId

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.

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

-DesktopGroups

Further restrict the command targeted at a user to machines in these desktop groups.

Type: DesktopGroup[]
Position: Named
Default value: No restriction by desktop group.
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-SendTrigger

Queue command for delivery until this particular event occurs. Valid values are NextContact, Broker, LogOn, Logoff, Disconnect and Reconnect.

Type: MachineCommandTrigger
Position: Named
Default value: Default value is ‘NextContact’ so the command is sent during the next communication with the desktop.
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-SendDeadline

Automatically cancel the command if it not delivered before the specified time span passes.

Type: TimeSpan
Position: Named
Default value: Command expires after 24 hours.
Required: False
Accept pipeline input: True (ByPropertyName)
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

No parameter is accepted from the input pipeline.

Outputs

Citrix.Broker.Admin.SDK.MachineCommand

New command that was added to the command queue.

Citrix.Broker.Admin.SDK.MachineSynchronousCommandResponse

When the Synchronous option is used, the command is immediately sent to the specified machine and processed. The SDK object returned describes the command and the result of this command processing.

Notes

Commands are subject to delegated administration restrictions based on the desktop group, category and command name.

New-BrokerMachineCommand