Product Documentation

Get-BrokerSession

Oct 12, 2015

Gets a list of sessions.

Syntax

Get-BrokerSession -Uid <Int64> [-Property <String[]>] [-AdminAddress <String>] [<CommonParameters>]

Get-BrokerSession [-AgentVersion <String>] [-ApplicationInUse <String>] [-AutonomouslyBrokered <Boolean>] [-BrokeringDuration <Int32>] [-BrokeringTime <DateTime>] [-BrokeringUserName <String>] [-BrokeringUserSID <String>] [-CatalogName <String>] [-ClientAddress <String>] [-ClientName <String>] [-ClientVersion <String>] [-ConnectedViaHostName <String>] [-ConnectedViaIP <String>] [-ControllerDNSName <String>] [-DesktopGroupName <String>] [-DesktopGroupUid <Int32>] [-DesktopKind <DesktopKind>] [-DesktopSID <String>] [-DesktopUid <Int32>] [-DeviceId <String>] [-DNSName <String>] [-EstablishmentDuration <Int32>] [-EstablishmentTime <DateTime>] [-HardwareId <String>] [-Hidden <Boolean>] [-HostedMachineName <String>] [-HostingServerName <String>] [-HypervisorConnectionName <String>] [-ImageOutOfDate <Boolean>] [-InMaintenanceMode <Boolean>] [-IPAddress <String>] [-IsPhysical <Boolean>] [-LaunchedViaHostName <String>] [-LaunchedViaIP <String>] [-MachineName <String>] [-MachineSummaryState <DesktopSummaryState>] [-MachineUid <Int32>] [-Metadata <String>] [-OSType <String>] [-PersistUserChanges <PersistUserChanges>] [-PowerState <PowerState>] [-Protocol <String>] [-ProvisioningType <ProvisioningType>] [-SecureIcaActive <Boolean>] [-SessionId <Int32>] [-SessionKey <Guid>] [-SessionState <SessionState>] [-SessionStateChangeTime <DateTime>] [-SessionSupport <SessionSupport>] [-SessionType <SessionType>] [-StartTime <DateTime>] [-UserFullName <String>] [-UserName <String>] [-UserSID <String>] [-UserUPN <String>] [-ApplicationUid <Int32>] [-SharedDesktopUid <Int32>] [-ReturnTotalRecordCount] [-MaxRecordCount <Int32>] [-Skip <Int32>] [-SortBy <String>] [-Filter <String>] [-Property <String[]>] [-AdminAddress <String>] [<CommonParameters>]

Detailed Description

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

-------------------------- BrokerSession Object

The session object returned represents a session on a machine in the site. The session could be for a desktop or application

-- AgentVersion (System.String)

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

-- ApplicationsInUse (System.String[])

List of SDK Name property of applications in use in the session.

-- AutonomouslyBrokered (System.Boolean)

Session property indicating if the session was started without the use of the broker.

-- BrokeringDuration (System.Int32?)

Time taken to broker the session.

-- BrokeringTime (System.DateTime?)

Time at which the session was brokered.

-- BrokeringUserName (System.String)

The user name of the brokering user.

-- BrokeringUserSID (System.String)

The SID of the brokering user.

-- CatalogName (System.String)

The name of the catalog that the machine hosting the session is assigned to.

-- ClientAddress (System.String)

The IP address of the client connected to the desktop.

-- ClientName (System.String)

The host name of the client connected to the session.

-- ClientVersion (System.String)

The version of the Citrix Receiver running on the client connected to the session.

-- ConnectedViaHostName (System.String)

The host name of the incoming connection. This is usually a gateway, router or client.

-- ConnectedViaIP (System.String)

The IP address of the incoming connection This is usually a gateway, router or client.

-- ControllerDNSName (System.String)

The DNS host name of the controller that the session's hosting machine is registered with.

-- DesktopGroupName (System.String)

Name of the desktop group of the machine the session is on.

-- DesktopGroupUid (System.Int32)

UID of the desktop group of the machine the session is on.

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

Indicates if the session is shared or private.

-- DesktopSID (System.String)

The Windows SID of the machine the session is on.

-- DesktopUid (System.Int32)

For a desktop session, the unique identifier of the desktop.

-- DeviceId (System.String)

Unique identifier for the client device that has most recently been associated with the session.

-- DNSName (System.String)

The DNS host name of the machine hosting the session.

-- EstablishmentDuration (System.Int32?)

Duration that it took to establish the session.

-- EstablishmentTime (System.DateTime?)

Time at which the session was established.

-- HardwareId (System.String)

Unique identifier for the client hardware that has been most recently associated with the session.

-- Hidden (System.Boolean)

