Group-Brokermachine
Groups and counts machines with the same value for a specified property.
Syntax
Group-BrokerMachine [-Uid] <Int32> -Property <String> [-AdminAddress <String>] [-BearerToken <String>] [-TraceParent <String>] [-TraceState <String>] [-VirtualSiteId <String>] [<CommonParameters>]
Group-BrokerMachine -Property <String> [[-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>] [-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>] [-IPAddress <String>] [-IsAssigned <Boolean>] [-IsPhysical <Boolean>] [-IsReserved <Boolean>] [-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>] [-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>] [-SupportedPowerActions <String[]>] [-Tag <String>] [-UUID <Guid>] [-VMToolsState <VMToolsState>] [-WillShutdownAfterUse <Boolean>] [-WillShutdownAfterUseReason <WillShutdownAfterUseReason>] [-WindowsConnectionSetting <WindowsConnectionSetting>] [-ZoneHealthy <Boolean>] [-ZoneName <String>] [-ZoneUid <Guid>] [-ReturnTotalRecordCount] [-MaxRecordCount <Int32>] [-Skip <Int32>] [-SortBy <String>] [-Filter <String>] [-FilterScope <Guid>] [-AdminAddress <String>] [-BearerToken <String>] [-TraceParent <String>] [-TraceState <String>] [-VirtualSiteId <String>] [<CommonParameters>]
<!--NeedCopy-->
Detailed 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:
C:\PS> Group-BrokerMachine -Property SummaryState
<!--NeedCopy-->
Count Name —– —- 43 Available 17 InUse 3 Disconnected
Filtering supports the same options as the 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 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.
Related Commands
Parameters
| Name | Description | Required? | Pipeline Input | Default Value |
|---|---|---|---|---|
| Uid | Gets a machine with a specific UID. | true | false | |
| Property | Selects the property by which matching machines are grouped. | true | false | |
| MachineName | Gets machines with a specific machine name (in the form domain\machine). | false | false | |
| AgentVersion | Gets machines with a specific Virtual Delivery Agent version. | false | false | |
| AllocationType | Gets machines from catalogs with the specified allocation type. | false | false | |
| ApplicationInUse | Gets machines running a specified published application. String comparisons are case-insensitive. | false | false | |
| AssignedClientName | Gets machines that have been assigned to the specific client name. | false | false | |
| AssignedIPAddress | Gets machines that have been assigned to the specific client IP address. | false | false | |
| AssignedUserSID | Gets machines with the specific SID of the user to whom the desktop is assigned. | false | false | |
| AssociatedTenantId | Gets machines associated with the specified tenant. | false | 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. | false | 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. | false | 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. | false | 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. | false | false | ||
| AzureADJoinedMode | Gets machines with a specific Azure AD Domain Join Type o NotAadJoined - Machine not joined to Azure AD yet. |
o HybridAadJoined - Machine was Hybrid Aad joined.
o PureAadJoined - Machine was Pure Aad joined. | false | false | |
| BrowserName | Gets assigned machines backing desktop resources that have browser names matching the specified name. | false | false | |
| CatalogName | Gets machines from the catalog with the specific name. | false | false | |
| CatalogUid | Gets machines from the catalog with the specific UID. | false | false | |
| CatalogUUID | Gets machines from the catalog with the specific UUID. | false | false | |
| CbpVersion | The version of CBP that the VDA is currently registered with. This will be null when the VDA is not registered. | false | false | |
| ColorDepth | Gets machines configured with a specific color depth.
Valid values are FourBit, EightBit, SixteenBit, and TwentyFourBit. | false | false | |
| ControllerDNSName | Gets machines by the DNS name of the controller they are registered with. | false | false | |
| DeliveryType | Gets machines of a particular delivery type.
Valid values are AppsOnly, DesktopsOnly, DesktopsAndApps | false | false | |
| Description | Get machines by description. | false | false | |
| DesktopCondition | Gets machines with an outstanding desktop condition.
Valid values are:
o CPU: Indicates the machine has high CPU usage
o ICALatency: Indicates the network latency is high
o UPMLogonTime: Indicates that the profile load time was high | false | false | |
| DesktopGroupName | Gets machines from a desktop group with the specified name. | false | false | |
| DesktopGroupUid | Gets machines from a desktop group with a specific UID. | false | false | |
| DesktopGroupUUID | Gets machines from a desktop group with a specific UUID. | false | false | |
| DesktopKind | Deprecated: Use AllocationType parameter.
Gets machines of a particular kind.
Valid values are Private, Shared. | false | false | |
| DesktopUid | Gets the machine that corresponds to the desktop with the specific UID. | false | false | |
| DNSName | Gets machines with the specific DNS name. | false | false | |
| DrainingUntilShutdown | Gets machines depending on whether they are draining until shutdown or not. | false | false | |
| FaultState | Gets machines currently in the specified fault state. | false | 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 | false | false | |
| HostedMachineId | Gets machines with the specific machine ID known to the hypervisor. | false | false | |
| HostedMachineName | Gets machines with the specific machine name known to the hypervisor. | false | false | |
| HostingServerName | Gets machines by the name of the hosting hypervisor server. | false | false | |
| HypervisorConnectionName | Gets machines with the specific name of the hypervisor connection hosting them. | false | false | |
| HypervisorConnectionUid | Gets machines with the specific UID of the hypervisor connection hosting them. | false | false | |
| HypHypervisorConnectionUid | Gets machines with the specific UUID of the hypervisor connection hosting them. | false | false | |
| IconUid | Gets machines by configured icon. Note that machines with a null IconUid use the icon of the desktop group. | false | false | |
| ImageOutOfDate | Gets machines depending on whether their disk image is out of date or not (for machines provisioned using MCS only). | false | false | |
| InMaintenanceMode | Gets machines by whether they are in maintenance mode or not. | false | false | |
| IPAddress | Gets machines with a specific IP address. | false | 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. | false | false | |
| IsPhysical | Gets machines according to whether they can be power managed by XenDesktop or not. | false | false | |
| IsReserved | Gets machines that are reserved for special use, for example, for AppDisk preparation. | false | false | |
| 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. | false | 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. | false | false | |
| LastConnectionUser | Gets machines where a specific user name last attempted a connection (in the form ‘domain\user’). | false | 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. | false | false | |
| LastDeregistrationTime | Gets machines by the time that they were last deregistered. | false | false | |
| LastErrorReason | Gets machines with the specified last error reason. | false | false | |
| LastErrorTime | Gets machines with the specified last error time. | false | false | |
| LastHostingUpdateTime | Gets machines with a specific time that the hosting information was last updated. | false | false | |
| LastPvdErrorReason | This property is no longer supported. | false | false | |
| LastPvdErrorTime | This property is no longer supported. | false | false | |
| LastRegistrationTime | Gets machines by the time that they last registered. | false | false | |
| LoadIndex | Gets machines by their current load index. | false | false | |
| MacAddress | Gets machines with a specific MAC address. | false | false | |
| MachineInternalState | Gets machines with the specified internal state. | false | false | |
| MachineUnavailableReason | Gets machines that corresponds to a particular MachineUnavailable Reason o None - No detailed reason specified
o LoadManagementInitializing - VDA load management logic currently initialising. Only occurs for multi-session capable VDAs.
o GctConnectionInitializing - VDA is still initializing control connection with NGS.
o AzureADJoinInitializing - VDA is still initializing Aad domain join. | false | false | |
| MaintenanceModeReason | Gets machines by the maintenance mode reason. Valid values are:
o None - Machine is not in maintenance mode.
o Administrator - Machine was manually placed in maintenance mode by an administrator.
o MaxFailedRegistrations - Machine was automatically placed in maintenance mode due to reaching the maximum failed registration limit. | false | false | |
| 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". | false | false | |
| NameLookupFailureCount | Tracks the number of consecutive directory lookup failures for this account. | false | false | |
| OSType | Gets machines by the type of operating system they are running. | false | false | |
| OSVersion | Gets machines by the version of the operating system they are running. | false | false | |
| PersistUserChanges | Gets machines according to the location where user changes are persisted. Values can be:
o OnLocal - User changes are persisted locally.
o Discard - User changes are discarded. | false | false | |
| PowerActionPending | Gets machines depending on whether a power action is pending or not.
Valid values are $true or $false. | false | false | |
| PowerState | Gets machines with a specific power state.
Valid values are Unmanaged, Unknown, Unavailable, Off, On, Suspended, TurningOn, TurningOff, Suspending, and Resuming. | false | false | |
| ProvisioningType | Specifies the provisioning type for the catalog. Values can be:
o Manual - No provisioning.
o PVS - Machine provisioned by PVS (machine may be physical, blade, VM,…).
o MCS - Machine provisioned by MCS (machine must be VM). | false | false | |
| PublishedApplication | Gets machines with a specific application published to them (identified by its browser name). | false | false | |
| PublishedName | Gets desktops with a specific published name. | false | false | |
| PvdEstimatedCompletionTime | This property is no longer supported. | false | false | |
| PvdPercentDone | This property is no longer supported. | false | false | |
| PvdStage | This property is no longer supported. | false | false | |
| PvdUpdateStartTime | This property is no longer supported. | false | false | |
| RegistrationState | Gets machines in a specific registration state.
Valid values are Unregistered, Initializing, Registered, and AgentError. | false | 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:
o None - No reboot currently scheduled.
o Pending - Reboot scheduled but machine still available for use.
o Draining - Reboot scheduled. New logons are disabled, but reconnections to existing sessions are allowed.
o InProgress - Machine is actively being rebooted.
o Natural - Natural reboot in progress. Machine is awaiting a restart. | false | 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. | false | 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. | false | false | |
| SessionClientAddress | Gets machines with a specific client IP address. | false | false | |
| SessionClientName | Gets machines with a specific client name. | false | false | |
| SessionClientVersion | Gets machines with a specific client version. | false | 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. | false | false | |
| SessionConnectedViaIP | Gets machines with a specific IP address of the incoming connection.
Session properties are always null for multi-session machines. | false | false | |
| SessionCount | Gets machines according to the total number of both pending and established user sessions on the machine. | false | false | |
| SessionDeviceId | Gets machines with a specific client device ID. | false | false | |
| SessionHardwareId | Gets machines with a specific client hardware ID. | false | 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. | false | false | |
| SessionKey | Gets machine running the session with the specified unique key.
Session properties are always null for multi-session machines. | false | 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. | false | 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. | false | false | |
| SessionProtocol | Gets machines with connections using a specific protocol, for example HDX, RDP, or Console. | false | false | |
| SessionSecureIcaActive | Gets machines depending on whether the current session uses SecureICA or not.
Session properties are always null for multi-session machines. | false | false | |
| SessionsEstablished | Gets machines according to the number of established user sessions present on the machine. | false | false | |
| SessionSmartAccessTag | Gets session machines where the session has the specific SmartAccess tag.
Session properties are always null for multi-session machines. | false | false | |
| SessionsPending | Get machines according to the number of pending user sessions for the machine. | false | false | |
| SessionStartTime | Gets machines with a specific session start time.
Session properties are always null for multi-session machines. | false | 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. | false | false | |
| SessionStateChangeTime | Gets machines whose sessions last changed state at a specific time.
Session properties are always null for multi-session machines. | false | false | |
| SessionSupport | Gets machines that have the specified session capability. Values can be:
o SingleSession - Single-session only machine.
o MultiSession - Multi-session capable machine. | false | false | |
| SessionType | Gets machines with a specific session state.
Session properties are always null for multi-session machines. | false | false | |
| SessionUid | Gets single-session machines with a specific session UID ($null for no session).
Session properties are always null for multi-session machines. | false | 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. | false | false | |
| SessionUserSID | Gets machines with a specific SID of the current session user.
Session properties are always null for multi-session machines. | false | false | |
| SID | Gets machines with a specific machine SID. | false | false | |
| SummaryState | Gets machines with a specific summary state.
Valid values are Off, Unregistered, Available, Disconnected, and InUse. | false | false | |
| SupportedPowerActions | A list of power actions supported by this machine. | false | false | |
| Tag | Gets machines where the session has the given SmartAccess tag. | false | false | |
| UUID | Gets machines with the specified value of UUID. | false | false | |
| VMToolsState | Gets machines with a specific VM tools state.
Valid values are NotPresent, Unknown, NotStarted, and Running. | false | false | |
| WillShutdownAfterUse | Gets machines depending on whether they shut down after use or not. | false | false | |
| WillShutdownAfterUseReason | Gets machines by the will shutdown after use reason. Valid values are:
o None - Machine will not shutdown after use.
o ResetDiskImage - Machine will shutdown after use to reset its disk image.
o ScheduledNaturalReboot - Machine will shutdown after use as part of the scheduled natural reboot process.
o OnDemandNaturalReboot - Machine will shutdown after use as part of an on-demand natural reboot process. | false | false | |
| WindowsConnectionSetting | Gets machines according to their current Windows connection setting (logon mode). Valid values are:
o LogonEnabled - All logons are enabled.
o Draining - New logons are disabled, but reconnections to existing sessions are allowed.
o DrainingUntilRestart - Same as Draining, but setting reverts to LogonEnabled when machine next restarts.
o 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. | false | false | |
| ZoneHealthy | Gets machines located in the zone with the specified health state. | false | false | |
| ZoneName | Gets machines located in the zone with the specified name. | false | false | |
| ZoneUid | Gets machines located in the zone with the specified UID. | false | 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](/en-us/citrix-virtual-apps-desktops-sdk/2112/Broker/about_Broker_Filtering.html) for details. | false | false | False |
| MaxRecordCount | Specifies the maximum number of records to return. | false | false | 250 |
| Skip | Skips the specified number of records before returning results. Also reduces the count returned by -ReturnTotalRecordCount. | false | false | 0 |
| 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. | false | false | The default sort order is by name or unique identifier. |
| Filter | Gets records that match a PowerShell style filter expression. See [about_Broker_Filtering](/en-us/citrix-virtual-apps-desktops-sdk/2112/Broker/about_Broker_Filtering.html) for details. | false | false | |
| FilterScope | Gets only results allowed by the specified scope id. | false | false | |
| AdminAddress | 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. | false | false | Localhost. Once a value is provided by any cmdlet, this value will become the default. |
| BearerToken | Specifies the bearer token assigned to the calling user | false | false | |
| TraceParent | Specifies the trace parent assigned for internal diagnostic tracing use | false | false | |
| TraceState | Specifies the trace state assigned for internal diagnostic tracing use | false | false | |
| VirtualSiteId | Specifies the virtual site the PowerShell snap-in will connect to. | false | false | |
Input Type
None
You cannot pipe input into this cmdlet.
Return Values
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.
Examples
Example 1
C:\PS> Group-BrokerMachine -Property SummaryState -DesktopGroupName dg1
<!--NeedCopy-->
Description
Group machines from the dg1 group by summary state.
Example 2
C:\PS> Group-BrokerMachine -Property LastConnectionFailure -Filter { LastConnectionFailure -ne "None" -and LastConnectionTime -ge '-7' } -MaxRecordCount 1
<!--NeedCopy-->
Description
For machines where the last connection attempt failed, list the most common reason for failure, ignoring connections that failed over a week ago.
Example 3
C:\PS> Group-BrokerMachine -Property HostingServerName -DesktopCondition ICALatency -SortBy Name
<!--NeedCopy-->
Description
List alphabetically the hypervisor servers hosting machines that are currently experiencing high network latency.