en-GB/about_PSRule_Conventions.help.txt
|
TOPIC
about_psrule_conventions SHORT DESCRIPTION Describes PSRule Conventions including how to use and author them. LONG 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. Use `Initialize` to perform any initialization required by the convention. - `Begin` occurs once per object before the any rules are executed. Use `Begin` blocks to perform expansion, set data, or alter the object before rules are processed. - `Process` occurs once per object after all rules are executed. Use `Process` blocks to perform per object tasks such as generate badges. - `End` occurs only once after all objects have been processed. Use `End` 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 in `Initialize`. - `Begin` and `Process` 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 in `End`. By default, the `Process` block 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: # Example ps-docs.yaml 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: # Example Config.Rule.yaml --- 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: 1. Using `-Convention` parameter. 2. PSRule options. 3. Module configuration. NOTE An online version of this document is available at https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Conventions/. SEE ALSO - Invoke-PSRule KEYWORDS - Conventions - PSRule |