Citrix Virtual Apps and Desktops SDK

Group-BrokerMachine

Groups and counts machines with the same value for a specified property.

Syntax

Group-BrokerMachine
     [[-MachineName] <String>]
     [-AgentVersion <String>]
     [-AllocationType <AllocationType>]
     [-ApplicationInUse <String>]
     [-AssignedClientName <String>]
     [-AssignedIPAddress <String>]
     [-AssignedUserSID <String>]
     [-AssociatedTenantId <Guid>]
     [-AssociatedUserFullName <String>]
     [-AssociatedUserName <String>]
     [-AssociatedUserSID <String>]
     [-AssociatedUserUPN <String>]
     [-AzureADJoinedMode <String>]
     [-AzureDeviceId <String>]
     [-BrowserName <String>]
     [-CatalogName <String>]
     [-CatalogUid <Int32>]
     [-CatalogUUID <Guid>]
     [-CbpVersion <CBPVersion>]
     [-ColorDepth <ColorDepth>]
     [-ControllerDNSName <String>]
     [-DeliveryType <DeliveryType>]
     [-Description <String>]
     [-DesktopCondition <String>]
     [-DesktopGroupName <String>]
     [-DesktopGroupUid <Int32>]
     [-DesktopGroupUUID <Guid>]
     [-DesktopKind <DesktopKind>]
     [-DesktopUid <Int32>]
     [-DNSName <String>]
     [-DrainingUntilShutdown <Boolean>]
     [-FaultState <MachineFaultState>]
     [-FunctionalLevel <FunctionalLevel>]
     [-HostedMachineId <String>]
     [-HostedMachineName <String>]
     [-HostingServerName <String>]
     [-HypervisorConnectionName <String>]
     [-HypervisorConnectionUid <Int32>]
     [-HypHypervisorConnectionUid <Guid>]
     [-IconUid <Int32>]
     [-ImageOutOfDate <Boolean>]
     [-InMaintenanceMode <Boolean>]
     [-InRegistrationSinBin <Boolean>]
     [-IPAddress <String>]
     [-IsAssigned <Boolean>]
     [-IsPhysical <Boolean>]
     [-IsReserved <Boolean>]
     [-LastAssignmentTime <DateTime>]
     [-LastConnectionFailure <ConnectionFailureReason>]
     [-LastConnectionTime <DateTime>]
     [-LastConnectionUser <String>]
     [-LastDeregistrationReason <DeregistrationReason>]
     [-LastDeregistrationTime <DateTime>]
     [-LastErrorReason <String>]
     [-LastErrorTime <DateTime>]
     [-LastHostingUpdateTime <DateTime>]
     [-LastPvdErrorReason <String>]
     [-LastPvdErrorTime <DateTime>]
     [-LastRegistrationTime <DateTime>]
     [-LoadIndex <Int32>]
     [-MacAddress <String>]
     [-MachineInternalState <MachineInternalState>]
     [-MachineUnavailableReason <String>]
     [-MaintenanceModeReason <MaintenanceModeReason>]
     [-Metadata <String>]
     [-NameLookupFailureCount <Int32>]
     [-OSType <String>]
     [-OSVersion <String>]
     [-PersistUserChanges <PersistUserChanges>]
     [-PowerActionPending <Boolean>]
     [-PowerState <PowerState>]
     [-ProvisioningMaintenanceMode <String>]
     [-ProvisioningType <ProvisioningType>]
     [-PublishedApplication <String>]
     [-PublishedName <String>]
     [-PvdEstimatedCompletionTime <DateTime>]
     [-PvdPercentDone <Int32>]
     [-PvdStage <PvdStage>]
     [-PvdUpdateStartTime <DateTime>]
     [-RegistrationState <RegistrationState>]
     [-ScheduledReboot <ScheduledReboot>]
     [-SecureIcaRequired <Boolean>]
     [-SessionAutonomouslyBrokered <Boolean>]
     [-SessionClientAddress <String>]
     [-SessionClientName <String>]
     [-SessionClientVersion <String>]
     [-SessionConnectedViaHostName <String>]
     [-SessionConnectedViaIP <String>]
     [-SessionCount <Int32>]
     [-SessionDeviceId <String>]
     [-SessionHardwareId <String>]
     [-SessionHidden <Boolean>]
     [-SessionKey <Guid>]
     [-SessionLaunchedViaHostName <String>]
     [-SessionLaunchedViaIP <String>]
     [-SessionProtocol <String>]
     [-SessionSecureIcaActive <Boolean>]
     [-SessionsEstablished <Int32>]
     [-SessionSmartAccessTag <String>]
     [-SessionsPending <Int32>]
     [-SessionStartTime <DateTime>]
     [-SessionState <SessionState>]
     [-SessionStateChangeTime <DateTime>]
     [-SessionSupport <SessionSupport>]
     [-SessionType <SessionType>]
     [-SessionUid <Int64>]
     [-SessionUserName <String>]
     [-SessionUserSID <String>]
     [-SID <String>]
     [-SummaryState <DesktopSummaryState>]
     [-SupportedPowerAction <String>]
     [-Tag <String>]
     [-UUID <Guid>]
     [-VMToolsState <VMToolsState>]
     [-WillShutdownAfterUse <Boolean>]
     [-WillShutdownAfterUseReason <WillShutdownAfterUseReason>]
     [-WindowsConnectionSetting <WindowsConnectionSetting>]
     [-ZoneHealthy <Boolean>]
     [-ZoneName <String>]
     [-ZoneUid <Guid>]
     -Property <String>
     [-ReturnTotalRecordCount]
     [-MaxRecordCount <Int32>]
     [-Skip <Int32>]
     [-SortBy <String>]
     [-Filter <String>]
     [-FilterScope <Guid>]
     [<CitrixCommonParameters>]
     [<CommonParameters>]
