Skip to content

microsoft/PSRule

Repository files navigation

PSRule

A cross-platform PowerShell module (Windows, Linux, and macOS) with commands to validate objects on the pipeline using PowerShell syntax.

ci-badge

Disclaimer

This project is to be considered a proof-of-concept and not a supported product.

If you have any problems please check our GitHub issues page. If you do not see your problem captured, please file a new issue and follow the provided template.

Getting the modules

You can download and install the PSRule module from the PowerShell Gallery.

Module Description Downloads / instructions
PSRule Validate objects using PowerShell rules latest / instructions

Getting started

Define a rule

To define a rule use the Rule keyword.

Rule 'NameOfRule' {
    # Rule conditions
}

Within the body of the rule provide one or more conditions. A condition is valid PowerShell that results in $True or $False.

For example:

# Saved to isFruit.Rule.ps1
Rule 'isFruit' {
    # Condition to determine if the object is fruit
    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'
}

An optional result message can be added to by using the Hint keyword.

Rule 'isFruit' {
    # An additional message to display in output
    Hint 'Fruit is only Apple, Orange and Pear'

    # Condition to determine if the object is fruit
    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'
}

Execute a rule

To execute the rule use Invoke-PSRule.

For example:

# Define objects to validate
$items = @();
$items += [PSCustomObject]@{ Name = 'Fridge' };
$items += [PSCustomObject]@{ Name = 'Apple' };

# Validate each item using rules saved in current working path
$items | Invoke-PSRule;

The output of this example is:

   TargetName: Fridge

RuleName                            Outcome    Message
--------                            -------    -------
isFruit                             Fail       Fruit is only Apple, Orange and Pear


   TargetName: Apple

RuleName                            Outcome    Message
--------                            -------    -------
isFruit                             Pass       Fruit is only Apple, Orange and Pear

Additional options

To filter results to only non-fruit results, use Invoke-PSRule -Outcome Fail. Passed, failed and error results are shown by default.

# Only show non-fruit results
$items | Invoke-PSRule -Outcome Fail;

For a summary of results for each rule use Invoke-PSRule -As Summary.

For example:

# Show rule summary
$items | Invoke-PSRule -As Summary;

The output of this example is:

RuleName                            Pass  Fail  Outcome
--------                            ----  ----  -------
isFruit                             1     1     Fail

Scenarios

For practical examples of PSRule see:

Language reference

PSRule extends PowerShell with domain specific language (DSL) keywords, cmdlets and automatic variables.

Keywords

The following language keywords are used by the PSRule module:

  • 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.

Commands

The following commands exist in the PSRule module:

Concepts

The following conceptual topics exist in the PSRule module:

Schemas

PSRule uses the following schemas:

Changes and versioning

Modules in this repository will use the semantic versioning model to declare breaking changes from v1.0.0. Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments. For a list of module changes please see the change log.

Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. Pre-release versions should be considered experimental. Modules and change log details for pre-releases will be removed as standard releases are made available.

Maintainers

License

This project is licensed under the MIT License.