September 27, 2022, Update: We are happy to share that we are NOT going to impose SDK record limits. We still strongly encourage every customer to use filtering or a reasonable MaxRecordCount. Our data indicates that customers with the best response times have MaxRecordCount <5k.

We are introducing record limiting mechanisms on the Citrix Virtual Apps and Desktops Remote PowerShell SDK API calls beginning December 1, 2021 to return a maximum of 1,000 rows per call. This change is applicable to Citrix Virtual Apps and Desktops service customers who are calling the Get-*, Group-* cmdlets with a MaxRecordCount parameter of greater than 1,000.

What is changing?

By default, the Citrix Virtual Apps and Desktops Remote PowerShell SDK Get-*/Group-* cmdlets returns up to 250 records per API call, with the ability to request a higher number of records using the optional MaxRecordCount parameter.

At present, there is no limit to the number of records requested using MaxRecordCount. As we have increased the service limits, the maximum response size of certain PowerShell cmdlets has grown large, placing higher loads on the system and increasing response times.

To help ensure service levels, availability, and quality, we will be implementing record limiting mechanisms that will be applied effective December 1, 2021. The APIs will be limited on the amount of data (rows) that can be retrieved within a single API call. After December 1, all API calls using the Remote PowerShell SDK will be limited to a maximum of 1,000 rows.

Who is impacted?

Customers matching all the below conditions would be impacted by this change:

  • Have a valid Citrix Cloud-Citrix Virtual Apps and Desktops service subscription
  • Use Remote PowerShell SDK to perform transactions/retrieve data
  • Call the Remote PowerShell SDK Get-*/Group-* cmdlets with the MaxRecordCount parameter
  • Have the MaxRecordCount parameter set to greater than 1,000

What changes do I need to implement?

With the new record limits, each cmdlet call should retrieve less than 1,000 records. This can be accomplished by applying filters to reduce the amount of data being retrieved. When the record size is not less than 1,000 even with filtering, then data can be retrieved as multiple pages of 1,000 records each.

1) Filtering: By applying filtering mechanisms, the number of records being retrieved can be reduced. As a best practice, filtering should be applied as a cmdlet parameter to implement server-side filtering. Performing client-side filtering using select/where statements are less efficient and lead to higher data retrieval and response times. Client-side filtering should be avoided.

Example: Querying for maintenance mode of a specific machine or a specific delivery group rather than querying for all machines.

Get updated maintenance mode status for a specific machine:

Get-BrokerMachine -MachineName &lt;&gt; -Property ‘MachineName’, ‘InMaintenanceMode’

Retrieve list of all machines in maintenance mode in a particular delivery group:

Get-BrokerMachine -DesktopGroupName &lt;&gt; -InMaintenanceMode $true -Property ‘MachineName’, ‘InMaintenanceMode’

2) Paging: Pagination can be applied when it is not feasible to bring the record count to under 1,000 records using filtering. With pagination, larger data sets can be retrieved by breaking them into sets/pages of 1,000 records each. The cmdlets can be called sequentially with a MaxRecordCount of 1,000 until the complete data set is retrieved.

Example: A script querying for all disconnected sessions using the Get-BrokerSession cmdlet as:

Get-BrokerSession -SessionState Disconnected -MaxRecordCount 5000 -Property ‘CatalogName’, ‘MachineName’

This can be broken down into retrieving five pages of 1,000 records each, as in the below sample. In this sample, the data is being ordered by Uid and retrieved in batches of 1,000 rows.

$allSessions = @()
$lastUid = 0
while ($true)
{
$sessions = @(Get-BrokerSession -Filter {Uid -gt $lastUid} -catalogname ABC -MaxRecordCount 1000 -Sortby 'Uid' -Property ‘CatalogName’, ‘MachineName’)
if ($sessions.Length -eq 0)
{
break;
}
$lastUid = $sessions[-1].Uid
$allSessions += $sessions
}

To retrieve all items, it is important to use a property that can appropriately sort the data while calling the cmdlet. For example, most broker cmdlets have a Uid parameter that can be used for sorting. For other cmdlets, other unique parameters can be used.

When will these record limits be introduced?

Based on administrator feedback, Citrix has postponed this change from December 2021 to later in 2022. Please start updating your API calls now in preparation for the switch, but Citrix will notify administrators in advance via blog, email, and in-product messaging when limits will be enforced.

After this change is enforced, what will happen to SDK calls that have not been updated?

When the new record limits are applied, all Get-*/Group-* cmdlet calls with the MaxRecordCount set to a value greater than 1,000 will be returned as an error.