<!--NeedCopy-->
Group-BrokerMachine
     [-Uid] <Int32>
     -Property <String>
     [<CitrixCommonParameters>]
     [<CommonParameters>]
<!--NeedCopy-->

Description

Filters machines using the specified criteria, then groups and counts matching machines with the same value for a particular property. The number of machines in the group, and the property value for the group, is output. For example:

Group-BrokerMachine -Property SummaryState
Count Name
----- ----
   43 Available
   17 InUse
    3 Disconnected
Filtering supports the same options as the [Get-BrokerMachine](Get-BrokerMachine) cmdlet, and allows filtering on both machine and session properties.
Group-BrokerMachine is similar to the standard PowerShell Group-Object, but is faster than piping the output of [Get-BrokerMachine](Get-BrokerMachine) into Group-Object when working with many machines.
Note that the MaxRecordCount, ReturnTotalRecordCount, Skip, and SortBy parameters apply to GroupInfo records output rather than the filtered machines.
<!--NeedCopy-->

Examples

EXAMPLE 1

Group machines from the dg1 group by summary state.

Group-BrokerMachine -Property SummaryState -DesktopGroupName dg1
<!--NeedCopy-->

EXAMPLE 2

For machines where the last connection attempt failed, list the most common reason for failure, ignoring connections that failed over a week ago.

Group-BrokerMachine -Property LastConnectionFailure -Filter { LastConnectionFailure -ne "None" -and LastConnectionTime -ge '-7' } -MaxRecordCount 1
<!--NeedCopy-->

EXAMPLE 3

List alphabetically the hypervisor servers hosting machines that are currently experiencing high network latency.

Group-BrokerMachine -Property HostingServerName -DesktopCondition ICALatency -SortBy Name
<!--NeedCopy-->

Parameters

-Uid

Gets a machine with a specific UID.

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

-Property

Selects the property by which matching machines are grouped.

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

-MachineName

Gets machines with a specific machine name (in the form domain\machine).

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

-AgentVersion

Gets machines with a specific Virtual Delivery Agent version.

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

-AllocationType

Gets machines from catalogs with the specified allocation type.

Type: AllocationType
Accepted values: Permanent, Static, Random
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-ApplicationInUse

Gets machines running a specified published application. String comparisons are case-insensitive.

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

-AssignedClientName

Gets machines that have been assigned to the specific client name.

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

-AssignedIPAddress

Gets machines that have been assigned to the specific client IP address.

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

-AssignedUserSID

Gets machines with the specific SID of the user to whom the desktop is assigned.

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

-AssociatedTenantId

Gets machines associated with the specified tenant.

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

-AssociatedUserFullName

Gets machines with an associated user identified by their full name (usually ‘first-name last-name’).

Associated users are all current users of a desktop, plus the assigned users for private desktops.

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

-AssociatedUserName

Gets machines with an associated user identified by their user name (in the form ‘domain\user’).

Associated users are all current users of a desktop, plus the assigned users for private desktops.

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

-AssociatedUserSID

