Assert-PSRule#
SYNOPSIS#
Evaluate objects against matching rules and assert any failures.
SYNTAX#
Input (Default)#
Assert-PSRule [-Module <String[]>] [-Format <InputFormat>] [-Baseline <BaselineOption>]
[-Convention <String[]>] [-Style <OutputStyle>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]
[[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]
[-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]
[-Culture <String[]>] -InputObject <PSObject> [-ResultVariable <String>] [-WhatIf] [-Confirm]
[<CommonParameters>]
InputPath#
Assert-PSRule -InputPath <String[]> [-Module <String[]>] [-Format <InputFormat>] [-Baseline <BaselineOption>]
[-Convention <String[]>] [-Style <OutputStyle>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]
[[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]
[-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]
[-Culture <String[]>] [-ResultVariable <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
DESCRIPTION#
Evaluate objects against matching rules and assert any failures. Objects can be specified directly from the pipeline or provided from file.
The commands Invoke-PSRule
and Assert-PSRule
provide similar functionality, as differ as follows:
Invoke-PSRule
writes results as structured objectsAssert-PSRule
writes results as a formatted string.
EXAMPLES#
Example 1#
@{ Name = 'Item 1' } | Assert-PSRule;
Evaluate a simple hashtable on the pipeline against rules loaded from the current working path.
Example 2#
# Define objects to validate
$items = @();
$items += [PSCustomObject]@{ Name = 'Fridge' };
$items += [PSCustomObject]@{ Name = 'Apple' };
# Validate each item using rules saved in current working path
$items | Assert-PSRule -Path .\docs\scenarios\fruit\
-> Fridge : System.Management.Automation.PSCustomObject
[FAIL] isFruit
-> Apple : System.Management.Automation.PSCustomObject
[PASS] isFruit
Assert-PSRule : One or more rules reported failure.
At line:1 char:10
+ $items | Assert-PSRule -Path .\docs\scenarios\fruit\
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidData: (:) [Assert-PSRule], FailPipelineException
+ FullyQualifiedErrorId : PSRule.Fail,Assert-PSRule
Evaluate an array of objects on the pipeline against rules loaded a specified relative path.
Example 3#
$items | Assert-PSRule -Module PSRule.Rules.Azure -o NUnit3 -OutputPath .\reports\results.xml
Evaluate items from a pre-installed rules module PSRule.Rules.Azure. Additionally save the results as a NUnit report.
Example 4#
$items | Assert-PSRule -Path .\docs\scenarios\fruit\ -ResultVariable resultRecords;
Evaluate items and additionally save the results into a variable resultRecords
.
PARAMETERS#
-InputPath#
Instead of processing objects from the pipeline, import objects file the specified file paths.
Type: String[]
Parameter Sets: InputPath
Aliases: f
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Format#
Configures the input format for when a string is passed in as a target object.
When the -InputObject
parameter or pipeline input is used, strings are treated as plain text by default.
Set this option to either Yaml
, Json
, Markdown
, PowerShellData
to have PSRule deserialize the object.
When the -InputPath
parameter is used with a file path or URL.
If the Detect
format is used, the file extension will be used to automatically detect the format.
When -InputPath
is not used, Detect
is the same as None
.
When this option is set to File
PSRule scans the path and subdirectories specified by -InputPath
.
Files are treated as objects instead of being deserialized.
Additional, PSRule uses the file extension as the object type.
When files have no extension the whole file name is used.
See about_PSRule_Options
for details.
This parameter takes precedence over the Input.Format
option if set.
Type: InputFormat
Parameter Sets: (All)
Aliases:
Accepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect
Required: False
Position: Named
Default value: Detect
Accept pipeline input: False
Accept wildcard characters: False
-Baseline#
Specifies an explicit baseline by name to use for evaluating rules. Baselines can contain filters and custom configuration that overrides the defaults.
Type: BaselineOption
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Convention#
Specifies conventions by name to execute in the pipeline when processing objects.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Culture#
Specifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet Get-Culture
shows the current culture of PowerShell.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Module#
Search for rule definitions within a module.
If no sources are specified by -Path
, -Module
, or options, the current working directory is used.
Type: String[]
Parameter Sets: (All)
Aliases: m
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Name#
The name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.
Type: String[]
Parameter Sets: (All)
Aliases: n
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ObjectPath#
The name of a property to use instead of the pipeline object.
If the property specified by ObjectPath
is a collection or an array, then each item in evaluated separately.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-TargetType#
Filters input objects by TargetType.
If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.
By default, all objects are processed.
This parameter if set, overrides the Input.TargetType
option.
To change the field TargetType is bound to set the Binding.TargetType
option.
For details see the about_PSRule_Options help topic.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Option#
Additional options that configure execution.
A PSRuleOption
can be created by using the New-PSRuleOption
cmdlet.
Alternatively, a hashtable or path to YAML file can be specified with options.
For more information on PSRule options see about_PSRule_Options.
Type: PSRuleOption
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-OutputPath#
Specifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-OutputFormat#
Configures the format that output is written.
This parameter has no affect when -OutputPath
is not specified.
The following format options are available:
- None - Output is presented as an object using PowerShell defaults. This is the default.
- Yaml - Output is serialized as YAML.
- Json - Output is serialized as JSON.
- Markdown - Output is serialized as Markdown.
- NUnit3 - Output is serialized as NUnit3 (XML).
- Csv - Output is serialized as a comma separated values (CSV).
- Sarif - Output is serialized as SARIF.
The Wide
format is not applicable to Assert-PSRule
.
Type: OutputFormat
Parameter Sets: (All)
Aliases: o
Accepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Sarif
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Style#
Configures the style that results will be presented in.
The following styles are available:
- Client - Output is written to the host directly in green/ red to indicate outcome.
- Plain - Output is written as an unformatted string. This option can be redirected to a file.
- AzurePipelines - Output is written for integration Azure Pipelines.
- GitHubActions - Output is written for integration GitHub Actions.
- VisualStudioCode - Output is written for integration with Visual Studio Code.
- Detect - Output style will be detected by checking the environment variables. This is the default.
Detect uses the following logic:
- If the
TF_BUILD
environment variable is set totrue
,AzurePipelines
will be used. - If the
GITHUB_ACTIONS
environment variable is set totrue
,GitHubActions
will be used. - If the
TERM_PROGRAM
environment variable is set tovscode
,VisualStudioCode
will be used. - Use
Client
.
Each of these styles outputs to the host. To capture output as a string redirect the information stream.
For example: 6>&1
Type: OutputStyle
Parameter Sets: (All)
Aliases:
Accepted values: Client, Plain, AzurePipelines, GitHubActions, VisualStudioCode, Detect
Required: False
Position: Named
Default value: Client
Accept pipeline input: False
Accept wildcard characters: False
-As#
The type of results to produce. Detailed results are generated by default.
The following result formats are available:
Detail
- Returns pass/ fail results for each rule per object.Summary
- Failure or errors are shown but passing results are summarized.
Type: ResultFormat
Parameter Sets: (All)
Aliases:
Accepted values: Detail, Summary
Required: False
Position: Named
Default value: Detail
Accept pipeline input: False
Accept wildcard characters: False
-Outcome#
Filter output to only show rule results with a specific outcome.
Type: RuleOutcome
Parameter Sets: (All)
Aliases:
Accepted values: Pass, Fail, Error, None, Processed, All
Required: False
Position: Named
Default value: Pass, Fail, Error
Accept pipeline input: False
Accept wildcard characters: False
-Path#
One or more paths to search for rule definitions within.
Type: String[]
Parameter Sets: (All)
Aliases: p
Required: False
Position: 0
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Tag#
Only get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.
When more than one tag is used, all tags must match. Tags are not case sensitive.
A tag value of *
may be used to filter rules to any rule with the tag set, regardless of tag value.
An array of tag values can be used to match a rule with either value.
i.e. severity = important, critical
matches rules with a category of either important
or critical
.
Type: Hashtable
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-InputObject#
The pipeline object to process rules for.
Type: PSObject
Parameter Sets: Input
Aliases: TargetObject
Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False
-ResultVariable#
Stores output result objects in the specified variable.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-WhatIf#
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Confirm#
Prompts you for confirmation before running the cmdlet.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters#
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS#
System.Management.Automation.PSObject#
You can pipe any object to Assert-PSRule.