PSDocs_Selectors

about_PSDocs_Selectors

SHORT DESCRIPTION

Describes PSDocs Selectors including how to use and author them.

LONG DESCRIPTION

PSDocs executes document to validate an object from input. When evaluating an object from input, PSDocs can use selectors to perform complex matches of an object.

A selector is a YAML-based expression that evaluates an object.
Each selector is comprised of nested conditions, operators, and comparison properties.
Selectors must use one or more available conditions with a comparison property to evaluate the object.
Optionally a condition can be nested in an operator.
Operators can be nested within other operators.

The following conditions are available:

Contains
Equals
EndsWith
Exists
Greater
GreaterOrEquals
HasValue
In
IsLower
IsString
IsUpper
Less
LessOrEquals
Match
NotEquals
NotIn
NotMatch
StartsWith

The following operators are available:

AllOf
AnyOf
Not

The following comparison properties are available:

Field

Currently the following limitations apply:

Selectors can only evaluate a field of the target object. The following examples can not be evaluated by selectors:
- State variables such as $PSDocs.

Using selectors as pre-conditions

Selectors can be referenced by name as a document pre-condition by using the -With parameter. For example:

Document 'SampleWithSelector' -With 'BasicSelector' {
    # Additional content
}

Selector pre-conditions can be used together with script block pre-conditions. If one or more selector pre-conditions are used, they are evaluated before script block pre-conditions.

Defining selectors

Selectors are defined in YAML and can be included within a module or standalone .Doc.yaml file. In either case, define a selector within a file ending with the .Doc.yaml extension.

Use the following template to define a selector:

---
# Synopsis: {{ Synopsis }}
apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: '{{ Name }}'
spec:
  if: { }

Within the if object, one or more conditions or logical operators can be used.

AllOf

The allOf operator is used to require all nested expressions to match. When any nested expression does not match, allOf does not match. This is similar to a logical and operation.

Syntax:

allOf: <expression[]>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleAllOf'
spec:
  if:
    allOf:
    # Both Name and Description must exist.
    - field: 'Name'
      exists: true
    - field: 'Description'
      exists: true

AnyOf

The anyOf operator is used to require one or more nested expressions to match. When any nested expression matches, allOf matches. This is similar to a logical or operation.

Syntax:

anyOf: <expression[]>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleAnyOf'
spec:
  if:
    anyOf:
    # Name and/ or AlternativeName must exist.
    - field: 'Name'
      exists: true
    - field: 'AlternativeName'
      exists: true

Contains

The contains condition can be used to determine if the operand contains a specified sub-string. One or more strings to compare can be specified.

Syntax:

contains: <string | array>

If the operand is a field, and the field does not exist, contains always returns false.

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleContains'
spec:
  if:
    anyOf:
    - field: 'url'
      contains: '/azure/'
    - field: 'url'
      contains:
      - 'github.io'
      - 'github.com'

Equals

The equals condition can be used to compare if a field is equal to a supplied value.

Syntax:

equals: <string | int | bool>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleEquals'
spec:
  if:
    field: 'Name'
    equals: 'TargetObject1'

EndsWith

The endsWith condition can be used to determine if the operand ends with a specified string. One or more strings to compare can be specified.

Syntax:

endsWith: <string | array>

If the operand is a field, and the field does not exist, endsWith always returns false.

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleEndsWith'
spec:
  if:
    anyOf:
    - field: 'hostname'
      endsWith: '.com'
    - field: 'hostname'
      endsWith:
      - '.com.au'
      - '.com'

Exists

The exists condition determines if the specified field exists.

Syntax:

exists: <bool>

When exists: true, exists will return true if the field exists.
When exists: false, exists will return true if the field does not exist.

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleExists'
spec:
  if:
    field: 'Name'
    exists: true

Field

The comparison property field is used with a condition to determine field of the object to evaluate. A field can be:

A property name.
A key within a hashtable or dictionary.
An index in an array or collection.
A nested path through an object.

Syntax:

field: <string>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleField'
spec:
  if:
    field: 'Properties.securityRules[0].name'
    exists: true

Greater

Syntax:

greater: <int>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleGreater'
spec:
  if:
    field: 'Name'
    greater: 3

GreaterOrEquals

Syntax:

greaterOrEquals: <int>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleGreaterOrEquals'
spec:
  if:
    field: 'Name'
    greaterOrEquals: 3

HasValue