Gets machines with an associated user identified by their Windows SID.

Associated users are all current users of a desktop, plus the assigned users for private desktops.

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

-AssociatedUserUPN

Gets machines with an associated user identified by their User Principle Name (in the form ‘user@domain’).

Associated users are all current users of a desktop, plus the assigned users for private desktops.

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

-AzureADJoinedMode

Gets machines with a specific Azure AD Domain Join Type

  • NotAadJoined - Machine not joined to Azure AD yet.
  • HybridAadJoined - Machine was Hybrid Aad joined.
  • PureAadJoined - Machine was Pure Aad joined.
Type: String
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2112

-AzureDeviceId

Gets machines with matching Azure DeviceId.

Type: String
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2212

-BrowserName

Gets assigned machines backing desktop resources that have browser names matching the specified name.

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

-CatalogName

Gets machines from the catalog with the specific name.

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

-CatalogUid

Gets machines from the catalog with the specific UID.

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

-CatalogUUID

Gets machines from the catalog with the specific UUID.

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

-CbpVersion

The version of CBP that the VDA is currently registered with. This will be null when the VDA is not registered.

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

-ColorDepth

Gets machines configured with a specific color depth.

Valid values are FourBit, EightBit, SixteenBit, and TwentyFourBit.

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

-ControllerDNSName

Gets machines by the DNS name of the controller they are registered with.

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

-DeliveryType

Gets machines of a particular delivery type.

Valid values are AppsOnly, DesktopsOnly, DesktopsAndApps

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

-Description

Get machines by description.

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

-DesktopCondition

Gets machines with an outstanding desktop condition.

Valid values are:

  • CPU: Indicates the machine has high CPU usage
  • ICALatency: Indicates the network latency is high
  • UPMLogonTime: Indicates that the profile load time was high
Type: String
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-DesktopGroupName

Gets machines from a desktop group with the specified name.

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

-DesktopGroupUid

Gets machines from a desktop group with a specific UID.

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

-DesktopGroupUUID

Gets machines from a desktop group with a specific UUID.

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

-DesktopKind

Deprecated: Use AllocationType parameter.

Gets machines of a particular kind.

Valid values are Private, Shared.

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

-DesktopUid

Gets the machine that corresponds to the desktop with the specific UID.

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

-DNSName

Gets machines with the specific DNS name.

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

-DrainingUntilShutdown

Gets machines depending on whether they are draining until shutdown or not.

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

-FaultState

Gets machines currently in the specified fault state.

Type: MachineFaultState
Accepted values: None, FailedToStart, StuckOnBoot, Unregistered, MaxCapacity, VirtualMachineNotFound
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-FunctionalLevel

Gets machines with a specific FunctionalLevel.

Valid values are L5, L7, L7_6, L7_7, L7_8, L7_9, L7_20, L7_25

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

-HostedMachineId

Gets machines with the specific machine ID known to the hypervisor.

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

-HostedMachineName

Gets machines with the specific machine name known to the hypervisor.

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

-HostingServerName

Gets machines by the name of the hosting hypervisor server.

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

-HypervisorConnectionName

Gets machines with the specific name of the hypervisor connection hosting them.

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

-HypervisorConnectionUid

Gets machines with the specific UID of the hypervisor connection hosting them.

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

-HypHypervisorConnectionUid

Gets machines with the specific UUID of the hypervisor connection hosting them.

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

-IconUid

Gets machines by configured icon. Note that machines with a null IconUid use the icon of the desktop group.

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

-ImageOutOfDate

Gets machines depending on whether their disk image is out of date or not (for machines provisioned using MCS only).

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

-InMaintenanceMode

Gets machines by whether they are in maintenance mode or not.

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

-InRegistrationSinBin

Gets machines by whether they are currently in the registration sin bin.

Type: Boolean
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2407

-IPAddress

Gets machines with a specific IP address.

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

-IsAssigned

Gets machines according to whether they are assigned or not. Machines may be assigned to one or more users or groups, a client IP address or a client endpoint name.

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

-IsPhysical

Gets machines according to whether they can be power managed by XenDesktop or not.

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

-IsReserved

Gets machines that are reserved for special use.

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

-LastAssignmentTime

Gets machines with the specific LastAssignmentTime.

Type: DateTime
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2209

-LastConnectionFailure

Gets machines with a specific reason for the last recorded connection failure. This value is None if the last connection was successful or if there has been no attempt to connect to the machine yet.

