Developer Documentation
Citrix Virtual Apps and Desktops SDK
Current Release 2402 2311 2305 2303 2212 2209 2206 2203 2112 2109 2103 1912
View PDF

Update-Brokernamecache

June 30, 2023
Contributed by: 
C

Performs administrative operations on the user/group and machine name cache.

Syntax

Update-BrokerNameCache [-Machines] [-Users] [-AdminAddress <String>] [-BearerToken <String>] [-TraceParent <String>] [-TraceState <String>] [-VirtualSiteId <String>] [<CommonParameters>]

Update-BrokerNameCache -Purge [-Machines] [-Users] [-UnusedFor <TimeSpan>] [-AdminAddress <String>] [-BearerToken <String>] [-TraceParent <String>] [-TraceState <String>] [-VirtualSiteId <String>] [<CommonParameters>]

Update-BrokerNameCache -Machine <String> [-AdminAddress <String>] [-BearerToken <String>] [-TraceParent <String>] [-TraceState <String>] [-VirtualSiteId <String>] [<CommonParameters>]

Update-BrokerNameCache -User <String> [-AdminAddress <String>] [-BearerToken <String>] [-TraceParent <String>] [-TraceState <String>] [-VirtualSiteId <String>] [<CommonParameters>]
<!--NeedCopy-->

Detailed Description

Triggers an immediate asynchronous refresh of the name cache, or when used with the -Purge parameter removes cache entries that are unreferenced and have been unused for a period of time.

The Broker Service maintains a cache of the names of users/groups and machines in use by the site. By default, name information is obtained periodically from Active Directory and the cache refreshed automatically.

Triggering a cache refresh with this cmdlet ensures up-to-date name information is present in the cache after user/group or machine accounts are known to have changed and you need to see those changes immediately instead of waiting for the periodic automatic refresh.

Removing (purging) entries relating to no longer used user/group or machine accounts is useful to stop requests being made to Active Directory to refresh the names relating to those items.

For users/groups, the following name information is cached: Windows name (DOMAIN\user) User Principal Name or ‘UPN’ (user@upndomain) Full Name or ‘Common Name’ (typically a user’s full name)

For machines, the following name information is cached: Windows name (DOMAIN\machine) DNS name (machine.dnsdomain)

Parameters

Name Description Required? Pipeline Input Default Value
Purge Removes unused entries from the cache rather than refreshing the name data. Entries are only removed if they are not configured or referenced in any way within the site.      

In addition, user entries are only removed if the user has not logged in for at least 90 days. Similarly machine entries are only removed if the machine has not registered with the site over the same period. The 90 day default can be overridden using the -UnusedFor parameter.
While removing genuinely unused cache entries is desirable to reduce the requests made to Active Directory, there is additional cost in repopulating the cache if a user/group or machine account is later used again after having been removed. Thus it is not recommended to routinely use very short intervals with -UnusedFor.
If a machine entry is removed from the cache and later used again, the Uid value associated with that machine changes (seen in the output of Get-BrokerMachine). | true | false | | | Machine | Triggers an asynchronous refresh of the cached machine name information for the specified machine. The machine can be specified by SID or by its name as currently known to the Citrix Broker service (for example as shown by Get-BrokerMachine). | true | false | | | User | Triggers an asynchronous refresh of the cached user name information for the specified user. The user can be specified by SID or by its name as currently known to the Citrix Broker service (for example as shown by Get-BrokerUser). | true | false | | | Machines | Triggers an asynchronous refresh of all cached machine name information, or with the -Purge parameter removes unused machine entries from the cache. | false | false | | | Users | Triggers an asynchronous refresh of all cached user/group name information, or with the -Purge parameter removes unused user/group entries from the cache. | false | false | | | UnusedFor | Specifies the minimum period over which user or machine cache entries must have been unused before they can be be removed with the -Purge option. | false | false | 90 days | | 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

None

Notes

For some user accounts, for example, the built-in domain administrator, the UPN and/or Full Name values may not be available because they are not typically specified within Active Directory.
For group accounts, UPN and Full Name values are not available because they are not applicable or not specified within Active Directory.
The DNS name information for a machine is obtained from Active Directory and not from the DNS sub-system. If a machine has only recently been configured, the DNS information may not be available initially.

Examples

Example 1 

C:\PS> Update-BrokerNameCache -Machines
<!--NeedCopy-->

Description

Triggers an immediate asynchronous refresh of all machine name information held within the name cache.

Example 2 

C:\PS> Update-BrokerNameCache -Machines -Users
<!--NeedCopy-->

Description

Triggers an immediate asynchronous refresh of all machine and user name information held within the name cache.

Update-Brokernamecache
June 30, 2023
Contributed by: 
C
June 30, 2023
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.