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 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: # Description: This rule checks for the presence of a name field Rule 'NameMustExist' { Exists 'Name' } # Description: 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' } # Description: 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: # Description: Checks for the presence of a name property Rule 'nameMustExist' { Exists 'Name' } # Description: Checks for the presence of name nested under the metadata property Rule 'nameMustExist' { Exists 'metadata.name' } # Description: 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: # Description: 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: # Description: 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: # Description: 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: # Description: 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: # Description: 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`. EXAMPLES # Description: App Service Plan has multiple instances Rule 'appServicePlan.MinInstanceCount' -If { $TargetObject.ResourceType -eq 'Microsoft.Web/serverfarms' } { Hint '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 [Invoke-PSRule]: https://github.com/BernieWhite/PSRule/blob/master/docs/commands/PSRule/en-US/Invoke-PSRule.md |