Flag to indicate if the session is currently hidden from the user and not to be reconnected to.

-- HostedMachineName (System.String)

The friendly name of a hosted machine running the session, as used by its hypervisor. This does not necessarily match either the DNS or AD name of the machine.

-- HostingServerName (System.String)

DNS name of the hypervisor that is hosting the machine hosting the session.

-- HypervisorConnectionName (System.String)

The name of the hypervisor connection that the machine hosting the session has been assigned to.

-- ImageOutOfDate (System.Boolean?)

Denotes whether the VM image for a hosted machine is out of date and due to be updated to a new master image when the machine next reboots.

-- InMaintenanceMode (System.Boolean)

Denotes whether the machine hosting the session is in maintentance mode.

-- IPAddress (System.String)

The IP address of the machine hosting the session.

-- IsPhysical (System.Boolean)

This value is false if the machine hosting the session can be power managed, and true otherwise

-- LaunchedViaHostName (System.String)

The host name of the StoreFront server used to launch the session.

-- LaunchedViaIP (System.String)

The IP address of the StoreFront server used to launch the session.

-- MachineName (System.String)

DNS host name of the machine hosting the session.

-- MachineSummaryState (Citrix.Broker.Admin.SDK.DesktopSummaryState)

The summary state of the machine (will be Unregistered, Disconnected, or InUse)

-- MachineUid (System.Int32)

UID of the machine hosting the session.

-- MetadataMap (System.Collections.Generic.Dictionary<string, string>)

Map of metadata for this session.

-- OSType (System.String)

A string that can be used to identify the operating system that is running on the machine hosting the session.

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

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

o OnLocal - Persist the user changes locally.

o Discard - Discard user changes.

o OnPvd - Persist user changes on the Citrix Personal vDisk.

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

The current power state of the machine hosting the session. Possible values are: Unmanaged, Unknown, Unavailable, On, Suspended, TurningOn, TurningOff, Suspending and Resuming.

-- Protocol (System.String)

The protocol that the session is using, can be either "HDX" or "RDP".

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

Describes how the machine hosting the session was provisioned, possible values are:

o Manual: No provisioning.

o PVS: Machine provisioned by PVS (may be physical, blade, VM,...)

o MCS: Machine provisioned by MCS (machine must be VM)

-- SecureIcaActive (System.Boolean?)

Indicates whether SecureICA is active on the session.

-- SessionId (System.Int32)

Deprecated. A unique identifier that Remote Desktop Services uses to track the session but it is only unique on that machine.

-- SessionKey (System.Guid)

GUID that provides a unique identifier for this session.

-- SessionState (Citrix.Broker.Admin.SDK.SessionState)

The state of the session. Valid values are PreparingNewSession, Connected, Active, Disconnected, Reconnecting, NonBrokeredSession, Other, and Unknown.

-- SessionStateChangeTime (System.DateTime)

The time of the most recent state change for the session.

-- SessionSupport (Citrix.Broker.Admin.SDK.SessionSupport)

Indicates if the machine hosting the session supports multiple or single sessions.

-- SessionType (Citrix.Broker.Admin.SDK.SessionType)

Indicates if this is an Application or Desktop session.

-- SmartAccessTags (System.String[])

The Smart Access tags for this session.

-- StartTime (System.DateTime?)

Indicates when the session was started.

-- Uid (System.Int64)

Unique identifier of this session.

-- UserFullName (System.String)

The full name of the user.

-- UserName (System.String)

The name of the user.

-- UserSID (System.String)

The user's Windows SID.

-- UserUPN (System.String)

The user's User Principal Name

Parameters

-Uid<Int64>

Get session by its Uid.

Required? true
Default Value  
Accept Pipeline Input? false

-AgentVersion<String>

Gets sessions with a specific Virtual Desktop Agent version.

Required? false
Default Value  
Accept Pipeline Input? false

-ApplicationInUse<String>

Gets sessions running specific applications (identified by their SDK Name property).

Required? false
Default Value  
Accept Pipeline Input? false

-AutonomouslyBrokered<Boolean>

Get autonomously brokered sessions.

Required? false
Default Value  
Accept Pipeline Input? false

-BrokeringDuration<Int32>

Gets session with a specific time taken to broker. In general, Citrix recommends using -Filter and relative comparisons.

Required? false
Default Value  
Accept Pipeline Input? false

-BrokeringTime<DateTime>

Get sessions brokered at a specific time. In general, Citrix recommends using -Filter and relative comparisons.

Required? false
Default Value  
Accept Pipeline Input? false

-BrokeringUserName<String>

Get sessions by brokering user.

Required? false
Default Value  
Accept Pipeline Input? false

