en-GB/about_PSRule_Selectors.help.txt

TOPIC
    about_psrule_selectors
 
SHORT DESCRIPTION
    Describes PSRule Selectors including how to use and author them.
 
LONG DESCRIPTION
    PSRule executes rules to validate an object from input. When evaluating an
    object from input, PSRule can use selectors to perform complex matches of an object.
    - A selector is a YAML/JSON 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
    -
    Count
    -
    Equals
    -
    EndsWith
    -
    Exists
    -
    Greater
    -
    GreaterOrEquals
    -
    HasDefault
    -
    HasSchema
    -
    HasValue
    -
    In
    -
    IsLower
    -
    IsString
    -
    IsArray
    -
    IsBoolean
    -
    IsDateTime
    -
    IsInteger
    -
    IsNumeric
    -
    IsUpper
    -
    Less
    -
    LessOrEquals
    -
    Match
    -
    NotEquals
    -
    NotIn
    -
    NotMatch
    -
    SetOf
    -
    StartsWith
    -
    Subset
    -
    Version
    The following operators are available:
-
    AllOf
    -
    AnyOf
    -
    Not
    The following comparison properties are available:
-
    Field
    -
    Name
    -
    Type
    To learn more about conditions, operators, and properties see
    about_PSRule_Expressions
    .
    Currently the following limitations apply:
    - Selectors can evaluate: - Fields of the target object. - Type and name
    binding of the target object by using `name` and `type` comparison
    properties. - State variables such has `$PSRule` can not be evaluated.
    - Bound fields can not be evaluated.
 
    USING SELECTORS AS PRE-CONDITIONS
    Selectors can be referenced by name as a rule pre-condition by using the
    `-With` parameter. For example:
 
    Rule 'RuleWithSelector' -With 'BasicSelector' {
        # Rule condition
    }
 
    Selector pre-conditions can be used together with type and script block
    pre-conditions. If one or more selector pre-conditions are used, they are
    evaluated before type or script block pre-conditions.
 
    DEFINING SELECTORS
    Selectors can be defined with either YAML or JSON format, and can be
    included with a module or standalone `.Rule.yaml` or `.Rule.jsonc` file. In
    either case, define a selector within a file ending with the `.Rule.yaml` or
    `.Rule.jsonc` extension. A selector can be defined side-by-side with other
    resources such as baselines or module configurations.
    Selectors can also be defined within `.json` files. We recommend using
    `.jsonc` to view
    JSON with Comments
    in Visual Studio Code.
Use the following template to define a selector:
 
```yaml
SYNOPSIS: {{ SYNOPSIS }}
    apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name:
    '{{ Name }}' spec: if: { }
 
     
 
    jsonc [ { // Synopsis: {{ Synopsis }} "apiVersion":
    "github.com/microsoft/PSRule/v1", "kind": "Selector", "metadata": {
         "name": "{{ Name }}" }, "spec": { "if": {} } } ]
 
    Within the `if` object, one or more conditions or logical operators can be used.
     
    ## EXAMPLES
     
    ### Example Selectors.Rule.yaml
 
    yaml
 
EXAMPLE SELECTORS.RULE.YAML
    ---
 
SYNOPSIS: REQUIRE THE CUSTOMVALUE FIELD.
    apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name:
    RequireCustomValue spec: if: field: 'CustomValue' exists: true
    ---
 
SYNOPSIS: REQUIRE A NAME OR ALTERNATIVENAME.
    apiVersion: github.com/microsoft/PSRule/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/PSRule/v1 kind: Selector metadata: name:
    RequireSpecificCustomValue spec: if: field: 'CustomValue' in:
    - 'Value1' - 'Value2'
 
    ### Example Selectors.Rule.jsonc
 
    jsonc // Example Selectors.Rule.jsonc [ { // Synopsis: Require the
    CustomValue field. "apiVersion": "github.com/microsoft/PSRule/v1",
    "kind": "Selector", "metadata": { "name": "RequireCustomValue"
    }, "spec": { "if": { "field": "CustomValue",
    "exists": true } } }, { // Synopsis: Require a Name or
    AlternativeName. "apiVersion": "github.com/microsoft/PSRule/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/PSRule/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/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Selectors/.
 
SEE ALSO
    -
    Invoke-PSRule
 
KEYWORDS
    - Selectors
- Expressions
- PSRule