How to convert PSRule output to structured objects or formatted string.

[Marc013]

I would like to know if it is possible to format the output of PSRule (Assert-PSRule or Invoke-PSRule) to either structured objects or formatted string.

My use case.

In an Azure pipeline I execute PSRule to validate my templates (pre commit build validation).
This pipeline task is to show the results in a formatted string create an NUnit3 export and upload structured objects to Azure monitor.

PSRule is to be run via PowerShell script only.

---

This can be accomplished by running both Assert-PSRule and Invoke-PSRule. However, I do not want to run the rule validation twice.
It would be great when the output of a single cmdlet can be used for my use case.

If this is currently not possible it would be great when this functionality could be added to the cmdlet.

Suggestion

Perhaps a -Passthrough switch could be added to Assert-PSRule which passes through the structured objects while still showing the formatted string

[PSRule.Configuration.PSRuleOption]$psRuleOptions = New-PSRuleOption -Configuration @{ AZURE_BICEP_FILE_EXPANSION = $true }

[PSRule.Rules.RuleRecord[]]$PSRuleResults = Assert-PSRule -InputPath .\Templates\storage.bicep -Module PSRule.Rules.Azure -Format File -Outcome All -Path .\.ps-rule\ -Option $PSRuleOptions -Culture en -OutputPath .\results\__PSRuleResults.xml -OutputFormat NUnit3 -Passthrough

[BernieWhite]

@Marc013 Thank you for the question. Yes, you can do this. An additional parameter (-ResultVariable) exists on Assert-PSRule for this reason.

For example:

[PSRule.Configuration.PSRuleOption]$psRuleOptions = New-PSRuleOption -Configuration @{ AZURE_BICEP_FILE_EXPANSION = $true }

Assert-PSRule -InputPath .\Templates\storage.bicep -Module PSRule.Rules.Azure -Format File -Outcome All -Path .\.ps-rule\ -Option $PSRuleOptions -Culture en -OutputPath .\results\__PSRuleResults.xml -OutputFormat NUnit3 -ResultVariable results

# Get results
$results

See https://microsoft.github.io/PSRule/v2/commands/PSRule/en-US/Assert-PSRule/.

---

I hope that answers your question.

[Marc013]

@BernieWhite Thank you very much for your quick response.
I've used the additional parameter and got exactly what I was looking for.

However, I do have an additional questions.

Q: Why does Invoke-PSRule provide the results of not applicable rules?

When I run Assert-PSRule using parameter -ResultVariable the specified variable has a count of 19 objects. When I run cmdlet Invoke-PSRule using the exact same parameters (except -ResultVariable) I have a count of 285 objects.
After filtering out the Outcome -NE None 19 objects remain.

The commands I've run:

Assert-PSRule -InputPath .\Templates\storage.bicep -Module PSRule.Rules.Azure -Format File -Outcome All -Path .\.ps-rule\ -Option $PSRuleOptions -ResultVariable psruleResults

$psruleResultsInvoke = Invoke-PSRule -InputPath .\Templates\storage.bicep -Module PSRule.Rules.Azure -Format File -Outcome All -Path .\.ps-rule\ -Option $PSRuleOptions

$psruleResults.Count
19

$psruleResultsInvoke.Count
285

$filteredResutls = $psruleResultsInvoke | Where-Object -Property Outcome -NE -Value None
$filteredResutls.Count
19

[BernieWhite]

@Marc013 with the same outcome or all the number of results should be the same. If it's only returning failed rules it's a bug.

[Marc013]

@BernieWhite, the outcome of Assert-PSRule -ResultVariable is the same as the filtered results of Invoke-PSRule (filtered out Outcome None).
See below results.

In the unfiltered output of Invoke-PSRule there are 266 results with Outcome None. When looking at the rule names of these results I can understand the None value as the rules do not apply to the template.
As these rules do not apply I did not expect them to be part of the output at all. However, there might be a very valid reason these rules are present in the output. I'm trying to understand this. Hence my question.

$psruleResults | FT RuleName, Outcome

RuleName                            Outcome
--------                            -------
Azure.Template.TemplateFile            Pass
Azure.Template.TemplateSchema          Pass
Azure.Template.TemplateScheme          Pass
Azure.Template.ParameterMetadata       Pass
Azure.Template.Resources               Pass
Azure.Template.UseParameters           Pass
Azure.Template.DefineParameters        Pass
Azure.Template.UseVariables            Pass
Azure.Template.LocationDefault         Pass
Azure.Template.LocationType            Pass
Azure.Template.ResourceLocation        Pass
Azure.Template.UseLocationParameter    Pass
Azure.Template.ParameterMinMaxValue    Pass
Azure.Template.DebugDeployment         Pass
Azure.Template.ParameterDataTypes      Pass
Azure.Template.UseComments             Fail
Azure.Template.MinTLS                  Pass
Azure.Template.ParameterTLS            Pass
Azure.Template.Tags                    Fail

###

$filteredResults | FT RuleName, Outcome

RuleName                            Outcome
--------                            -------
Azure.Template.TemplateFile            Pass
Azure.Template.TemplateSchema          Pass
Azure.Template.TemplateScheme          Pass
Azure.Template.ParameterMetadata       Pass
Azure.Template.Resources               Pass
Azure.Template.UseParameters           Pass
Azure.Template.DefineParameters        Pass
Azure.Template.UseVariables            Pass
Azure.Template.LocationDefault         Pass
Azure.Template.LocationType            Pass
Azure.Template.ResourceLocation        Pass
Azure.Template.UseLocationParameter    Pass
Azure.Template.ParameterMinMaxValue    Pass
Azure.Template.DebugDeployment         Pass
Azure.Template.ParameterDataTypes      Pass
Azure.Template.UseComments             Fail
Azure.Template.MinTLS                  Pass
Azure.Template.ParameterTLS            Pass
Azure.Template.Tags                    Fail

[BernieWhite]

@Marc013 Both Invoke-PSRule and Assert-PSRule should returns the same results if -Outcome All. Which should be all results that have and have not have been processed. This seems to be a bug because it's not working that way. You are correct None results are rule that do not apply to a resource or were suppressed.

To get results that are for processed rules you could use -Outcome Error,Fail,Pass or just -Outcome Processed instead of -Outcome All.

In general practical use there is no benefit to using -Outcome All however, for unit testing when we are authoring new rules we use this option.

[Marc013]

@BernieWhite, specifying -Outcome Processed does the trick for me 😉

Thnx for explaining the purpose of the Outcome None results.