en-US/about_PSRule_Keywords.help.txt

TOPIC
    about_psrule_keywords
 
SHORT DESCRIPTION
    Describes the language keywords that can be used within PSRule rule
    definitions.
 
LONG DESCRIPTION
    PSRule lets you define rules using PowerShell blocks. To define a rule use
    the `Rule` keyword.
    -
    Rule
    - Creates a rule definition.
    The following are the built-in keywords that can be used within a rule definition:
    -
    AnyOf
    - Assert that any of the child expressions must be true. -
    AllOf
    - Assert that all of the child expressions must be true. -
    Exists
    - Assert that a field or property must exist. -
    Match
    - Assert that the field must match any of the regular expressions. -
    Reason
    - Return a reason for why the rule failed. -
    Recommend
    - Return a recommendation to resolve the issue and pass the rule. -
    TypeOf
    - Assert that the object must be of a specific type. -
    Within
    - Assert that the field must match any of the values.
    A subset of built-in keywords can be used within script preconditions:
    -
    Exists
    - Assert that a field or property must exist. -
    Match
    - Assert that the field must match any of the regular expressions. -
    TypeOf
    - Assert that the object must be of a specific type. -
    Within
    - Assert that the field must match any of the values.
 
    RULE
    A `Rule` definition describes an individual business rule that will be
    executed against each input object. Input objects can be passed on the
    PowerShell pipeline or supplied from file.
    To define a Rule use the `Rule` keyword followed by a name and a pair of
    squiggly brackets `{`. Within the `{ }` one or more conditions can be used.
    Conditions determine if the input object either
    Pass
    or
    Fail
    the rule.
Syntax:
 
    Rule [-Name] <string> [-Tag <hashtable>] [-When <string[]>] [-Type <string[]>] [-If <scriptBlock>] [-DependsOn <string[]>] [-Configure <hashtable>] [-ErrorAction <ActionPreference>] [-Body] {
        ...
    }
 
    - `Name` - The name of the rule definition. Each rule name must be unique.
    When packaging rules within a module, rule names must only be unique within
    the module. - `Tag` - A hashtable of key/ value metadata that can be used to
    filter and identify rules and rule results.
    - `When` - A selector precondition that must evaluate true before the rule
    is executed.
    - `Type` - A type precondition that must match the
    TargetType
    of the pipeline object before the rule is executed. - `If` - A script
    precondition that must evaluate to `$True` before the rule is executed.
    - `DependsOn` - A list of rules this rule depends on.
    Rule dependencies must execute successfully before this rule is executed. -
    `Configure` - A set of default configuration values. These values are only
    used when the baseline configuration does not contain the key. -
    `ErrorAction` - The action to take when an error occur. Only a subset of
    preferences are supported, either `Stop` or `Ignore`. When `-ErrorAction` is
    not specified the default preference is `Stop`. When errors are ignored a
    rule will pass or fail based on the rule condition. Uncaught exceptions will
    still cause rule return an error outcome. - `Body` - A script block that
    specifies one or more conditions that are required for the rule to
    Pass
    .
    A condition is any valid PowerShell that return either `$True` or `$False`.
    Optionally, PSRule keywords can be used to help build out conditions
    quickly. When a rule contains more then one condition, all must return
    `$True` for the rule to
    Pass
    . If any one condition returns `$False` the rule has failed.
    The following restrictions apply:
    - Rule conditions should only return `$True` or `$False`. Other objects
    should be caught with `Out-Null` or null assigned like `$Null = SomeCommand`.
    - The `Rule` keyword can not be nested in a `Rule` definition.
    - Variables and functions defined within `.Rule.ps1` files, but outside the
    `Rule` definition block are not accessible unless the `Global` scope is applied.
    - Functions and variables within the caller's scope (the scope calling
    `Invoke-PSRule`, `Get-PSRule`, `Test-PSRuleTarget`) are not accessible.
    - Cmdlets that require user interaction are not supported, i.e. `Read-Host`.
    - Script preconditions can contain `Exists`, `Match`, `TypeOf` and `Within` keywords.
    Examples:
 
    # Synopsis: This rule checks for the presence of a name field
    Rule 'NameMustExist' {
        Exists 'Name'
    }
 
    # Synopsis: This rule checks that the title field is valid, when the rule NameMustExist is successful
    Rule 'TitleIsValid' -DependsOn 'NameMustExist' {
        Within 'Title' 'Mr', 'Miss', 'Mrs', 'Ms'
    }
 
    # Synopsis: This rule uses a threshold stored as $Configuration.minInstanceCount
    Rule 'HasMinInstances' {
        $TargetObject.Sku.capacity -ge $Configuration.minInstanceCount
    } -Configure @{ minInstanceCount = 2 }
 
    # Synopsis: This rule still passes because errors are ignored
    Rule 'WithRuleErrorActionIgnore' -ErrorAction Ignore {
        Write-Error 'Some error';
        $True;
    }
 
    EXISTS
    The `Exists` assertion is used within a `Rule` definition to assert that a
    field
    or property must exist on the pipeline object.
