Developer Documentation
Citrix Daas SDK

Update-BrokerNameCache

August 9, 2024
Contributed by: 
C C

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

Syntax

Update-BrokerNameCache
      [-Machines]
      [-Users]
      [<CitrixCommonParameters>]
      [<CommonParameters>]
<!--NeedCopy-->

Update-BrokerNameCache
      [-Machines]
      [-Users]
      [-Purge]
      [-UnusedFor <TimeSpan>]
      [<CitrixCommonParameters>]
      [<CommonParameters>]
<!--NeedCopy-->

Update-BrokerNameCache
      -Machine <String>
      [<CitrixCommonParameters>]
      [<CommonParameters>]
<!--NeedCopy-->

Update-BrokerNameCache
      -User <String>
      [<CitrixCommonParameters>]
      [<CommonParameters>]
<!--NeedCopy-->

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)

Examples

EXAMPLE 1

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

Update-BrokerNameCache -Machines
<!--NeedCopy-->

EXAMPLE 2

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

Update-BrokerNameCache -Machines -Users
<!--NeedCopy-->

Parameters

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

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

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

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

-Machines

Triggers an asynchronous refresh of all cached machine name information, or with the -Purge parameter removes unused machine entries from the cache.

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

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

Type: TimeSpan
Position: Named
Default value: 90 days
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

None

By default, this cmdlet returns no output.

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.

Update-BrokerNameCache
August 9, 2024
Contributed by: 
C C
August 9, 2024
Contributed by: 
C 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.