Citrix Virtual Apps and Desktops SDK

Get-BrokerDesktop

Gets desktops configured for this site.

Syntax

Get-BrokerDesktop
   [[-MachineName] <String>]
   [-AgentVersion <String>]
   [-ApplicationInUse <String>]
   [-AssignedClientName <String>]
   [-AssignedIPAddress <String>]
   [-AssociatedUserFullName <String>]
   [-AssociatedUserName <String>]
   [-AssociatedUserUPN <String>]
   [-AutonomouslyBrokered <Boolean>]
   [-CatalogName <String>]
   [-CatalogUid <Int32>]
   [-ClientAddress <String>]
   [-ClientName <String>]
   [-ClientVersion <String>]
   [-ColorDepth <ColorDepth>]
   [-ConnectedViaHostName <String>]
   [-ConnectedViaIP <String>]
   [-ControllerDNSName <String>]
   [-DeliveryType <DeliveryType>]
   [-Description <String>]
   [-DesktopCondition <String>]
   [-DesktopGroupName <String>]
   [-DesktopGroupUid <Int32>]
   [-DesktopKind <DesktopKind>]
   [-DeviceId <String>]
   [-DNSName <String>]
   [-FunctionalLevel <FunctionalLevel>]
   [-HardwareId <String>]
   [-HostedMachineId <String>]
   [-HostedMachineName <String>]
   [-HostingServerName <String>]
   [-HypervisorConnectionName <String>]
   [-HypervisorConnectionUid <Int32>]
   [-IconUid <Int32>]
   [-ImageOutOfDate <Boolean>]
   [-InMaintenanceMode <Boolean>]
   [-IPAddress <String>]
   [-IsAssigned <Boolean>]
   [-IsPhysical <Boolean>]
   [-LastConnectionFailure <ConnectionFailureReason>]
   [-LastConnectionTime <DateTime>]
   [-LastConnectionUser <String>]
   [-LastDeregistrationReason <DeregistrationReason>]
   [-LastDeregistrationTime <DateTime>]
   [-LastErrorReason <String>]
   [-LastErrorTime <DateTime>]
   [-LastHostingUpdateTime <DateTime>]
   [-LaunchedViaHostName <String>]
   [-LaunchedViaIP <String>]
   [-MachineInternalState <MachineInternalState>]
   [-MachineUid <Int32>]
   [-OSType <String>]
   [-OSVersion <String>]
   [-PersistUserChanges <PersistUserChanges>]
   [-PowerActionPending <Boolean>]
   [-PowerState <PowerState>]
   [-Protocol <String>]
   [-ProvisioningType <ProvisioningType>]
   [-PublishedApplication <String>]
   [-PublishedName <String>]
   [-PvdStage <PvdStage>]
   [-RegistrationState <RegistrationState>]
   [-SecureIcaActive <Boolean>]
   [-SecureIcaRequired <Boolean>]
   [-SessionHidden <Boolean>]
   [-SessionId <Int32>]
   [-SessionState <SessionState>]
   [-SessionStateChangeTime <DateTime>]
   [-SessionUid <Int64>]
   [-SessionUserName <String>]
   [-SessionUserSID <String>]
   [-SID <String>]
   [-SmartAccessTag <String>]
   [-StartTime <DateTime>]
   [-SummaryState <DesktopSummaryState>]
   [-Tag <String>]
   [-WillShutdownAfterUse <Boolean>]
   [-ApplicationUid <Int32>]
   [-Property <String[]>]
   [-ReturnTotalRecordCount]
   [-MaxRecordCount <Int32>]
   [-Skip <Int32>]
   [-SortBy <String>]
   [-Filter <String>]
   [-FilterScope <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
Get-BrokerDesktop
   [-Uid] <Int32>
   [-Property <String[]>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Description

This cmdlet is now deprecated, please use Get-BrokerMachine.

Retrieves desktops matching the specified criteria. If no parameters are specified this cmdlet enumerates all desktops.

Get-BrokerDesktop returns objects that combine desktop configuration and state information.

For single-session desktops, session information is displayed if present. It is possible that there are more than one sessions present on single-session desktops if ‘fast user switching’ is enabled, this cmdlet will prefer to return information about brokered sessions (rather than, for example, unbrokered direct RDP sessions). If there is no session running, session related fields return $null.

For multi-session desktops, no session information is ever displayed by this cmdlet, so session related fields always return $null. Get-BrokerSession can be used to get information about sessions on both multi-session and single-session desktops.

To count desktops, rather than retrieve full details of each desktop, use Group-BrokerDesktop instead.

For information about advanced filtering options, see about_Broker_Filtering; for information about desktops, see about_Broker_Desktops.

————————– BrokerDesktop Object

The desktop object returned represents a physical or virtual machine configured in the site that is able to run either a Microsoft Windows desktop environment, individual applications, or both.

  • AgentVersion (System.String)

    Version of the Citrix Virtual Delivery Agent (VDA) installed on the desktop.

  • ApplicationsInUse (System.String[])

    List of applications in use on the desktop (in the form of browser name).

  • AssignedClientName (System.String)

    The name of the endpoint client device that the desktop has been assigned to.

  • AssignedIPAddress (System.String)

    The IP address of the endpoint client device that the desktop has been assigned to.

  • AssociatedUserFullNames (System.String[])

    Full names of the users that have been associated with the desktop (in the form “Firstname Lastname”). Associated users are the current user(s) for shared desktops and the assigned users for private desktops.

  • AssociatedUserNames (System.String[])

    Usernames of the users that have been associated with the desktop (usually in the form “domain\user”). Associated users are the current user(s) for shared desktops and the assigned users for private desktops.

  • AssociatedUserUPNs (System.String[])

    The user principal names of the users that have been associated with the desktop (in the form user@upndomain.com). Associated users are the current user(s) for shared desktops and the assigned users for private desktops.

  • AutonomouslyBrokered (System.Boolean?)

    Session property indicating if the current session is an HDX session established by direct connection without being brokered. Session properties are always null for multi-session desktops.

  • CatalogName (System.String)

    Name of the catalog the desktop is a member of.

  • CatalogUid (System.Int32)

    UID of the catalog the desktop is a member of.

  • ClientAddress (System.String)

    Session property indicating the IP address of the client connected to the desktop. Session properties are always null for multi-session desktops.

  • ClientName (System.String)

    Session property indicating the host name of the client connected to the desktop. Session properties are always null for multi-session desktops.

  • ClientVersion (System.String)

    Session property indicating the version of the Citrix Receiver running on the connected client. Session properties are always null for multi-session desktops.

  • ColorDepth (Citrix.Broker.Admin.SDK.ColorDepth?)

    The color depth setting configured on the desktop, possible values are: $null, FourBit, EightBit, SixteenBit, and TwentyFourBit.

  • ConnectedViaHostName (System.String)

    Session property indicating the host name of the connection gateway, router or client. Session properties are always null for multi-session desktops.

  • ConnectedViaIP (System.String)

    Session property indicating the IP address of the connection gateway, router or client. Session properties are always null for multi-session desktops.

  • ControllerDNSName (System.String)

    The DNS host name of the controller that the desktop is registered to.

  • DeliveryType (Citrix.Broker.Admin.SDK.DeliveryType)

    Denotes whether the desktop delivers desktops only, apps only or both.

  • Description (System.String)

    Description of the desktop.

  • DesktopConditions (System.String[])

    List of outstanding desktop conditions for the desktop.

  • DesktopGroupName (System.String)

    Name of the desktop group the desktop has been assigned to.

  • DesktopGroupUid (System.Int32)

    Uid of the desktop group the desktop has been assigned to.

  • DesktopKind (Citrix.Broker.Admin.SDK.DesktopKind)

    Denotes whether the desktop is private or shared.

  • DeviceId (System.String)

    Session property indicating a unique identifier for the client device that has most recently been associated with the current session. Session properties are always null for multi-session desktops.

  • DNSName (System.String)

    The DNS host name of the desktop.

  • FunctionalLevel (Citrix.Broker.Admin.SDK.FunctionalLevel?)

    The functional level of the desktop, if known.

  • HardwareId (System.String)

    Session property indicating a unique identifier for the client hardware that has been most recently associated with the current session. Session properties are always null for multi-sesison desktops.

  • HostedMachineId (System.String)

    Unique ID within the hosting unit of the target managed desktop.

  • HostedMachineName (System.String)

    The friendly name of a hosted desktop as used by its hypervisor. This is not necessarily the DNS name of the desktop.

  • HostingServerName (System.String)

    DNS name of the hypervisor that is hosting the desktop if managed.

  • HypervisorConnectionName (System.String)

    The name of the hypervisor connection that the desktop’s hosting server is accessed through, if managed.

  • HypervisorConnectionUid (System.Int32?)

    The UID of the hypervisor connection that the desktop’s hosting server is accessed through, if managed.

  • IconUid (System.Int32?)

    The UID of the desktop’s icon that is displayed in StoreFront.

  • ImageOutOfDate (System.Boolean?)

    Denotes whether the VM image for a hosted desktop is out of date.

  • InMaintenanceMode (System.Boolean)

    Denotes whether the desktop is in maintenance mode.

  • IPAddress (System.String)

    The IP address of the desktop.

  • IsAssigned (System.Boolean)

    Denotes whether a private desktop has been assigned to a user/users, or a client name/address. Users can be assigned explicitly or by assigning on first use of the desktop.

  • IsPhysical (System.Boolean)

    This value is true if the desktop is physical(ie not power managed by the Citrix Broker Service), and false otherwise.

  • LastConnectionFailure (Citrix.Broker.Admin.SDK.ConnectionFailureReason)

    The reason for the last failed connection between a client and the desktop.

  • LastConnectionTime (System.DateTime?)

    Time of the last detected connection attempt that either failed or succeeded.

  • LastConnectionUser (System.String)

    The SAM name (in the form DOMAIN\user) of the user that last attempted a connection with the desktop. If the SAM name is not available, the SID is used.

  • LastDeregistrationReason (Citrix.Broker.Admin.SDK.DeregistrationReason?)

    The reason for the last deregistration of the desktop with the broker. Possible values are: 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.

  • LastDeregistrationTime (System.DateTime?)

    Time of the last deregistration of the desktop from the controller.

  • LastErrorReason (System.String)

    The reason for the last error detected in the desktop.

  • LastErrorTime (System.DateTime?)

    The time of the last detected error.

  • LastHostingUpdateTime (System.DateTime?)

    Time of last update to any hosting data (such as power state) for this desktop reported by the hypervisor connection.

  • LaunchedViaHostName (System.String)

    Session property that denotes the host name of the StoreFront server used to launch the current brokered session. Session properties are always null for multi-session desktops.

  • LaunchedViaIP (System.String)

    Session property that denotes the IP address of the StoreFront server used to launch the current brokered session. Session properties are always null for multi-session desktops.

  • MachineInternalState (Citrix.Broker.Admin.SDK.MachineInternalState)

    The internal state of the machine associated with the desktop; reported while the desktop is registered to a controller, plus some private Citrix Broker Service states while the machine is not registered.

  • MachineName (System.String)

    DNS host name of the machine associated with the desktop.

  • MachineUid (System.Int32)

    Uid of the associated machine.

  • OSType (System.String)

    A string that can be used to identify the operating system that is running on the desktop.

  • OSVersion (System.String)

    A string that can be used to identify the version of the operating system running on the desktop, if known

  • PersistUserChanges (Citrix.Broker.Admin.SDK.PersistUserChanges)

    Describes whether/how the user changes are persisted. Possible values are:

    • OnLocal - Persist the user changes on the local disk of the desktop.
    • Discard - Discard user changes.
  • PowerActionPending (System.Boolean)

    Property indicating whether there are any pending power actions for the desktop.

  • PowerState (Citrix.Broker.Admin.SDK.PowerState)

    The current power state of the desktop. Possible values are: Unmanaged, Unknown, Unavailable, Off, On, Suspended, TurningOn, TurningOff, Suspending, resuming.

  • Protocol (System.String)

    Session property that denotes the protocol that the current session is using, can be either HDX, RDP or Console. Console sessions on XenDesktop 5 VDAs appear with a blank protocol. Session properties are always null for multi-session desktops.

  • ProvisioningType (Citrix.Broker.Admin.SDK.ProvisioningType)

    Describes how the machine associated with the desktop was provisioned, possible values are: Manual: No automated provisioning.PVS: Machine provisioned by PVS (may be physical, blade, VM,…)MCS: Machine provisioned by MCS (machine must be VM)

  • PublishedApplications (System.String[])

    List of applications published by the desktop (displayed as browser names).

  • PublishedName (System.String)

    The name of the desktop that is displayed in StoreFront, if the desktop is published.

  • PvdStage (Citrix.Broker.Admin.SDK.PvdStage)

    This property is no longer supported.

  • RegistrationState (Citrix.Broker.Admin.SDK.RegistrationState)

    Indicates the registration state of the desktop. Possible values are: Unregistered, Initializing, Registered, AgentError.

  • SecureIcaActive (System.Boolean?)

    Session property that indicates whether SecureICA is active on the current session. Session properties are always null for multi-session desktops.

  • SecureIcaRequired (System.Boolean?)

    Flag indicating whether SecureICA is required or not when starting a session on the desktop.

  • SessionHidden (System.Boolean?)

    Session property that indicates if a session is hidden. Session properties are always null for multi-session desktops.

  • SessionId (System.Int32?)

    Deprecated. A unique identifier that Remote Desktop Services uses to track the session but it is only unique on that machine and only unique at any one particular time.

  • SessionState (Citrix.Broker.Admin.SDK.SessionState?)

    Session property indicating the state of the current session. Session properties are always null for multi-session desktops, possible values are: Other, PreparingSession, Connected, Active, Disconnected, Reconnecting, NonBrokeredSession and Unknown.

  • SessionStateChangeTime (System.DateTime?)

    Session property indicating the time of the last state change of the current session. Session properties are always null for multi-session desktops.

  • SessionUid (System.Int64?)

    Session property indicating the UID of the current session. Session properties are always null for multi-session desktops.

  • SessionUserName (System.String)

    Session property indicates the name of the current sessions’ user (in the form DOMAIN\user). Session properties are always null for multi-session desktops.

  • SessionUserSID (System.String)

    Session property indicates the SID of the current sessions’ user. Session properties are always null for multi-session desktops.

  • SID (System.String)

    The SID of the desktop.

  • SmartAccessTags (System.String[])

    Session property that indicates the Smart Access tags for the current session. Session properties are always null on multi-session desktops.

  • StartTime (System.DateTime?)

    Session property that indicates the start time of the current session. Session properties are always null on multi-session desktops.

  • SummaryState (Citrix.Broker.Admin.SDK.DesktopSummaryState)

    Indicates the overall state of the desktop. The overall state is a result of other more specific states such as session state, registration state and power state. Possible values: Off, Unregistered, Available, Disconnected, InUse, Preparing.

  • Tags (System.String[])

    A list of tags for the desktop.

  • Uid (System.Int32)

    UID of the desktop object.

  • WillShutdownAfterUse (System.Boolean)

    Flag indicating whether this desktop is tainted and will be shut down after all sessions on the desktop have ended. This flag should only ever be true on power managed, single-session desktops. Note: The desktop will not shut down if it is in maintenance mode, but will shut down after the desktop is taken out of maintenance mode.

Examples

EXAMPLE 1

Both commands retrieve desktops that are unregistered. The second command also includes desktops with a registration state of AgentError.

Get-BrokerDesktop -RegistrationState Unregistered
Get-BrokerDesktop -Filter { RegistrationState -ne 'Registered' }
<!--NeedCopy-->

EXAMPLE 2

Gets desktops without sessions, listing the DNS name and current state.

Get-BrokerDesktop -SessionUid $null | ft -a DNSName,SummaryState
<!--NeedCopy-->

EXAMPLE 3

Finds all Windows XP desktops with an out-of-date image.

Get-BrokerDesktop -Filter { OSType -like "Windows XP*" -and ImageOutOfDate }
<!--NeedCopy-->

EXAMPLE 4

Gets desktops running a published PowerPoint application. It matches any application browser name containing the word ‘powerpoint’. String comparisons are case-insensitive.

Get-BrokerDesktop -ApplicationInUse '*powerpoint*'
<!--NeedCopy-->

EXAMPLE 5

Finds all desktops with an outstanding desktop condition, listing the affected desktop and user.

Get-BrokerDesktop -DesktopCondition * DNSName,SessionUserName,DesktopConditions
<!--NeedCopy-->

EXAMPLE 6

Finds users who have been logged on for more than a day, and outputs the machine name, start time, and duration the session has been logged on.

$d = (Get-Date).AddDays(-1)
Get-BrokerDesktop -Filter { StartTime -le $d } | ft MachineName,SessionUserName,StartTime,@{Label='Duration'; Expression={(Get-Date) - $_.StartTime}}
<!--NeedCopy-->

Parameters

-Uid

Gets desktops with a specific UID.

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

-MachineName

Gets desktops 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: True

-AgentVersion

Gets desktops with a specific Citrix Virtual Delivery Agent version.

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

-ApplicationInUse

Gets desktops running a specified published application (identified by browser name).

String comparisons are case-insensitive.

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

-AssignedClientName

Gets desktops assigned to a specific client name.

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

-AssignedIPAddress

Gets desktops assigned to a specific client IP address.

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

-AssociatedUserFullName

Gets desktops with an associated user identified by their full name (usually in the form ‘first-name last-name’).

Associated users are the current user for shared desktops, and the assigned users for private desktops.

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

-AssociatedUserName

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

Associated users are the current user for shared desktops, and the assigned users for private desktops.

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

-AssociatedUserUPN

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

Associated users are the current user for shared desktops, and the assigned users for private desktops.

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

-AutonomouslyBrokered

Gets desktops 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 desktops.

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

-CatalogName

Gets desktops from the catalog with the specific name.

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

-CatalogUid

Gets desktops from a catalog with a specific UID.

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

-ClientAddress

Gets desktops with a specific client IP address.

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

-ClientName

Gets desktops with a specific client name.

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

-ClientVersion

Gets desktops with a specific client version.

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

-ColorDepth

Gets desktops 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

-ConnectedViaHostName

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

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

-ConnectedViaIP

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

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

-ControllerDNSName

Gets desktops with a specific 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: True

-DeliveryType

Gets desktops 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

Gets desktops with a specific description.

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

-DesktopCondition

Gets desktop with an outstanding desktop condition 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: True

-DesktopGroupName

Gets desktops from a desktop group with the specified name.

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

-DesktopGroupUid

Gets desktops from a desktop group with the specified UID.

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

-DesktopKind

Deprecated: Use AllocationType parameter.

Gets desktops 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

-DeviceId

Gets desktops with a specific client device ID.

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

-DNSName

Gets desktops with a specific DNS name.

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

-FunctionalLevel

Gets desktops 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

-HardwareId

Gets desktops with a specific client hardware ID.

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

-HostedMachineId

Gets desktops with a specific machine ID known to the hypervisor.

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

-HostedMachineName

Gets desktops with a specific machine name known to the hypervisor.

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

-HostingServerName

Gets desktops with a specific name of the hosting hypervisor server.

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

-HypervisorConnectionName

Gets desktops with a specific name of the hosting hypervisor connection.

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

-HypervisorConnectionUid

Gets desktops with a specific UID of the hosting hypervisor connection.

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

-IconUid

Gets desktops with a specific configured icon. Note that desktops 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 desktops by whether their disk image is out of date (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 desktops with a specific InMaintenanceMode setting.

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

-IPAddress

Gets desktops with a specific IP address.

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

-IsAssigned

Gets desktops according to whether they are assigned or not. Desktops 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

Specifies if machines in the catalog can be power managed by the Citrix Broker Service. Where the power state of the machine cannot be controlled, specify $true, otherwise $false. Can only be specified together with a provisioning type of Pvs or Manual, or if used with the deprecated CatalogKind parameter only with a Pvs catalog kind.

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

-LastConnectionFailure

Gets desktops 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 desktop yet.

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

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

-LastConnectionTime

Gets desktops that last connected 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 desktops 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: True

-LastDeregistrationReason

Gets desktops 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 desktops 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 desktops with the specified last error reason.

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

-LastErrorTime

Gets desktops 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 desktops with a specific time that the hosting information was last updated.

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

-LaunchedViaHostName

Gets desktops with a specific host name of the StoreFront server from which the user launched the session.

Session properties are always null for multi-session desktops.

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

-LaunchedViaIP

Gets desktops with a specific IP address of the StoreFront server from which the user launched the session.

Session properties are always null for multi-session desktops.

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

-MachineInternalState

Gets desktops with the specified internal machine state.

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

-MachineUid

Gets desktops with a specific machine UID.

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

-OSType

Gets desktops 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: True

-OSVersion

Gets desktops 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: True

-PersistUserChanges

Gets desktops by the location where the user changes are persisted.

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

-PowerActionPending

Gets desktops with a specific power action pending state.

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 desktops with a specific power state.

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

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

-Protocol

Gets desktops 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: True

-ProvisioningType

Gets desktops that are in a catalog with a particular provisioning type. 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
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-PublishedApplication

Gets desktops with a specific application published to them.

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

-PublishedName

Gets desktops with a specific published name.

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

-PvdStage

This property is no longer supported.

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

-RegistrationState

Gets desktops with a specific registration state.

Valid values are Unregistered, Initializing, Registered and AgentError.

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

-SecureIcaActive

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

Session properties are always null for multi-session desktops.

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

-SecureIcaRequired

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

Session properties are always null for multi-session desktops.

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

-SessionHidden

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

Session properties are always null for multi-session desktops.

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

-SessionId

Deprecated.

Gets desktops by session ID, a unique identifier that Remote Desktop Services uses to track the session but it is only unique on that machine.

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

-SessionState

Gets desktops 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 desktops.

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

-SessionStateChangeTime

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

Session properties are always null for multi-session desktops.

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

-SessionUid

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

Session properties are always null for multi-session desktops.

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

-SessionUserName

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

Session properties are always null for multi-session desktops.

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

-SessionUserSID

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

Session properties are always null for multi-session desktops.

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

-SID

Gets desktops with a specific machine SID.

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

-SmartAccessTag

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

Session properties are always null for multi-session desktops.

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

-StartTime

Gets desktops with a specific session start time.

Session properties are always null for multi-session desktops.

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

-SummaryState

Gets desktops with a specific summary state.

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

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

-Tag

Gets desktops with a specific tag.

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

-WillShutdownAfterUse

Gets desktops 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

-ApplicationUid

Gets desktops with a specific published application (identified by its UID).

Type: Int32
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

-Property

Specifies the properties to be returned. This is similar to piping the output of the command through Select-Object, but the properties are filtered more efficiently at the server.

Type: String[]
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 cannot pipe input into this cmdlet.

Outputs

Citrix.Broker.Admin.SDK.Desktop

Get-BrokerDesktop returns an object for each matching desktop.

Notes

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

Get-BrokerDesktop