-BrokeringUserSID<String>

Get sessions by brokering user SID.

Required? false
Default Value  
Accept Pipeline Input? false

-CatalogName<String>

Gets sessions on machines from a specific catalog name.

Required? false
Default Value  
Accept Pipeline Input? false

-ClientAddress<String>

Get sessions by client IP address.

Required? false
Default Value  
Accept Pipeline Input? false

-ClientName<String>

Get sessions by client name.

Required? false
Default Value  
Accept Pipeline Input? false

-ClientVersion<String>

Get sessions by client version.

Required? false
Default Value  
Accept Pipeline Input? false

-ConnectedViaHostName<String>

Get sessions by host name of the incoming connection. This is usually a proxy or Citrix Access Gateway server.

Required? false
Default Value  
Accept Pipeline Input? false

-ConnectedViaIP<String>

Get sessions by IP address of the incoming connection.

Required? false
Default Value  
Accept Pipeline Input? false

-ControllerDNSName<String>

Gets sessions that are hosted on machines which are registered with a specific controller.

Required? false
Default Value  
Accept Pipeline Input? false

-DesktopGroupName<String>

Gets sessions from a desktop group with the specified name.

Required? false
Default Value  
Accept Pipeline Input? false

-DesktopGroupUid<Int32>

Gets sessions from a desktop group with the specified UID.

Required? false
Default Value  
Accept Pipeline Input? false

-DesktopKind<DesktopKind>

Gets sessions on a desktop of a particular kind.

Valid values are Private and Shared.

Required? false
Default Value  
Accept Pipeline Input? false

-DesktopSID<String>

Get sessions by desktop SID.

Required? false
Default Value  
Accept Pipeline Input? false

-DesktopUid<Int32>

Get sessions by desktop Uid.

Required? false
Default Value  
Accept Pipeline Input? false

-DeviceId<String>

Get sessions by client device id.

Required? false
Default Value  
Accept Pipeline Input? false

-DNSName<String>

Gets sessions by their machine's DNS name.

Required? false
Default Value  
Accept Pipeline Input? false

-EstablishmentDuration<Int32>

Gets sessions which took a specific time to establish. In general, Citrix recommends using -Filter and relative comparisons.

Required? false
Default Value  
Accept Pipeline Input? false

-EstablishmentTime<DateTime>

Gets sessions which became established at a particular time. In general, Citrix recommends using -Filter and relative comparisons.

Required? false
Default Value  
Accept Pipeline Input? false

-HardwareId<String>

Get sessions by client hardware id.

Required? false
Default Value  
Accept Pipeline Input? false

-Hidden<Boolean>

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

Required? false
Default Value  
Accept Pipeline Input? false

-HostedMachineName<String>

Gets sessions by their machine's name as known to its hypervisor.

Required? false
Default Value  
Accept Pipeline Input? false

-HostingServerName<String>

Gets sessions hosted by a machine with a specific name of the hosting hypervisor server.

Required? false
Default Value  
Accept Pipeline Input? false

-HypervisorConnectionName<String>

Gets sessions hosted by a machine with a specific name of the hosting hypervisor connection.

Required? false
Default Value  
Accept Pipeline Input? false

-ImageOutOfDate<Boolean>

Gets sessions hosted by a machine with a specific ImageOutOfDate setting.

Required? false
Default Value  
Accept Pipeline Input? false

-InMaintenanceMode<Boolean>

Gets sessions hosted by a machine with a specific InMaintenanceMode setting.

Required? false
Default Value  
Accept Pipeline Input? false

-IPAddress<String>

Gets sessions hosted by a machine with a specific IP address.

Required? false
Default Value  
Accept Pipeline Input? false

-IsPhysical<Boolean>

Gets sessions hosted on machines where the flag indicating if the machine can be power managed by the Citrix Broker Service matches the requested value. Where the power state of the machine cannot be controlled, specify $true, otherwise $false.

Required? false
Default Value  
Accept Pipeline Input? false

-LaunchedViaHostName<String>

Get sessions by the host name of the Web Interface server from which a user launches a session.

Required? false
Default Value  
Accept Pipeline Input? false

-LaunchedViaIP<String>

Get sessions by the IP address of the Web Interface server from which a user launches a session.

Required? false
Default Value  
Accept Pipeline Input? false

-MachineName<String>

Gets sessions by their machine name (DOMAIN\MACHINE).

Required? false
Default Value  
Accept Pipeline Input? false

-MachineSummaryState<DesktopSummaryState>

Gets sessions on a machine with a specific summary state.

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

Required? false
Default Value  
Accept Pipeline Input? false

-MachineUid<Int32>

