Describes PSDocs Selectors including how to use and author them.
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:
The following comparison properties are available:
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
.
- State variables such as
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.
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.
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
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
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'
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'
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'
The exists
condition determines if the specified field exists.
Syntax:
exists: <bool>
- When
exists: true
, exists will returntrue
if the field exists. - When
exists: false
, exists will returntrue
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
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
Syntax:
greater: <int>
For example:
apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
name: 'ExampleGreater'
spec:
if:
field: 'Name'
greater: 3
Syntax:
greaterOrEquals: <int>
For example:
apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
name: 'ExampleGreaterOrEquals'
spec:
if:
field: 'Name'
greaterOrEquals: 3
The hasValue
condition determines if the field exists and has a non-empty value.
Syntax:
hasValue: <bool>
- When
hasValue: true
, hasValue will returntrue
if the field is not empty. - When
hasValue: false
, hasValue will returntrue
if the field is empty.
For example:
apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
name: 'ExampleHasValue'
spec:
if:
field: 'Name'
hasValue: true
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'
The isLower
condition determines if the operand is a lowercase string.
Syntax:
isLower: <bool>
- When
isLower: true
, isLower will returntrue
if the operand is a lowercase string. Non-letter characters are ignored. - When
isLower: false
, isLower will returntrue
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
The isString
condition determines if the operand is a string or other type.
Syntax:
isString: <bool>
- When
isString: true
, isString will returntrue
if the operand is a string. - When
isString: false
, isString will returntrue
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
The isUpper
condition determines if the operand is an uppercase string.
Syntax:
isUpper: <bool>
- When
isUpper: true
, isUpper will returntrue
if the operand is an uppercase string. Non-letter characters are ignored. - When
isUpper: false
, isUpper will returntrue
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
Syntax:
less: <int>
For example:
apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
name: 'ExampleLess'
spec:
if:
field: 'Name'
less: 3
Syntax:
lessOrEquals: <int>
For example:
apiVersion: github.com/microsoft/PSDocs/v1
kind: Selector
metadata:
name: 'ExampleLessOrEquals'
spec:
if:
field: 'Name'
lessOrEquals: 3
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)$'
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
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'
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'
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)$'
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:
- 'http://'
- 'https://'
# 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'
An online version of this document is available at https://microsoft.github.io/PSDocs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md.
- Selectors
- PSDocs