en-US/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.
    - `HasDefaultValue` - The object should not have the field or the field
    value is set to the default value.
    - `HasField` - Asserts that the object must have the specified field.
    - `HasFieldValue` - Asserts that the object must have the specified field
    and that field is not empty.
    - `JsonSchema` - Asserts that the object must validate successfully against
    a JSON schema.
    - `NullOrEmpty` - Asserts that the object must not have the specified field
    or it must be empty.
    - `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:
    - `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.
    The following properties are available for read/ write access:
    - `Data` - A hashtable of custom data. This property can be populated during
    rule 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.
    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.
    - `TargetObject` - (deprecated) The object currently being processed on the pipeline.
    - `TargetName` - (deprecated) 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` - (deprecated) The type of the object currently being
    processed on the pipeline. This property will automatically bind to
    `PSObject.TypeNames[0]` by default.
    Note:
    Use `TargetName`, `TargetType` and `TargetObject` on `$PSRule` instead.
    Syntax:
 
    $Rule
 
    Examples:
 
    # Synopsis: This rule determines if the target object matches the naming convention
    Rule 'resource.NamingConvention' {
        $Rule.TargetName.ToLower() -ceq $Rule.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/master/docs/concepts/PSRule/en-US/about_PSRule_Variables.md.
 
SEE ALSO
    -
    Invoke-PSRule
 
KEYWORDS
    - Assert
- Configuration
- LocalizedData
- PSRule
- Rule
- TargetObject