Product Documentation

Get-BrokerApplicationInstance

Oct 21, 2016

Gets the running applications on the desktops.

Syntax

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

Get-BrokerApplicationInstance [-ApplicationName <String>] [-ApplicationUid <Int32>] [-Instances <Int32>] [-MachineName <String>] [-MachineUid <Int32>] [-Metadata <String>] [-SessionUid <Int64>] [-UserName <String>] [-ReturnTotalRecordCount] [-MaxRecordCount <Int32>] [-Skip <Int32>] [-SortBy <String>] [-Filter <String>] [-Property <String[]>] [-AdminAddress <String>] [<CommonParameters>]

Detailed Description

The Get-BrokerApplicationInstance gets the published applications that are running on desktops.

Only published applications that are launched from a Citrix client are returned. If a user launches an application from within a session (by double-clicking on an attachment from an email for example) then it will not show up in the list of running applications.

Also note that this is a list of launched published applications, not a list of processes that are running on the desktop. In some cases the original process associated with the published application may not be running any longer, but if the session is still running then the published application might still be listed as running.

The number of instances for each published application running in a session is also returned. For example, if a user launches two Notepad applications from a Citrix client, and session-sharing occurs such that both Notepad applications run in the same session, then the Instances property indicates that 2 copies are running in the session.

See Get-BrokerApplication and Get-BrokerSession to get the details for the applications and sessions, respectively.

The Get-BrokerMachine cmdlet also returns a list of published applications that are running on a desktop. See the "ApplicationsInUse" attribute of the returned desktop objects.

-------------------------- BrokerApplicationInstance Object

The BrokerApplicationInstance object represents an instance of a published application in the site. It contains the following properties:

-- ApplicationName (System.String)

The administrative name of the application.

-- ApplicationUid (System.Int32)

The UID of the application.

-- Instances (System.Int32)

The number of times this published application is running in the specified session.

-- MachineName (System.String)

Machine's SAM name (of the form domain\machine). If SAM name is unavailable contains the machines's SID.

-- MachineUid (System.Int32)

UID of underlying machine.

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

Metadata for this application instance.

-- SessionUid (System.Int64)

The UID of the session.

-- Uid (System.Int64)

The unique identifier for this application instance object itself and is distinct from the Uids of either application or session. objects.

-- UserName (System.String)

User name (SAMName).

Parameters

-Uid<Int64>

Gets only the application instances specified by the unique identifier. This is the unique identifier for the application instance object itself, and is distinct from the Uids of either application or session objects.

Required? true
Default Value  
Accept Pipeline Input? false

-ApplicationName<String>

Gets only application instances for the specified application name.

Required? false
Default Value  
Accept Pipeline Input? false

-ApplicationUid<Int32>

Gets only the application instances for the specified application Uid.

Required? false
Default Value  
Accept Pipeline Input? false

-Instances<Int32>

Gets only the application instances that match the specified number of instances.

Required? false
Default Value  
Accept Pipeline Input? false

-MachineName<String>

Gets only application instances running on the specified machines.

Required? false
Default Value  
Accept Pipeline Input? false

-MachineUid<Int32>

Gets only application instances running on the 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

-SessionUid<Int64>

Gets only the application instances for the published applications running in the specified session. Note that the SessionUid, not the SessionID, must be specified.

Required? false
Default Value  
Accept Pipeline Input? false

-UserName<String>

Gets only application instances being run by the specified users.

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

Get-BrokerApplicationInstance returns an object for each application instance it gets.

Examples

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

C:\PS> Get-BrokerApplicationInstance -Uid 3

Returns the application instance with a Uid of 3. Note that this is the unique identifier for application instances, which is distinct from the unique identifiers of either application or session objects.

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

C:\PS> $app = Get-BrokerApplication Notepad 
C:\PS> Get-BrokerApplicationInstance -ApplicationUid $app.Uid

Returns all the application instances for the Notepad application. This is a convenient way to see if there are any launched instances of Notepad running in your site, and if so then from which desktops.

-------------------------- EXAMPLE 3 --------------------------

C:\PS> $sessions = Get-BrokerSession -MachineName "ACME\Worker1" 
C:\PS> for ($i=0; $i -lt $sessions.Length; $i++) { 
            Get-BrokerApplicationInstance -SessionUid $sessions[$i].SessionUid 
          }

Returns all the applications that are running on the "Worker1" machine in the "ACME" domain. This can be a useful way to see which published applications are running on a specific machine.

Note that the SessionUid, not the SessionId, is specified as a parameter to this cmdlet. The SessionId is a unique identifier that Remote Desktop Services uses to track the session, and is only unique on that machine. The SessionUid on the other hand is unique across the entire site.

The "ApplicationsInUse" attribute of the returned session object also provides a list of running launched applications, and in many cases might be more convenient to use. It returns a list of application BrowserNames.