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