Citrix Virtual Apps and Desktops SDK

View PDF

about_EnvTest_Filtering

August 9, 2024

Contributed by:

Topic

XenDesktop - Advanced Dataset Filtering

Short Description

Describes the common filtering options for XenDesktop cmdlets.

Long Description

Some cmdlets operate on large quantities of data and, to reduce the overhead of sending all of that data over the network, many of the Get- cmdlets support server-side filtering of the results.

The conventional way of filtering results in PowerShell is to pipeline them into Where-Object, Select-Object, and Sort-Object, for example:

Get-<Noun> | Where { $_.Size = 'Small' } | Sort 'Date' | Select -First 10
<!--NeedCopy-->

However, for most XenDesktop cmdlets the data is stored remotely and it would be slow and inefficient to retrieve large amounts of data over the network and then discard most of it. Instead, many of the Get- cmdlets provide filtering parameters that allow results to be processed on the server, returning only the required results.

You can filter results by most object properties using parameters derived from the property name. You can also sort results or limit them to a specified number of records:

Get-<Noun> -Size 'Small' -SortBy 'Date' -MaxRecordCount 10
<!--NeedCopy-->

You can express more complex filter conditions using a syntax and set of operators very similar to those used by PowerShell expressions.

Those cmdlets that support filtering have the following common parameters:

-MaxRecordCount <int>

Specifies the maximum number of results to return. For example, to return only the first nine results use:

Get-<Noun> -MaxRecordCount 9
<!--NeedCopy-->

If not specified, only the first 250 records are returned, and if more are available, a warning is produced:

WARNING: Only first 250 records returned. Use -MaxRecordCount to retrieve more.

You can suppress this warning by using -WarningAction or by specifying a value for -MaxRecordCount.

Based on the use case, you can filter results or separate results into multiple pages. You may also use both approaches together.

-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. For example:

# ReturnTotalRecord example
Get-<Noun> -MaxRecordCount 9 -ReturnTotalRecordCount
....
Get-<Noun> : Returned 9 of 10 items
At line:1 char:18
+ Get-<Noun> <<<<  -MaxRecordCount 9 -ReturnTotalRecordCount
+ CategoryInfo          : OperationStopped: (:) [Get-<Noun>], PartialDataException
+ FullyQualifiedErrorId : PartialData,Citrix.<SDKName>.SDK.Get<Noun>
<!--NeedCopy-->

The count can be accessed using the TotalAvailableResultCount property:

$count = $error[0].TotalAvailableResultCount

-Skip <int>

Skips the specified number of records before returning results. Also reduces the count returned by -ReturnTotalRecordCount.

-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, respectively. Ascending order is assumed if no prefix is present.

Sorting occurs before -MaxRecordCount and -Skip parameters are applied. For example, to sort by Name and then by Count (largest first) use:

-SortBy ‘Name,-Count’

By default, sorting by an enumeration property uses the numeric value of the elements. You can specify a different sort order by qualifying the name with an ordered list of elements or their numeric values, or <null> to indicate the placement of null values. Elements not mentioned are placed at the end in their numeric order. For example, to sort by two different enums and then by the object id:

-SortBy ‘MyState(StateC,<null>,StateA,StateB),Another(0,3,2,1),Id’

-Filter <String>

This parameter lets you specify advanced filter expressions, and supports combination of conditions with -and and -or, and grouping with braces. For example:

Get-<Noun> -Filter 'Name -like "High*" -or (Priority -eq 1 -and Severity -ge 2)'
<!--NeedCopy-->

The syntax is close enough to PowerShell syntax that you can use script blocks in most cases. This can be easier to read as it reduces quoting:

Get-<Noun> -Filter { Count -ne $null }
<!--NeedCopy-->

The full -Filter syntax is provided below.

Examples

Filtering by strings performs a case-insensitive wildcard match. Separate parameters are combined with an implicit -and operator. Normal PowerShell quoting rules apply, so you can use single or double quotes, and omit the quotes altogether for many strings. The order of parameters does not make any difference. The following are equivalent:

