Conventions#
Describes PSRule Conventions including how to use and author them.
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. Each convention, hooks into one or more places within the pipeline.
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 'ExampleConvention';
If multiple conventions are specified in an array, all are executed in they are specified. As a result, the convention specified last may override state set by earlier conventions.
Assert-PSRule -Convention 'ExampleConvention1', 'ExampleConvention2';
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.
For example:
# Synopsis: An example convention.
Export-PSRuleConvention 'ExampleConvention' {
# Add code here
}
Initialize Begin Process End blocks#
Conventions define four executable blocks Initialize
, Begin
, Process
, End
similar to a PowerShell function.
Each block is injected in a different part of the pipeline as follows:
Initialize
occurs once at the beginning of the pipeline. UseInitialize
to perform any initialization required by the convention.Begin
occurs once per object before the any rules are executed. UseBegin
blocks to perform expansion, set data, or alter the object before rules are processed.Process
occurs once per object after all rules are executed. UseProcess
blocks to perform per object tasks such as generate badges.End
occurs only once after all objects have been processed. UseEnd
blocks to upload results to an external service.
Convention block limitations:
Initialize
can not use automatic variables except$PSRule
. Most methods and properties of$PSRule
are not available inInitialize
.Begin
andProcess
can not use rule specific variables such as$Rule
. These blocks are executed outside of the context of a single rule.End
can not use automatic variables except$PSRule
. Most methods and properties of$PSRule
are not available inEnd
.
By default, the Process
block is used.
For example:
# Synopsis: The default { } executes the process block
Export-PSRuleConvention 'ExampleConvention' {
# Process block
}
# Synopsis: With optional -Process parameter name
Export-PSRuleConvention 'ExampleConvention' -Process {
# Process block
}
To use Initialize
, Begin
, or End
explicitly add these blocks.
For example:
Export-PSRuleConvention 'ExampleConvention' -Process {
# Process block
} -Begin {
# Begin block
} -End {
# End block
} -Initialize {
# Initialize block
}
Including with options#
Conventions can be included by name within options in addition to using the -Convention
parameter.
To specify a convention within YAML options use the following:
convention:
include:
- 'ExampleConvention1'
- 'ExampleConvention2'
Using within modules#
Conventions can be shipped within a module using the same packaging and distribution process as rules.
Additionally, conventions shipped within a module can be automatically included.
By default, PSRule does not include conventions shipped within a module.
To use a convention included in a module use the -Convention
parameter or options configuration.
A module can automatically include a convention by specifying the convention by name in module configuration. For example:
---
apiVersion: github.com/microsoft/PSRule/v1
kind: ModuleConfig
metadata:
name: ExampleModule
spec:
convention:
include:
- 'ExampleConvention1'
- 'ExampleConvention2'
Execution order#
Conventions are executed in the order they are specified.
This is true for Initialize
, Begin
, Process
, and End
blocks.
i.e. In the following example ExampleConvention1
is execute before ExampleConvention2
.
Assert-PSRule -Convention 'ExampleConvention1', 'ExampleConvention2';
When conventions are specified from multiple locations PSRule orders conventions as follows:
- Using
-Convention
parameter. - PSRule options.
- Module configuration.