Download full document:

# about_broker_Filtering

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

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

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

    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.

    To retrieve all records, specify a large number for -MaxRecordCount. 
    As the value is an integer, you can use the following:

      Get-<Noun> -MaxRecordCount [int]::MaxValue

-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:

      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>

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

    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 }

    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*' }

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_Escape_Characters), or switch to a filter expression and the -eq 
operator:

  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

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:

  Get-<Noun> -Uid 123 
  Get-<Noun> -Enabled $true 
  Get-<Noun> -Duration 1:30:40 
  Get-<Noun> -NullableProperty $null

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'

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'

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

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 }

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

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*" }

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' }

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 }

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') }

PAGING The simplest way to page through data is to use the -Skip and -MaxRecordCount parameters. So, to read the first three pages of data with 10 records per page, use:

  Get-<Noun> -Skip 0  -MaxRecordCount 10 <other filtering criteria> 
  Get-<Noun> -Skip 10 -MaxRecordCount 10 <other filtering criteria> 
  Get-<Noun> -Skip 20 -MaxRecordCount 10 <other filtering criteria>

You must include the same filtering criteria on each call, and 
ensure that the data is sorted consistently.

The above approach is often acceptable, but as each call performs an 
independent query, data changes can result in records being skipped or 
appearing twice. One approach to improve this is to sort by a unique id 
field and then start the search for the next page at the unique id after 
the last unique id of the previous page. For example:

  # Get the first page 
  Get-<Noun> -MaxRecordCount 10 -SortBy SerialNumber

  SerialNumber  ... 
  ------------  --- 
  A120004 
  A120007 
  ... 7 other records ... 
  A120900

  # Get the next page 
  Get-<Noun> -MaxRecordCount 10 -Filter { FirstName -gt 'A120900' }

  SerialNumber  ... 
  ------------  --- 
  A120901 
  B220000 
  ...

FILTER SYNTAX DEFINITION

<Filter>        ::= <ScriptBlock> | <ComponentList>

<ScriptBlock>   ::= "{" <ComponentList> "}"

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

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

<Factor>        ::= "(" <ComponentList> ")" | 
                    <PropertyName> <ComparisonOperator> <Value> | 
                    <PropertyName>

<AndOrOperator> ::= "-and" | "-or"

<NotOperator>   ::= "-not" | "!"

<ComparisonOperator> 
                ::= "-eq" | "-ne" | "-le" | "-ge" | "-lt" | "-gt" | 
                    "-like" | "-notlike" | "-contains" | "-notcontains" | 
                    "-in" | "-notin"

<PropertyName>  ::= <simple name of property>

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