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
    -
    $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:
    - `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.
    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.
    Syntax:
 
    $Configuration.<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.
 
    RULE
    An object representing the current object model of the rule during execution.
    The following section properties are available for public read access:
    - `RuleName` - The name of the rule.
    - `RuleId` - A unique identifier for the rule.
    - `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.
    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
- Rule
- TargetObject