Badges#
Describes using the badge API with PSRule.
Description#
PSRule executes rules to validate an object from input. When processing input it may be necessary to perform custom actions before or after rules execute. Conventions provide an extensibility point that can be shipped with or external to standard rules. The badge API can be used to create badges within a convention.
Using the API#
PSRule provides the $PSRule
built-in variable that exposes the badge API.
By using the $PSRule.Badges.Create
method you can create a standard or custom badge.
The create method provides the following overloads:
// Create a badge for the worst case of an analyzed object.
IBadge Create(InvokeResult result);
// Create a badge for the worst case of all analyzed objects.
IBadge Create(IEnumerable<InvokeResult> result);
// Create a custom badge.
IBadge Create(string title, BadgeType type, string label);
A badge once created can be read as a string or written to disk with the following methods:
// Get the badge as SVG text content.
string ToSvg();
// Write the SVG badge content directly to disk.
void ToFile(string path);
Defining conventions#
To define a convention, add a Export-PSRuleConvention
block within a .Rule.ps1
file.
The .Rule.ps1
must be in an included path or module with -Path
or -Module
.
The Export-PSRuleConvention
block works similar to the Rule
block.
Each convention must have a unique name.
Currently the badge API support creating badges in the -End
block.
For example:
# Synopsis: A convention that generates a badge for an aggregate result.
Export-PSRuleConvention 'Local.Aggregate' -End {
$PSRule.Badges.Create($PSRule.Output).ToFile('out/badges/aggregate.svg');
}
# Synopsis: A convention that generates a custom badge.
Export-PSRuleConvention 'Local.CustomBadge' -End {
$PSRule.Badges.Create('PSRule', [PSRule.Badges.BadgeType]::Success, 'OK').ToFile('out/badges/custom.svg');
}
Using conventions#
A convention can be included by using the -Convention
parameter when executing a PSRule cmdlet.
Alternatively, conventions can be included with options.
To use a convention specify the name of the convention by name.
For example:
Invoke-PSRule -Convention 'Local.Aggregate';