Valid values are None, SessionPreparation, RegistrationTimeout, ConnectionTimeout, Licensing, Ticketing, and Other.

Type: ConnectionFailureReason
Accepted values: None, SessionPreparation, RegistrationTimeout, ConnectionTimeout, Licensing, Ticketing, SessionLimitReached, Other
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-LastConnectionTime

Gets machines to which a user session connection occurred at a specific time. This is the time that the broker detected that the connection attempt either succeeded or failed.

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

-LastConnectionUser

Gets machines where a specific user name last attempted a connection (in the form ‘domain\user’).

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

-LastDeregistrationReason

Gets machines whose broker last recorded a specific deregistration reason.

Valid values are $null, AgentShutdown, AgentSuspended, AgentRequested, IncompatibleVersion, AgentAddressResolutionFailed, AgentNotContactable, AgentWrongActiveDirectoryOU, EmptyRegistrationRequest, MissingRegistrationCapabilities, MissingAgentVersion, InconsistentRegistrationCapabilities, NotLicensedForFeature, UnsupportedCredentialSecurityVersion, InvalidRegistrationRequest, SingleMultiSessionMismatch, FunctionalLevelTooLowForCatalog, FunctionalLevelTooLowForDesktopGroup, PowerOff, DesktopRestart, DesktopRemoved, AgentRejectedSettingsUpdate, SendSettingsFailure, SessionAuditFailure, SessionPrepareFailure, ContactLost, SettingsCreationFailure, UnknownError and BrokerRegistrationLimitReached.

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

-LastDeregistrationTime

Gets machines by the time that they were last deregistered.

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

-LastErrorReason

Gets machines with the specified last error reason.

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

-LastErrorTime

Gets machines with the specified last error time.

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

-LastHostingUpdateTime

Gets machines with a specific time that the hosting information was last updated or the completion of the last power action.

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

-LastPvdErrorReason

This property is no longer supported.

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

-LastPvdErrorTime

This property is no longer supported.

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

-LastRegistrationTime

Gets machines by the time that they last registered.

Type: DateTime
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2012

-LoadIndex

Gets machines by their current load index.

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

-MacAddress

Gets machines with a specific MAC address.

Type: String
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2009

-MachineInternalState

Gets machines with the specified internal state.

Type: MachineInternalState
Accepted values: Available, Unavailable, FullCapacity, Pending, Unregistered, SoftRegistered, Unknown
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-MachineUnavailableReason

Gets machines that corresponds to a particular MachineUnavailable Reason

  • None - No detailed reason specified
  • LoadManagementInitializing - VDA load management logic currently initialising. Only occurs for multi-session capable VDAs.
  • GctConnectionInitializing - VDA is still initializing control connection with NGS.
  • AzureADJoinInitializing - VDA is still initializing Aad domain join.
Type: String
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2112

-MaintenanceModeReason

Gets machines by the maintenance mode reason. Valid values are:

  • None - Machine is not in maintenance mode.
  • Administrator - Machine was manually placed in maintenance mode

    by an administrator.

  • MaxFailedRegistrations - Machine was automatically placed in

    maintenance mode due to reaching the maximum failed registration limit.

Type: MaintenanceModeReason
Accepted values: None, Administrator, MaxFailedRegistrations
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2003

-Metadata

Gets records with matching metadata entries.

The value being compared with is a concatenation of the key name, a colon, and the value. For example: -Metadata “abc:x*” matches records with a metadata entry having a key name of “abc” and a value starting with the letter “x”.

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

-NameLookupFailureCount

Tracks the number of consecutive directory lookup failures for this account.

Type: Int32
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2012

-OSType

Gets machines by the type of operating system they are running.

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

-OSVersion

Gets machines by the version of the operating system they are running.

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

-PersistUserChanges

Gets machines according to the location where user changes are persisted. Values can be:

  • OnLocal - User changes are persisted locally.
  • Discard - User changes are discarded.
Type: PersistUserChanges
Accepted values: OnLocal, Discard, OnPvd
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-PowerActionPending

Gets machines depending on whether a power action is pending or not.

Valid values are $true or $false.

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

-PowerState

Gets machines with a specific power state.

Valid values are Unmanaged, Unknown, Unavailable, Off, On, Suspended, TurningOn, TurningOff, Suspending, and Resuming.

Type: PowerState
Accepted values: Unmanaged, Unknown, Unavailable, Off, On, Suspended, TurningOn, TurningOff, Suspending, Resuming, NotSupported, VirtualMachineNotFound
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-ProvisioningMaintenanceMode

