en-US/about_PSRule_Keywords.help.txt

TOPIC
    about_psrule_keywords
 
SHORT DESCRIPTION
    Describes the language keywords that can be used within PSRule document
    definitions.
 
LONG DESCRIPTION
    PSRule lets you define rules using PowerShell blocks. To create a rule use
    the `Rule` keyword. Within a rule several assertions can be used.
    - Assertion - A specific test that always evaluates to true or false.
    The following are the built-in keywords that can be used within PSRule:
    -
    Rule
    - A rule definition -
    Exists
    - Assert that a field or property must exist -
    Match
    - Assert that the field must match any of the regular expressions -
    AnyOf
    - Assert that any of the child expressions must be true -
    AllOf
    - Assert that all of the child expressions must be true -
    Within
    - Assert that the field must match any of the values -
    TypeOf
    - Assert that the object must be of a specific type -
    Recommend
    - Return the process to resolve the issue and pass the rule.
 
    RULE
    A `Rule` definition describes an individual business rule that will be
    applied to pipeline objects.
    To define a Rule use the `Rule` keyword followed by a name and a pair of
    squiggly brackets `{`. Within the `{ }` one or more expressions can be used.
    Syntax:
 
    Rule [-Name] <string> [-Tag <hashtable>] [-Type <string[]>] [-If <scriptBlock>] [-DependsOn <string[]>] [-Configure <hashtable>] [-Body] {
        ...
    }
 
    - `Name` - The name of the rule definition. This must be unique with in the
    same script file.
    - `Tag` - A hashtable of key/ value metadata that can be used to filter and
    identify rules and rule results.
    - `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.
    - `Body` - A script block definition of the rule containing one or more
    PSRule keywords and PowerShell expressions.
    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 }
 
    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] [-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.
    - `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'
    }
 
    Output:
If
    any
    the specified field exists then Exists will return `$True`, otherwise `$False`.
    If `-Not` is used, then if
    any
    of the specified fields exist then 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] [-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. - `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`.
 
    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> [-AllowedValue] <PSObject[]]> [-CaseSensitive] [-InputObject <PSObject>]
 
    - `Field` - The name of the field that will be evaluated on the pipeline object.
    - `AllowedValue` - A list of allowed 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. - `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'
    }
 
    Output:
If
    any
    of the allow values match the field value then Within returns `$True`,
    otherwise `$False`.
 
    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[]> [-InputObject <PSObject>]
 
    - `TypeName` - One or more type names which will be evaluated against the
    pipeline object. `TypeName` is case insensitive.
    - `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`.
 
    RECOMMEND
    The `Recommend` keyword is used within a `Rule` definition to provide a
    process 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.
    Previously this keyword was `Hint`. The previous keyword `Hint` is aliased
    by deprecated.
    Syntax:
 
    Recommend [-Message] <string>
 
    - `Message` - 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/BernieWhite/PSRule/blob/master/docs/keywords/PSRule/en-US/about_PSRule_Keywords.md.
 
SEE ALSO
    - [Invoke-PSRule]
 
KEYWORDS
    - Rule
    - Exists
    - Match
    - AnyOf
    - AllOf
    - Within
    - TypeOf
    - Recommend
    [Invoke-PSRule]:
    https://github.com/BernieWhite/PSRule/blob/master/docs/commands/PSRule/en-US/Invoke-PSRule.md