Get-<Noun> -Company Citrix -Product Xen*
Get-<Noun> -Company "citrix" -Product '[X]EN*'
Get-<Noun> -Product "Xen*" -Company "CITRIX"
Get-<Noun> -Filter { Company -eq 'Citrix' -and Product -like 'Xen*' }
<!--NeedCopy-->

See about_Quoting_Rules and about_Wildcards for details about PowerShell handling of quotes and wildcards.

To avoid wildcard matching or include quote characters, you can escape the wildcards using the normal PowerShell escape mechanisms (see about_Special_Characters), or switch to a filter expression and the -eq operator:

# Escape examples
Get-<Noun> -Company "Abc[*]"                 # Matches Abc*
Get-<Noun> -Company "Abc`*"                  # Matches Abc*
Get-<Noun> -Filter { Company -eq "Abc*" }    # Matches Abc*
Get-<Noun> -Filter { Company -eq "A`"B`'C" } # Matches A"B'C
<!--NeedCopy-->

Simple filtering by numbers, booleans, and TimeSpans perform direct equality comparisons, although if the value is nullable you can also search for null values. Here are some examples:

# Simple filtering examples
Get-<Noun> -Uid 123
Get-<Noun> -Enabled $true
Get-<Noun> -Duration 1:30:40
Get-<Noun> -NullableProperty $null
<!--NeedCopy-->

More comparisons are possible using advanced filtering with -Filter:

Get-<Noun> -Filter 'Capacity -ge 10gb'
Get-<Noun> -Filter 'Age -ge 20 -and Age -lt 40'
Get-<Noun> -Filter 'VolumeLevel -like "[123]"'
Get-<Noun> -Filter 'Enabled -ne $false'
Get-<Noun> -Filter 'NullableProperty -ne $null'
<!--NeedCopy-->

You can check boolean values without an explicit comparison operator, and you can also combine them with -not:

Get-<Noun> -Filter 'Enabled'      # Equivalent to 'Enabled -eq $true'
Get-<Noun> -Filter '-not Enabled' # Equivalent to 'Enabled -eq $false'
<!--NeedCopy-->

See about_Comparison_Operators for an explanation of the operators, but note that only a subset of PowerShell operators are supported (-eq, -ne, -gt, -ge, -lt, -le, -like, -notlike, -in, -notin, -contains, -notcontains).

Enumeration values can either be specified using typed values or the string name of the enumeration value:

Get-<Noun> -Shape [Shapes]::Square
Get-<Noun> -Shape Circle
<!--NeedCopy-->

With filter expressions, typed values can be specified with simple variables or quoted strings. They also support enumerations with wildcards:

$s = [Shapes]::Square Get-<Noun> -Filter { Shape -eq $s -or Shape -eq “Circle” } Get-<Noun> -Filter { Shape -like ‘C*’ }

By their nature, floating point values, DateTime values, and TimeSpan values are best suited to relative comparisons rather than just equality. DateTime strings are converted using the locale and time zone of the user device, but you can use ISO8601 format strings (YYYY-MM-DDThh:mm:ss.sTZD) to avoid ambiguity. You can also use standard PowerShell syntax to create these values:

Get-<Noun> -Filter { StartTime -ge "2010-08-23T12:30:00.0Z" }
$d = [DateTime]"2010-08-23T12:30:00.0Z"
Get-<Noun> -Filter { StartTime -ge $d }
$d = (Get-Date).AddDays(-1)
Get-<Noun> -Filter { StartTime -ge $d }
<!--NeedCopy-->

Relative times are quite common and, when using filter expressions, you can also specify DateTime values using a relative format:

Get-<Noun> -Filter { StartTime -ge '-2' }         # Two days ago
Get-<Noun> -Filter { StartTime -ge '-1:30' }      # Hour and a half ago
Get-<Noun> -Filter { StartTime -ge '-0:0:30' }    # 30 seconds ago
<!--NeedCopy-->

Array Properties

When filtering against list or array properties, simple parameters perform a case-insensitive wildcard match against each of the members. With filter expressions, you can use the -contains and -notcontains operators. Unlike PowerShell, these perform wildcard matching on strings. Note that for array properties the naming convention is for the returned property to be plural, but the parameter used to search for any match is singular. The following are equivalent (assuming Users is an array property):

Get-<Noun> -User Fred*
Get-<Noun> -Filter { User -like "Fred*" }
Get-<Noun> -Filter { Users -contains "Fred*" }
<!--NeedCopy-->

You can also use the singular form with -Filter to search using other operators:

# Match if any user in the list is called "Frederick"
Get-<Noun> -Filter { User -eq "Frederick" }
# Match if any user in the list has a name alphabetically below 'F'
Get-<Noun> -Filter { User -lt 'F' }
<!--NeedCopy-->

Complex Expressions

When matching against multiple values, you can use a sequence of comparisons joined with -or operators, or you can use -in and -notin:

Get-<Noun> -Filter { Shape -eq 'Circle' -or Shape -eq 'Square' }
$shapes = 'Circle','Square'
Get-<Noun> -Filter { Shape -in $shapes }
$sides = 1..4
Get-<Noun> -Filter { Sides -notin $sides }
<!--NeedCopy-->

Braces can be used to group complex expressions, and override the default left-to-right evaluation of -and and -or. You can also use -not to invert the sense of any sub-expression:

Get-<Noun> -Filter { Size -gt 4 -or (Color -eq 'Blue' -and Shape -eq 'Circle') }
Get-<Noun> -Filter { Sides -lt 5 -and -not (Color -eq 'Blue' -and Shape -eq 'Circle') }
<!--NeedCopy-->

Paging

Citrix recommends that you avoid paging by using *Properties* or the *-Filter* mechanism.

However, if more objects are required, then the SDK supports deterministic paging though filtering. You must sort and filter objects to have a unique identifier for an object. This unique identifier helps you to page through objects and avoid reordering. Most of the Broker objects have a unique ID that can be used for paging. However, you must sort the other objects that do not have a unique ID either by time or some other unique field.

Example:

# Paging example
$allSessions = @()
$lastUid = 0
while ($true)
{
  $sessions = @(Get-BrokerSession -Filter { Uid -gt $lastUid } -MaxRecordCount 1000 -Sortby 'Uid')

<!--NeedCopy-->

if ($sessions.Length -eq 0) {

break;

} $lastUid = $sessions[-1].Uid $allSessions += $sessions }

In this example, a list is created and the lowest possible value for the chosen unique field is initialized. The unique ID in this example is zero. In a loop, sessions are requested using a filter searching for objects with a unique ID greater than zero. The number of objects is restricted to the first 1000 entries. It is important to sort by the field that is used as a filter.

The filtering UID ($lastUid) is set to the unique ID of the final object retrieved. The loop begins again using this unique ID value as the lower bound. This loop continues until all sessions are retrieved and stored in an array ($allSessions).

Filter Syntax Definition

<ScriptBlock> ::= “{“ <ComponentList> “}”

<ComponentList> ::= <Component> <AndOrOperator> <ComponentList> |

<Component> ::= <NotOperator> <Factor> |

<Factor> ::= “(“ <ComponentList> “)” |

<AndOrOperator> ::= “-and” | “-or”

<NotOperator> ::= “-not” | “!”

::= “-eq” | “-ne” | “-le” | “-ge” | “-lt” | “-gt” |

<Value> ::= <string literal> | <numeric literal> |

<scalar variable> | <array variable> | “$null” | “$true” | “$false”

Numeric literals support decimal and hexadecimal literals, with optional multiplier suffixes (kb, mb, gb, tb, pb).

Dates and times can be specified as string literals. The current culture determines what formats are accepted. To avoid any ambiguity, use strings formatted to the ISO8601 standard. If not specified, the current time zone is used.

Relative date-time string literals are also supported, using a minus sign followed by a TimeSpan. For example, “-1:30” means 1 hour and 30 minutes ago.

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

about_EnvTest_Filtering

August 9, 2024

Contributed by:

August 9, 2024

Contributed by:

about_EnvTest_Filtering

Topic

Short Description

Long Description

Examples

Array Properties

Complex Expressions

Paging

Filter Syntax Definition

In this article