VDA machine’s current Provisioning maintenance mode

Type: String
Position: Named
Default value: Unknown
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2407

-ProvisioningType

Specifies the provisioning type for the catalog. Values can be:

  • Manual - No provisioning.
  • PVS - Machine provisioned by PVS (machine may be physical, blade, VM,…).
  • MCS - Machine provisioned by MCS (machine must be VM).
Type: ProvisioningType
Accepted values: Manual, PVS, MCS
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-PublishedApplication

Gets machines with a specific application published to them (identified by its browser name).

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

-PublishedName

Gets desktops with a specific published name.

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

-PvdEstimatedCompletionTime

This property is no longer supported.

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

-PvdPercentDone

This property is no longer supported.

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

-PvdStage

This property is no longer supported.

Type: PvdStage
Accepted values: None, Requested, Starting, Working, Failed
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-PvdUpdateStartTime

This property is no longer supported.

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

-RegistrationState

Gets machines in a specific registration state.

Valid values are Unregistered, Initializing, Registered, and AgentError.

Type: RegistrationState
Accepted values: Unregistered, Initializing, Registered, AgentError
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-ScheduledReboot

Gets machines according to their current status with respect to any scheduled reboots (for either scheduled desktop group reboots or image rollout purposes). Valid values are:

  • None - No reboot currently scheduled.
  • Pending - Reboot scheduled but machine still available for use.
  • Draining - Reboot scheduled. New logons are disabled, but

    reconnections to existing sessions are allowed.

  • InProgress - Machine is actively being rebooted.
  • Natural - Natural reboot in progress. Machine is awaiting a restart.
Type: ScheduledReboot
Accepted values: None, Pending, Draining, InProgress, Natural
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-SecureIcaRequired

Gets machines configured with a particular SecureIcaRequired setting. Note that the machine setting of $null indicates that the desktop group value is used.

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

-SessionAutonomouslyBrokered

Gets machines according to whether their current session is autonomously brokered or not. Autonomously brokered sessions are HDX sessions established by direct connection without being brokered.

Session properties are always null for multi-session machines.

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

-SessionClientAddress

Gets machines with a specific client IP address.

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

-SessionClientName

Gets machines with a specific client name.

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

-SessionClientVersion

Gets machines with a specific client version.

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

-SessionConnectedViaHostName

Gets machines with a specific host name of the incoming connection. This is usually a proxy or Citrix Access Gateway server.

Session properties are always null for multi-session machines.

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

-SessionConnectedViaIP

Gets machines with a specific IP address of the incoming connection.

Session properties are always null for multi-session machines.

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

-SessionCount

Gets machines according to the total number of both pending and established user sessions on the machine.

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

-SessionDeviceId

Gets machines with a specific client device ID.

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

-SessionHardwareId

Gets machines with a specific client hardware ID.

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

-SessionHidden

Gets machines by whether their sessions are hidden or not. Hidden sessions are treated as though they do not exist when launching sessions using XenDesktop; a hidden session cannot be reconnected to, but a new session may be launched using the same entitlement.

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

-SessionKey

Gets machine running the session with the specified unique key.

Session properties are always null for multi-session machines.

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

-SessionLaunchedViaHostName

Gets machines with a specific host name of the Web Interface server from which the user launched the session.

Session properties are always null for multi-session machines.

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

-SessionLaunchedViaIP

Gets machines with a specific IP address of the Web Interface server from which the user launched the session.

Session properties are always null for multi-session machines.

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

-SessionProtocol

Gets machines with connections using a specific protocol, for example HDX, RDP, or Console.

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

-SessionSecureIcaActive

Gets machines depending on whether the current session uses SecureICA or not.

Session properties are always null for multi-session machines.

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

-SessionsEstablished

Gets machines according to the number of established user sessions present on the machine.

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

-SessionSmartAccessTag

Gets session machines where the session has the specific SmartAccess tag.

Session properties are always null for multi-session machines.

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

-SessionsPending

Get machines according to the number of pending user sessions for the machine.

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

-SessionStartTime

Gets machines with a specific session start time.

Session properties are always null for multi-session machines.

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

-SessionState

Gets machines with a specific session state.

Valid values are $null, Other, PreparingSession, Connected, Active, Disconnected, Reconnecting, NonBrokeredSession, and Unknown.

Session properties are always null for multi-session machines.

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

