Citrix Virtual Apps and Desktops SDK

Get-BrokerApplicationInstance

March 11, 2024

Contributed by:

Gets the running applications on the desktops.

Syntax

Get-BrokerApplicationInstance
   [-ApplicationName <String>]
   [-ApplicationUid <Int32>]
   [-ApplicationUUID <Guid>]
   [-Instances <Int32>]
   [-MachineName <String>]
   [-MachineUid <Int32>]
   [-Metadata <String>]
   [-SessionKey <Guid>]
   [-SessionUid <Int64>]
   [-UserName <String>]
   [-Property <String[]>]
   [-ReturnTotalRecordCount]
   [-MaxRecordCount <Int32>]
   [-Skip <Int32>]
   [-SortBy <String>]
   [-Filter <String>]
   [-FilterScope <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Get-BrokerApplicationInstance
   -Uid <Int64>
   [-Property <String[]>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

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) this 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 running on the desktop. In some cases the original process associated with the published application may no longer be running, but if the session is still running the published application may 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.
ApplicationUUID (System.Guid)

The UUID 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.
SessionKey (System.Guid)

The key of the session.
SessionUid (System.Int64)

The UID of the session.
Uid (System.Int64)

The unique identifier for this application instance object itself, distinct from the Uids of either application or session. objects.
UserName (System.String)

User name (SAMName).

Examples

EXAMPLE 1

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.

Get-BrokerApplicationInstance -Uid 3
<!--NeedCopy-->

EXAMPLE 2

Returns all the application instances for the Notepad application.

Use this to see if there are any launched instances of Notepad

running in your site and, if so, from which desktops.

$app = Get-BrokerApplication Notepad
Get-BrokerApplicationInstance -ApplicationUid $app.Uid
<!--NeedCopy-->

EXAMPLE 3

Returns all the applications that are running on the “Worker1” machine

in the “ACME” domain. Use this 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 unique only 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.

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

Parameters

-Uid

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.

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

-ApplicationName

Gets only application instances for the specified application name.

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

-ApplicationUid

Gets only application instances for the specified application Uid.

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

-ApplicationUUID

Gets only the application instances for the specified application UUID.

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

-Instances

Gets only application instances that match the specified

number of instances.

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

-MachineName

Gets only application instances running on the specified machines.

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

-MachineUid

Gets only application instances running on the machine with the specified UID.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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”.

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

-SessionKey

Gets only application instances for the published applications

running in the specified session.

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

-SessionUid

Gets only application instances for the published applications

running in the specified session.

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

-UserName

Gets only application instances being run by the specified users.

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

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

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

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Get-BrokerApplicationInstance

March 11, 2024

Contributed by:

March 11, 2024

Contributed by:

Get-BrokerApplicationInstance

Syntax

Description

Examples

EXAMPLE 1

EXAMPLE 2

EXAMPLE 3

Parameters

-Uid

-ApplicationName

-ApplicationUid

-ApplicationUUID

-Instances

-MachineName

-MachineUid

-Metadata

-SessionKey

-SessionUid

-UserName

-ReturnTotalRecordCount

-MaxRecordCount

-Skip

-SortBy

-Filter

-FilterScope

-Property

CitrixCommonParameters

CommonParameters

Inputs

None

Outputs

Citrix.Broker.Admin.SDK.ApplicationInstance

Related Links

In this article