The hasValue condition determines if the field exists and has a non-empty value.

Syntax:

hasValue: <bool>

When hasValue: true, hasValue will return true if the field is not empty.
When hasValue: false, hasValue will return true if the field is empty.

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleHasValue'
spec:
  if:
    field: 'Name'
    hasValue: true

In

The in condition can be used to compare if a field contains one of the specified values.

Syntax:

in: <array>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleIn'
spec:
  if:
    field: 'Name'
    in:
    - 'Value1'
    - 'Value2'

IsLower

The isLower condition determines if the operand is a lowercase string.

Syntax:

isLower: <bool>

When isLower: true, isLower will return true if the operand is a lowercase string. Non-letter characters are ignored.
When isLower: false, isLower will return true if the operand is not a lowercase string.
If the operand is a field, and the field does not exist isLower always returns false.

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleIsLower'
spec:
  if:
    field: 'Name'
    isLower: true

IsString

The isString condition determines if the operand is a string or other type.

Syntax:

isString: <bool>

When isString: true, isString will return true if the operand is a string.
When isString: false, isString will return true if the operand is not a string or is null.
If the operand is a field, and the field does not exist isString always returns false.

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleIsString'
spec:
  if:
    field: 'Name'
    isString: true

IsUpper

The isUpper condition determines if the operand is an uppercase string.

Syntax:

isUpper: <bool>

When isUpper: true, isUpper will return true if the operand is an uppercase string. Non-letter characters are ignored.
When isUpper: false, isUpper will return true if the operand is not an uppercase string.
If the operand is a field, and the field does not exist isUpper always returns false.

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleIsUpper'
spec:
  if:
    field: 'Name'
    isUpper: true

Less

Syntax:

less: <int>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleLess'
spec:
  if:
    field: 'Name'
    less: 3

LessOrEquals

Syntax:

lessOrEquals: <int>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleLessOrEquals'
spec:
  if:
    field: 'Name'
    lessOrEquals: 3

Match

The match condition can be used to compare if a field matches a supplied regular expression.

Syntax:

match: <string>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleMatch'
spec:
  if:
    field: 'Name'
    match: '$(abc|efg)$'

Not

The any operator is used to invert the result of the nested expression. When a nested expression matches, not does not match. When a nested expression does not match, not matches.

Syntax:

not: <expression>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleNot'
spec:
  if:
    not:
      # The AlternativeName field must not exist.
      field: 'AlternativeName'
      exists: true

NotEquals

The notEquals condition can be used to compare if a field is equal to a supplied value.

Syntax:

notEquals: <string | int | bool>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleNotEquals'
spec:
  if:
    field: 'Name'
    notEquals: 'TargetObject1'

NotIn

The notIn condition can be used to compare if a field does not contains one of the specified values.

Syntax:

notIn: <array>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleNotIn'
spec:
  if:
    field: 'Name'
    notIn:
    - 'Value1'
    - 'Value2'

NotMatch

The notMatch condition can be used to compare if a field does not matches a supplied regular expression.

Syntax:

notMatch: <string>

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleNotMatch'
spec:
  if:
    field: 'Name'
    notMatch: '$(abc|efg)$'

StartsWith

The startsWith condition can be used to determine if the operand starts with a specified string. One or more strings to compare can be specified.

Syntax:

startsWith: <string | array>

If the operand is a field, and the field does not exist, startsWith always returns false.

For example:

apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: 'ExampleStartsWith'
spec:
  if:
    anyOf:
    - field: 'url'
      startsWith: 'http'
    - field: 'url'
      startsWith:
      - 'https://'
      - 'https://'

EXAMPLES

Example Selectors.Doc.yaml

# Example Selectors.Doc.yaml
---
# Synopsis: Require the CustomValue field.
apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: RequireCustomValue
spec:
  if:
    field: 'CustomValue'
    exists: true

---
# Synopsis: Require a Name or AlternativeName.
apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: RequireName
spec:
  if:
    anyOf:
    - field: 'AlternateName'
      exists: true
    - field: 'Name'
      exists: true

---
# Synopsis: Require a specific CustomValue
apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
  name: RequireSpecificCustomValue
spec:
  if:
    field: 'CustomValue'
    in:
    - 'Value1'
    - 'Value2'

NOTE

An online version of this document is available at https://microsoft.github.io/PSDocs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md.

KEYWORDS

Selectors
PSDocs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!