-SessionStateChangeTime

Gets machines whose sessions last changed state at a specific time.

Session properties are always null for multi-session machines.

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

-SessionSupport

Gets machines that have the specified session capability. Values can be:

  • SingleSession - Single-session only machine.
  • MultiSession - Multi-session capable machine.
Type: SessionSupport
Accepted values: SingleSession, MultiSession
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-SessionType

Gets machines with a specific session state.

Session properties are always null for multi-session machines.

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

-SessionUid

Gets single-session machines with a specific session UID ($null for no session).

Session properties are always null for multi-session machines.

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

-SessionUserName

Gets machines with a specific user name for the current session (in the form ‘domain\user’).

Session properties are always null for multi-session machines.

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

-SessionUserSID

Gets machines with a specific SID of the current session user.

Session properties are always null for multi-session machines.

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

-SID

Gets machines with a specific machine SID.

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

-SummaryState

Gets machines with a specific summary state.

Valid values are Off, Unregistered, Available, Disconnected, and InUse.

Type: DesktopSummaryState
Accepted values: Off, Unregistered, Available, Disconnected, InUse, Preparing
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-SupportedPowerAction

Gets machines that support the specified power action.

Type: String
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2305

-Tag

Gets machines where the session has the given SmartAccess tag.

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

-UUID

Gets machines with the specified value of UUID.

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

-VMToolsState

Gets machines with a specific VM tools state.

Valid values are NotPresent, Unknown, NotStarted, and Running.

Type: VMToolsState
Accepted values: NotPresent, Unknown, NotStarted, Running
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-WillShutdownAfterUse

Gets machines depending on whether they shut down after use or not.

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

-WillShutdownAfterUseReason

Gets machines by the will shutdown after use reason. Valid values are:

  • None - Machine will not shutdown after use.
  • ResetDiskImage - Machine will shutdown after use to reset its disk image.
  • ScheduledNaturalReboot - Machine will shutdown after use as part of the scheduled natural reboot process.
  • OnDemandNaturalReboot - Machine will shutdown after use as part of an on-demand natural reboot process.
Type: WillShutdownAfterUseReason
Accepted values: None, ResetDiskImage, ScheduledNaturalReboot, OnDemandNaturalReboot, VdaDetectedUsage
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2009

-WindowsConnectionSetting

Gets machines according to their current Windows connection setting (logon mode). Valid values are:

  • LogonEnabled - All logons are enabled.
  • Draining - New logons are disabled, but reconnections to existing

    sessions are allowed.

  • DrainingUntilRestart - Same as Draining, but setting reverts to

    LogonEnabled when machine next restarts.

  • LogonDisabled - All logons and reconnections are disabled.

This is a Windows setting and is not controlled by XenDesktop. It applies only to multi-session machines; for single-session machines its value is always LogonEnabled.

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

-ZoneHealthy

Gets machines located in the zone with the specified health state.

Type: Boolean
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2106

-ZoneName

Gets machines located in the zone with the specified name.

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

-ZoneUid

Gets machines located in the zone with the specified UID.

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

-ReturnTotalRecordCount

When specified, this causes the cmdlet to output an error record containing the number of records available. This error record is additional information and does not affect the objects written to the output pipeline. See about_Broker_Filtering for details.

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

-MaxRecordCount

Specifies the maximum number of records to return.

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

-Skip

Skips the specified number of records before returning results. Also reduces the count returned by -ReturnTotalRecordCount.

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

-SortBy

Sorts the results by the specified list of properties. The list is a set of property names separated by commas, semi-colons, or spaces. Optionally, prefix each name with a + or - to indicate ascending or descending order. Ascending order is assumed if no prefix is present.

Type: String
Position: Named
Default value: The default sort order is by name or unique identifier.
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-Filter

Gets records that match a PowerShell style filter expression. See about_Broker_Filtering for details.

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

-FilterScope

Gets only results allowed by the specified scope id.

Type: Guid
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2106

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 cannot pipe input into this cmdlet.

Outputs

Citrix.Broker.Admin.SDK.GroupInfo

Each GroupInfo object represents one group, and contains the following properties:

  • Count: The count of machines in this group.
  • Name: The value of the property the machines were grouped by (as a string).

If you do not specify -SortBy, groups are sorted with the largest count first.

Notes

To compare dates or times, use -Filter and relative comparisons. For more information, see about_Broker_Filtering and the examples.

Group-BrokerMachine