Gets sessions on a machine with the specified UID.

Required? false
Default Value  
Accept Pipeline Input? false

-Metadata<String>

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".

Required? false
Default Value  
Accept Pipeline Input? false

-OSType<String>

Gets sessions with a specific type of operating system.

Required? false
Default Value  
Accept Pipeline Input? false

-PersistUserChanges<PersistUserChanges>

Gets sessions where the user changes are persisted in a particular manner. Values can be:

o OnLocal - User changes are persisted locally.

o Discard - User changes are discarded.

o OnPvd - User changes are persisted on the Pvd.

Required? false
Default Value  
Accept Pipeline Input? false

-PowerState<PowerState>

Gets sessions on machines in the specified power state.

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

Required? false
Default Value  
Accept Pipeline Input? false

-Protocol<String>

Get sessions by connection protocol. Valid values are HDX and RDP.

Required? false
Default Value  
Accept Pipeline Input? false

-ProvisioningType<ProvisioningType>

Gets sessions hosted on machines provisioned in a particular manner. Values can be:

o Manual - No automated provisioning.

o PVS - Machine provisioned by PVS (machine may be physical, blade, VM,...).

o MCS - Machine provisioned by MCS (machine must be VM).

Required? false
Default Value  
Accept Pipeline Input? false

-SecureIcaActive<Boolean>

Get sessions by their use of SecureICA.

Required? false
Default Value  
Accept Pipeline Input? false

-SessionId<Int32>

Deprecated.

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

Required? false
Default Value  
Accept Pipeline Input? false

-SessionKey<Guid>

Gets session having the specified unique key.

Required? false
Default Value  
Accept Pipeline Input? false

-SessionState<SessionState>

Get sessions by their state.

Valid values are Other, PreparingNewSession, Connected, Active, Disconnected, Reconnecting, NonBrokeredSession, and Unknown.

Required? false
Default Value  
Accept Pipeline Input? false

-SessionStateChangeTime<DateTime>

Get sessions by their last state change time. In general, Citrix recommends using -Filter and relative comparisons.

Required? false
Default Value  
Accept Pipeline Input? false

-SessionSupport<SessionSupport>

Gets sessions hosted on machines which support the required pattern of sessions. Values can be:

o SingleSession - Single-session only machine.

o MultiSession - Multi-session capable machine.

Required? false
Default Value  
Accept Pipeline Input? false

-SessionType<SessionType>

Get sessions by their type.

Valid values are Application and Desktop.

Required? false
Default Value  
Accept Pipeline Input? false

-StartTime<DateTime>

Get sessions by their start time. In general, Citrix recommends using -Filter and relative comparisons.

Required? false
Default Value  
Accept Pipeline Input? false

-UserFullName<String>

Gets sessions by user's full name (usually 'first-name last-name').

Required? false
Default Value  
Accept Pipeline Input? false

-UserName<String>

Get sessions by user name (in the form domain\user).

Required? false
Default Value  
Accept Pipeline Input? false

-UserSID<String>

Get sessions by user's Windows SID.

Required? false
Default Value  
Accept Pipeline Input? false

-UserUPN<String>

Gets sessions by user's User Principal Name (in the form user@domain).

Required? false
Default Value  
Accept Pipeline Input? false

-ApplicationUid<Int32>

Get sessions running the application with the specified Uid.

Required? false
Default Value  
Accept Pipeline Input? false

-SharedDesktopUid<Int32>

Get sessions by SharedDesktop Uid.

Required? false
Default Value  
Accept Pipeline Input? false

-ReturnTotalRecordCount<SwitchParameter>

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.

Required? false
Default Value False
Accept Pipeline Input? false

-MaxRecordCount<Int32>

Specifies the maximum number of records to return.

Required? false
Default Value 250
Accept Pipeline Input? false

-Skip<Int32>

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

Required? false
Default Value 0
Accept Pipeline Input? false

-SortBy<String>

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.

Required? false
Default Value The default sort order is by name or unique identifier.
Accept Pipeline Input? false

-Filter<String>

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

Required? false
Default Value  
Accept Pipeline Input? false

-Property<String[]>

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.

Required? false
Default Value  
Accept Pipeline Input? false

-AdminAddress<String>

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

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

Input Type

None You cannot pipe input into this cmdlet.

Return Values

Citrix.Broker.Admin.SDK.Session

Returns sessions matching the specified criteria.

Examples

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

C:\PS> Get-BrokerSession

Enumerate all sessions.

-------------------------- EXAMPLE 2 --------------------------

C:\PS> Get-BrokerSession -UserName MyDomain\MyAccount -SessionState Disconnected

Get all disconnected sessions for a specific user.