Syntax:
 
    Exists [-Field] <string[]> [-CaseSensitive] [-Not] [-All] [-Reason <string>] [-InputObject <PSObject>]
 
    - `Field` - One or more fields/ properties that must exist on the pipeline object.
    - `CaseSensitive` - The field name must match exact case.
    - `Not` - Instead of checking if the field names exists they should not exist.
    - `All` - All fields must exist on the pipeline object, instead of only one.
    - `Reason` - A custom reason provided if the condition fails.
    - `InputObject` - Supports objects being piped directly.
    Examples:
 
    # Synopsis: Checks for the presence of a name property
    Rule 'nameMustExist' {
        Exists 'Name'
    }
 
    # Synopsis: Checks for the presence of name nested under the metadata property
    Rule 'nameMustExist' {
        Exists 'metadata.name'
    }
 
    # Synopsis: Checks for the presence of name nested under the metadata property
    Rule 'nameMustExist' {
        $TargetObject.metadata | Exists 'name'
    }
 
    # Synopsis: Checks that the NotName property does not exist
    Rule 'NotNameMustNotExist' {
        Exists -Not 'NotName'
    }
 
    # Synopsis: Checks one of Name or AlternativeName properties exist
    Rule 'EitherMustExist' {
        Exists 'Name', 'AlternativeName'
    }
 
    # Synopsis: Checks that both Name and Type properties exist
    Rule 'AllMustExist' {
        Exists 'Name', 'Type' -All
    }
 
    Output:
If
    any
    the specified fields exists then `Exists` will return `$True`, otherwise `$False`.
    If `-Not` is used, then if
    any
    of the fields exist then `Exists` will return `$False` otherwise `$True`.
    If `-All` is used, then then
    all
    of the fields must exist, or not with the `-Not` switch. If all fields exist
    then `Exists` will return `$True`, otherwise `$False`. If `-Not` is used
    with `-All`, if
    all
    of the fields exist `Exists` will return `$False` otherwise `$True`.
 
    MATCH
    The `Match` assertion is used within a `Rule` definition to assert that the
    value of a
    field
    or property from pipeline data must match one or more regular expressions.
    To optionally perform a case sensitive match use the `-CaseSensitive`
    switch, otherwise a case insensitive match will be used.
    Syntax:
 
    Match [-Field] <string> [-Expression] <string[]> [-CaseSensitive] [-Not] [-Reason <string>] [-InputObject <PSObject>]
 
    - `Field` - The name of the field that will be evaluated on the pipeline object.
    - `Expression` - One or more regular expressions that will be used to match
    the value of the field.
    - `CaseSensitive` - The field
    value
    must match exact case. - `Not` - Instead of checking the field value
    matches, the field value must not match any of the expressions.
    - `Reason` - A custom reason provided if the condition fails.
    - `InputObject` - Supports objects being piped directly.
    Examples:
 
    # Synopsis: Check that PhoneNumber is complete and formatted correctly
    Rule 'validatePhoneNumber' {
        Match 'PhoneNumber' '^(\+61|0)([0-9] {0,1}){8}[0-9]$'
    }
 
    Output:
If
    any
    of the specified regular expressions match the field value then `Match`
    returns `$True`, otherwise `$False`.
    When `-Not` is used, if any of the regular expressions match the field value
    with `Match` return `$False`, otherwise `$True`.
 
    WITHIN
    The `Within` assertion is used within a `Rule` definition to assert that the
    value of a field or property from pipeline data must equal an item from a
    supplied list of allowed values. To optionally perform a case sensitive
    match use the `-CaseSensitive` switch, otherwise a case insensitive match
    will be used.
    Syntax:
 
    Within [-Field] <string> [-Not] [-Like] [-Value] <PSObject[]> [-CaseSensitive] [-Reason <string>] [-InputObject <PSObject>]
 
    - `Field` - The name of the field that will be evaluated on the pipeline object.
    - `Value` - A list of values that the field value must match.
    - `CaseSensitive` - The field
    value
    must match exact case. Only applies when the field value and allowed values
    are strings. - `Not` - Instead of checking the field value matches, the
    field value must not match any of the supplied values.
    - `Like` - Instead of using an exact match, a wildcard match is used.
    This switch can only be used when `Value` a string type. - `Reason` - A
    custom reason provided if the condition fails.
    - `InputObject` - Supports objects being piped directly.
    Examples:
 
    # Synopsis: Ensure that the title field has one of the allowed values
    Rule 'validateTitle' {
        Within 'Title' 'Mr', 'Miss', 'Mrs', 'Ms'
    }
 
    # Synopsis: Ensure that the title field is not one of the specified values
    Rule 'validateTitle' {
        Within 'Title' -Not 'Mr', 'Sir'
    }
 
    # Synopsis: Ensure that the title field has one of the allowed values
    Rule 'validateTitle' {
        Within 'Title' -Like 'Mr', 'M*s'
    }
 
    Output:
If
    any
    of the values match the field value then `Within` returns `$True`, otherwise `$False`.
    When `-Not` is used, if any of the values match the field value with
    `Within` return `$False`, otherwise `$True`.
    When `-Like` is used, the field value is matched against one or more
    wildcard expressions.
 
    ALLOF
    The `AllOf` assertion is used within a `Rule` definition to aggregate the
    result of assertions within a pair of squiggly brackets `{ }`. `AllOf` is
    functionally equivalent to a binary
    and
    , where when all of the contained assertions return `$True`, `AllOf` will
    return `$True`.
    Syntax:
 
    AllOf [-Body] {
        <assertion>
        [<assertion>]
        ...
    }
 
    - `Body` - A script block definition of the containing one or more PSRule
    keywords and PowerShell expressions.
    Examples:
 
    # Synopsis: The Name field must exist and have a value of either John or Jane
    Rule 'nameCheck' {
        AllOf {
            Exists 'Name'
            Within 'Name' 'John', 'Jane'
        }
    }
 
    Output:
If
    all
    of the assertions return `$True` AllOf will return `$True`, otherwise
    `$False`.
 
    ANYOF
    The `AnyOf` assertion is used within a `Rule` definition to aggregate the
    result of assertions within a pair of squiggly brackets `{ }`. `AnyOf` is
    functionally equivalent to a binary
    or
    , where if any of the contained assertions returns `$True`, `AnyOf` will
    return `$True`.
    Syntax:
 
    AnyOf [-Body] {
        <assertion>
        [<assertion>]
        ...
    }
 
    - `Body` - A script block definition of the containing one or more PSRule
    keywords and PowerShell expressions.
    Examples:
 
    # Synopsis: The Last or Surname field must exist
    Rule 'personCheck' {
        AnyOf {
            Exists 'Last'
            Exists 'Surname'
        }
    }
 
    Output:
If
    any
    of the assertions return `$True` AnyOf will return `$True`, otherwise
    `$False`.
 
    TYPEOF
    The `TypeOf` assertion is used within a `Rule` definition to evaluate if the
    pipeline object matches one or more of the supplied type names.
    Syntax:
 
    TypeOf [-TypeName] <string[]> [-Reason <string>] [-InputObject <PSObject>]
 
    - `TypeName` - One or more type names which will be evaluated against the
    pipeline object. `TypeName` is case sensitive. - `Reason` - A custom reason
    provided if the condition fails.
    - `InputObject` - Supports objects being piped directly.
    Examples:
 
    # Synopsis: The object must be a hashtable
    Rule 'objectType' {
        TypeOf 'System.Collections.Hashtable'
    }
 
    Output:
If
    any
    the specified type names match the pipeline object then TypeOf will return
    `$True`, otherwise `$False`.
 
    REASON
    The `Reason` keyword is used within a `Rule` definition to provide a message
    that indicates the reason the rule failed. The reason is included in
    detailed results.
    A reason is only included when the rule fails or errors. The outcomes `Pass`
    and `None` do not include reason.
    Use this keyword when you want to implement custom logic. Built-in keywords
    including `Exists`, `Match`, `Within` and `TypeOf` automatically include a
    reason when they fail.
    Syntax:
 
    Reason [-Text] <string>
 
    - `Text` - A message that includes the reason for the failure.
Examples:
 
    # Synopsis: Provide reason the rule failed
    Rule 'objectRecommend' {
        Reason 'A minimum of two (2) instances are required'
        $TargetObject.count -ge 2
    }
 
    Output:
None.
 
    RECOMMEND
    The `Recommend` keyword is used within a `Rule` definition to provide a
    recommendation to resolve the issue and pass the rule. This may include
    manual steps to change that state of the object or the desired state
    accessed by the rule.
    The recommendation can only be set once per rule. Each object will use the
    same recommendation.
    Syntax:
 
    Recommend [-Text] <string>
 
    - `Text` - A message that includes the process to resolve the issue and pass
    the rule.
    Examples:
 
    # Synopsis: Provide recommendation to resolve the issue
    Rule 'objectRecommend' {
        Recommend 'Use at least two (2) instances'
        $TargetObject.count -ge 2
    }
 
    Output:
None.
 
EXAMPLES
    # Synopsis: App Service Plan has multiple instances
    Rule 'appServicePlan.MinInstanceCount' -If { $TargetObject.ResourceType -eq 'Microsoft.Web/serverfarms' } {
        Recommend 'Use at least two (2) instances'
     
        $TargetObject.Sku.capacity -ge 2
    }
 
NOTE
    An online version of this document is available at
    https://github.com/Microsoft/PSRule/blob/main/docs/keywords/PSRule/en-US/about_PSRule_Keywords.md.
 
SEE ALSO
    - [Invoke-PSRule]
 
KEYWORDS
    - Rule
    - Exists
    - Match
    - AnyOf
    - AllOf
    - Within
    - TypeOf
    - Reason
    - Recommend
    [Invoke-PSRule]:
    https://github.com/Microsoft/PSRule/blob/main/docs/commands/PSRule/en-US/Invoke-PSRule.md