en-GB/about_PSRule_Variables.help.txt
|
TOPIC
about_psrule_variables SHORT DESCRIPTION Describes the automatic variables that can be used within PSRule rule definitions. LONG DESCRIPTION PSRule lets you define rules using PowerShell blocks. A rule is defined within script files by using the `rule` keyword. Within a rule definition, PSRule exposes a number of automatic variables that can be read to assist with rule execution. Overwriting these variables or variable properties is not supported. These variables are only available while `Invoke-PSRule` is executing. The following variables are available for use: - $Assert - $Configuration - $LocalizedData - $PSRule - $Rule - $TargetObject ASSERT An assertion helper with methods to evaluate objects. The `$Assert` object provides a set of built-in methods and provides a consistent variable for extension. Each `$Assert` method returns an `AssertResult` object that contains the result of the condition. The following built-in assertion methods are provided: - `Contains` - The field value must contain at least one of the strings. - `EndsWith` - The field value must match at least one suffix. - `FileHeader` - The file must contain a comment header. - `FilePath` - The file path must exist. - `Greater` - The field value must be greater. - `GreaterOrEqual` - The field value must be greater or equal to. - `HasDefaultValue` - The object should not have the field or the field value is set to the default value. - `HasField` - The object must have any of the specified fields. - `HasFields` - The object must have all of the specified fields. - `HasFieldValue` - The object must have the specified field and that field is not empty. - `HasJsonSchema` - The object must reference a JSON schema with the `$schema` field. - `In` - The field value must be included in the set. - `IsArray` - The field value must be an array. - `IsBoolean` - The field value must be a boolean. - `IsInteger` - The field value must be an integer. - `IsLower` - The field value must include only lowercase characters. - `IsNumeric` - The field value must be a numeric type. - `IsString` - The field value must be a string. - `IsUpper` - The field value must include only uppercase characters. - `JsonSchema` - The object must validate successfully against a JSON schema. - `Less` - The field value must be less. - `LessOrEqual` - The field value must be less or equal to. - `Match` - The field value matches a regular expression pattern. - `NotIn` - The field value must not be included in the set. - `NotMatch` - The field value does not match a regular expression pattern. - `NullOrEmpty` - The object must not have the specified field or it must be empty. - `TypeOf` - The field value must be of the specified type. - `StartsWith` - The field value must match at least one prefix. - `Version` - The field value must be a semantic version string. The `$Assert` variable can only be used within a rule definition block. For detailed information on the assertion helper see about_PSRule_Assert . Syntax: $Assert Examples: # Synopsis: Determine if $TargetObject is valid against the provided schema Rule 'UseJsonSchema' { $Assert.JsonSchema($TargetObject, 'schemas/PSRule-options.schema.json') } CONFIGURATION A dynamic object with properties names that map to configuration values set in the baseline. When accessing configuration: - Configuration keys are case sensitive. - Configuration values are read only. - Configuration values can be accessed through helper methods. The following helper methods are available: - `GetStringValues(string configurationKey)` - Returns an array of strings, based on `configurationKey`. Syntax: $Configuration.<configurationKey> $Configuration.GetStringValues(<configurationKey>) Examples: # Synopsis: This rule uses a threshold stored as $Configuration.appServiceMinInstanceCount Rule 'appServicePlan.MinInstanceCount' -If { $TargetObject.ResourceType -eq 'Microsoft.Web/serverfarms' } { $TargetObject.Sku.capacity -ge $Configuration.appServiceMinInstanceCount } -Configure @{ appServiceMinInstanceCount = 2 } LOCALIZEDDATA A dynamic object with properties names that map to localized data messages in a `.psd1` file. When using localized data, PSRule loads localized strings as a hashtable from `PSRule-rules.psd1`. The following logic is used to locate `PSRule-rules.psd1`: - If the rules are loose (not part of a module), PSRule will search for `PSRule-rules.psd1` in the `.<culture>` subdirectory relative to where the rule script .ps1 file is located. - When the rules are shipped as part of a module, PSRule will search for `PSRule-rules.psd1` in the `.<culture>` subdirectory relative to where the module manifest .psd1 file is located. When accessing localized data: - Message names are case sensitive. - Message values are read only. Syntax: $LocalizedData.<messageName> Examples: # Data for rules stored in PSRule-rules.psd1 @{ WithLocalizedDataMessage = 'LocalizedMessage for en-ZZ. Format={0}.' } # Synopsis: Use -f to generate a formatted localized warning Rule 'WithLocalizedData' { Write-Warning -Message ($LocalizedData.WithLocalizedDataMessage -f $TargetObject.Type) } This rule returns a warning message similar to: LocalizedMessage for en-ZZ. Format=TestType. PSRULE An object representing the current context during execution. The following properties are available for read access: - `Badges` - A helper to generate badges within PSRule. This property can only be called within the `-End` block of a convention. - `Field` - A hashtable of custom bound fields. See option `Binding.Field` for more information. - `TargetObject` - The object currently being processed on the pipeline. - `TargetName` - The name of the object currently being processed on the pipeline. This property will automatically default to `TargetName` or `Name` properties of the object if they exist. - `TargetType` - The type of the object currently being processed on the pipeline. This property will automatically bind to `PSObject.TypeNames[0]` by default. - `Source` - A collection of sources for the object currently being processed on the pipeline. - `Output` - The output of all rules. This property can only be called within the `-End` block of a convention. The following properties are available for read/ write access: - `Data` - A hashtable of custom data. This property can be populated during rule or begin/ process convention execution. Custom data is not used by PSRule directly, and is intended to be used by downstream processes that need to interpret PSRule results. To bind fields that already exist on the target object use custom binding and `Binding.Field`. Use custom data to store data that must be calculated during rule execution. The following helper methods are available: - `GetContent(PSObject sourceObject)` - Returns the content of a file as one or more objects. The parameter `sourceObject` should be a `InputFileInfo`,`FileInfo`, or `Uri` object. - `GetContentField(PSObject sourceObject, string field)` - Returns the content of a file as one or more objects. The parameter `sourceObject` should be a `InputFileInfo`,`FileInfo`, or `Uri` object. The parameter `field` is an field within each object to return. If the field does not exist on the object, an object is not returned. - `GetContentFirstOrDefault(PSObject sourceObject)` - Returns the content of a file as on object. The parameter `sourceObject` should be a `InputFileInfo`,`FileInfo`, or `Uri` object. If more than one object is contained in the file, only the first object is returned. When the source file contains no objects null is returned. - `Import(PSObject[] sourceObject)` - Imports one or more source objects into the pipeline. This method can only be called within the `-Begin` block of a convention. Use this method to expand an object into child objects that will be processed independently. Objects imported using this method will be excluded from the `Input.ObjectPath` option if set. - `AddService(string id, object service)` - Add a service to the current context. The service can be retrieved using `$PSRule.GetService(id)`. The service object will be available to all rules and cleaned up after all rules are executed. Services should implement the `IDisposable` interface to perform additional cleanup. This method can only be called within the `-Initialize` block of a convention. - `GetService(string id)` - Retrieves a service previously added by a convention. The file format is detected based on the same file formats as the option `Input.Format`. i.e. Yaml, Json, Markdown, and PowerShell Data. Syntax: $PSRule Examples: # Synopsis: This rule determines if the target object matches the naming convention Rule 'NamingConvention' { $PSRule.TargetName.ToLower() -ceq $PSRule.TargetName } # Synopsis: Use allowed environment tags Rule 'CustomData' { Recommend 'Environment must be set to an allowed value' Within 'Tags.environment' 'production', 'test', 'development' if ($TargetObject.Tags.environment -in 'prod') { $PSRule.Data['targetEnvironment'] = 'production' } elseif ($TargetObject.Tags.environment -in 'dev', 'develop') { $PSRule.Data['targetEnvironment'] = 'development' } elseif ($TargetObject.Tags.environment -in 'tst', 'testing') { $PSRule.Data['targetEnvironment'] = 'test' } } RULE An object representing the current rule during execution. The following properties are available for read access: - `RuleName` - The name of the rule. - `RuleId` - A unique identifier for the rule. Syntax: $Rule Examples: # Synopsis: This rule determines if the target object matches the naming convention Rule 'resource.NamingConvention' { $PSRule.TargetName.ToLower() -ceq $PSRule.TargetName } TARGETOBJECT The value of the pipeline object currently being processed. `$TargetObject` is set by using the `-InputObject` parameter of `Invoke-PSRule`. When more than one input object is set, each object will be processed sequentially. Syntax: $TargetObject Examples: # Synopsis: Check that sku capacity is set to at least 2 Rule 'HasMinInstances' { $TargetObject.Sku.capacity -ge 2 } NOTE An online version of this document is available at https://github.com/Microsoft/PSRule/blob/main/docs/concepts/PSRule/en-US/about_PSRule_Variables.md. SEE ALSO - Invoke-PSRule KEYWORDS - Assert - Configuration - LocalizedData - PSRule - Rule - TargetObject |