en-AU/about_PSRule_Assert.help.txt

TOPIC
    about_psrule_assert
 
SHORT DESCRIPTION
    Describes the assertion helper that can be used within PSRule rule
    definitions.
 
LONG DESCRIPTION
    PSRule includes an assertion helper exposed as a built-in variable
    `$Assert`. The `$Assert` object provides a consistent set of methods to
    evaluate objects.
    Each `$Assert` method returns an `AssertResult` object that contains the
    result of the assertion.
    The following built-in assertion methods are provided:
    -
    APIVersion
    - The field value must be a date version string. -
    Contains
    - The field value must contain at least one of the strings. -
    Count
    - The field value must contain the specified number of items. -
    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. -
    IsDateTime
    - The field value must be a DateTime. -
    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. -
    Like
    - The value must match any of the specified wildcard values. -
    Match
    - The field value matches a regular expression pattern. -
    NotContains
    - The value must not contain any of the specified strings. -
    NotCount
    - The field value must not contain the specified number of items. -
    NotEndsWith
    - The value must not end with any of the specified strings. -
    NotHasField
    - The object must not have any of the specified fields. -
    NotIn
    - The field value must not be included in the set. -
    NotLike
    - The value must not match any of the specified wildcard values. -
    NotMatch
    - The field value does not match a regular expression pattern. -
    NotNull
    - The field value must not be null. -
    NotStartsWith
    - The value must not start with any of the specified strings. -
    NotWithinPath
    - The field must not be within the specified path. -
    Null
    - The field value must not exist or be null. -
    NullOrEmpty
    - The object must not have the specified field or it must be empty. -
    TypeOf
    - The field value must be of the specified type. -
    SetOf
    - The field value must match a set of specified values. -
    StartsWith
    - The field value must match at least one prefix. -
    Subset
    - The field value must include a set of specified values. -
    Version
    - The field value must be a semantic version string. -
    WithinPath
    - The field value must be within the specified path.
    The `$Assert` variable can only be used within a rule definition block or
    script pre-conditions.
 
    USING ASSERTION METHODS
    An assertion method can be used like other methods in PowerShell. i.e. `$Assert.methodName(parameters)`.
    Assertion methods use the following standard pattern:
    - The first parameter is
    always
    the input object of type `PSObject`, additional parameters can be included
    based on the functionality required by the method. - In many cases the
    input object will be `$TargetObject`, however assertion methods must not
    assume that `$TargetObject` will be used. - Assertion methods must accept
    a `$Null` input object. - Assertion methods return the `AssertResult` object
    that is interpreted by the rule pipeline.
    Some assertion methods may overlap or provide similar functionality to
    built-in keywords. Where you have the choice, use built-in keywords. Use
    assertion methods for advanced cases or increased flexibility.
    In the following example, `Assert.HasFieldValue` asserts that
    `$TargetObject` should have a field named `Type` with a non-empty value.
 
    Rule 'Assert.HasTypeField' {
        $Assert.HasFieldValue($TargetObject, 'Type')
    }
 
    To find perform multiple assertions use.
 
    Rule 'Assert.HasRequiredFields' {
        $Assert.HasFieldValue($TargetObject, 'Name')
        $Assert.HasFieldValue($TargetObject, 'Type')
        $Assert.HasFieldValue($TargetObject, 'Value')
    }
 
    FIELD NAMES
    Many of the built-in assertion methods accept an object path or field name.
    An object path is an expression that traverses object properties, keys or
    indexes of the
    input object
    . The syntax for an object path is inspired by JSONPath which is current an
    IETF Internet-Draft.
    The object path expression can contain:
    - Property names for PSObjects or .NET objects.
    - Keys for hash table or dictionaries.
    - Indexes for arrays or collections.
    - Queries that filter items from array or collection properties.
    For example:
    - `.`, or `$` refers to
    input object
    itself. - `Name`, `.Name`, or `$.Name` refers to the
    name
    member of the
    input object
    . - `Properties.enabled` refers to the
    enabled
    member under the Properties member. Alternatively this can also be written
    as `Properties['enabled']`. - `Tags.env` refers to the env member under a
    hash table property of the
    input object
    . - `Tags+env` refers to the env member using a case-sensitive match.
    - `Properties.securityRules[0].name` references to the name member of the
    first security rule.
    - `Properties.securityRules[-1].name` references to the name member of the
    last security rule.
    - `Properties.securityRules[?@direction == 'Inbound'].name` returns the name
    of any inbound rules. This will return an array of security rule names.
    Notable differences between object paths and JSONPath are:
    - Member names (properties and keys) are case-insensitive by default. To
    perform a case-sensitive match of a member name use a plus selector `+` in
    front of the member name. Some assertions such as `HasField` provide an
    option to match case when matching member names. When this is used, the
    plus selector perform an case-insensitive match. - Quoted member names with
    single or double quotes are supported with dot selector. i.e.
    `Properties.'spaced name'` is valid. - Member names with a dash `-` are
    supported without being quoted. However member names can not start or end
    with a dash. i.e. `Properties.dashed-name` and `Properties.'-dashed-name'`
    are valid.
 
    APIVERSION
    The `APIVersion` assertion method checks the field value is a valid date
    version. A constraint can optionally be provided to require the date version
    to be within a range.
    A date version uses the format `yyyy-MM-dd` (`2015-10-01`). Additionally an
    optional string prerelease identifier can be used `yyyy-MM-dd-prerelease` (`2015-10-01-preview.1`).
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive
    compare. - `constraint` (optional) - A version constraint, see below for
    details of version constrain format.
    - `includePrerelease` (optional) - Determines if prerelease versions are included.
     Unless specified this defaults to `$False`.
    The following are supported constraints:
    - `version` - Must match version exactly. This also accepts the prefix `=`.
     - e.g. `2015-10-01`, `=2015-10-01` - `>version` - Must be greater than
    version. - e.g. `>2015-10-01` - `>=version` - Must be greater than or
    equal to version. - e.g. `>=2015-10-01` - `<version` - Must be less than
    version. - e.g. `<2022-03-01` - `<=version` - Must be less than or equal
    to version. - e.g. `<=2022-03-01`
    An empty, null or `*` constraint matches all valid date versions.
    Multiple constraints can be joined together:
    - Use a
    space
    to separate multiple constraints, each must be true (
    logical AND
    ). - Separates constraint sets with the double pipe `||`. Only one
    constraint set must be true (
    logical OR
    ).
    By example:
    - `2014-01-01 || >=2015-10-01 <2022-03-01` results in: - Pass:
    `2014-01-01`, `2015-10-01`, `2019-06-30`, `2022-02-01`. - Fail:
    `2015-01-01`, `2022-09-01`.
    Handling for prerelease versions:
    - Constraints and versions containing prerelease identifiers are supported.
     i.e. `>=2015-10-01-preview` or `2015-10-01-preview`. - A version containing
    a prerelease identifer follows similar ordering to semantic versioning.
    i.e. `2015-10-01-preview` < `2015-10-01-preview.1` < `2015-10-01` <
    `2022-03-01-preview` < `2022-03-01`. - A constraint without a prerelease
    identifer will only match a stable version by default. Set
    `includePrerelease` to `$True` to include prerelease versions.
    Alternatively use the `@pre` or `@prerelease` flag in a constraint.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is not a version string.
    -
    The version '{0}' does not match the constraint '{1}'.
    Examples:
 
    Rule 'ValidAPIVersion' {
        $Assert.APIVersion($TargetObject, 'apiVersion')
    }
     
    Rule 'MinimumAPIVersion' {
        $Assert.APIVersion($TargetObject, 'apiVersion', '>=2015-10-01')
    }
     
    Rule 'MinimumAPIVersionWithPrerelease' {
        $Assert.APIVersion($TargetObject, 'apiVersion', '>=2015-10-01-0', $True)
    }
     
    Rule 'MinimumAPIVersionWithFlag' {
        $Assert.APIVersion($TargetObject, 'apiVersion', '@pre >=2015-10-01-0')
    }
 
    CONTAINS
    The `Contains` assertion method checks the operand contains the specified
    string. If the operand is an array of strings, only one string must contain
    the specified string. Optionally a case-sensitive compare can be used,
    however case is ignored by default.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `text` - A string or an array of
    strings to compare the field value with. Only one string must match. When an
    empty array of strings is specified or text is an empty string, `Contains`
    always passes. - `caseSensitive` (optional) - Use a case sensitive compare
    of the field value. Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'text' is null.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is not a string.
    -
    The field '{0}' does not contain '{1}'.
    Examples:
 
    Rule 'Contains' {
        $Assert.Contains($TargetObject, 'ResourceGroupName', 'prod')
        $Assert.Contains($TargetObject, 'Name', @('prod', 'test'), $True)
    }
 
    COUNT
    The `Count` assertion method checks the field value contains the specified
    number of items. The field value must be an array or collection.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `count` - The number of items that the field value must contain.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field '{0}' is not enumerable.
    -
    The field '{0}' has '{1}' items instead of '{2}'.
    Examples:
 
    Rule 'Count' {
        $Assert.Count($TargetObject, 'items', 2)
    }
 
    ENDSWITH
    The `EndsWith` assertion method checks the operand ends with the specified
    suffix. If the operand is an array of strings, only one string must end with
    the specified suffix. Optionally a case-sensitive compare can be used,
    however case is ignored by default.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `suffix` - A suffix or an array of
    suffixes to compare the field value with. Only one suffix must match. When
    an empty array of suffixes is specified or suffix is an empty string,
    `EndsWith` always passes. - `caseSensitive` (optional) - Use a case
    sensitive compare of the field value. Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'suffix' is null.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is not a string.
    -
    The field '{0}' does not end with '{1}'.
    Examples:
 
    Rule 'EndsWith' {
        $Assert.EndsWith($TargetObject, 'ResourceGroupName', 'eus')
        $Assert.EndsWith($TargetObject, 'Name', @('db', 'web'), $True)
    }
 
    FILEHEADER
    The `FileHeader` assertion method checks a file for a comment header. When
    comparing the file header, the format of line comments are automatically
    detected by file extension. Single line comments are supported. Multi-line
    comments are not supported.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field containing a valid file path.
    - `header` - One or more lines of a header to compare with file contents.
    - `prefix` (optional) - An optional comment prefix for each line.
    By default a comment prefix will automatically detected based on file
    extension. When set, detection by file extension is skipped.
    Prefix detection for line comments is supported with the following file extensions:
    - `.bicep`, `.bicepparam`, `.cs`, `.csx`, `.ts`, `.tsp`, `.tsx`, `.js`,
    `.jsx`, `.fs`, `.go`, `.groovy`, `.php`, `.cpp`, `.h`, `.java`, `.json`,
    `.jsonc`, `.scala`, `Jenkinsfile` - Use a prefix of (`// `). -
    `.editorconfig`, `.ipynb`, `.ps1`, `.psd1`, `.psm1`, `.yaml`, `.yml`, `.r`,
    `.py`, `.sh`, `.tf`, `.tfvars`, `.toml`, `.gitignore`, `.pl`, `.rb`,
    `Dockerfile` - Use a prefix of (`# `). - `.sql`, `.lau` - Use a prefix of
    (`-- `).
    - `.bat`, `.cmd` - Use a prefix of (`:: `).
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is not a string.
    -
    The file '{0}' does not exist.
    -
    The header was not set.
    Examples:
 
    Rule 'FileHeader' {
        $Assert.FileHeader($TargetObject, 'FullName', @(
            'Copyright (c) Microsoft Corporation.'
            'Licensed under the MIT License.'
        ));
    }
 
    FILEPATH
    The `FilePath` assertion method checks the file exists. Checks use file
    system case-sensitivity rules.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field containing a file path.
    - `suffix` (optional) - Additional file path suffixes to append.
    When specified each suffix is combined with the file path. Only one full
    file path must be a valid file for the assertion method to pass.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is not a string.
    -
    The file '{0}' does not exist.
    Examples:
 
    Rule 'FilePath' {
        $Assert.FilePath($TargetObject, 'FullName', @('CHANGELOG.md'));
        $Assert.FilePath($TargetObject, 'FullName', @('LICENSE', 'LICENSE.txt'));
        $Assert.FilePath($TargetObject, 'FullName', @('CODE_OF_CONDUCT.md'));
        $Assert.FilePath($TargetObject, 'FullName', @('CONTRIBUTING.md'));
        $Assert.FilePath($TargetObject, 'FullName', @('SECURITY.md'));
        $Assert.FilePath($TargetObject, 'FullName', @('README.md'));
        $Assert.FilePath($TargetObject, 'FullName', @('.github/CODEOWNERS'));
        $Assert.FilePath($TargetObject, 'FullName', @('.github/PULL_REQUEST_TEMPLATE.md'));
    }
 
    GREATER
    The `Greater` assertion method checks the field value is greater than the
    specified value. The field value can either be an integer, float, array, or
    string. When the field value is:
    - An integer or float, a numerical comparison is used.
    - An array, the number of elements is compared.
    - A string, the length of the string is compared.
    - A DateTime, the number of days from the current time is compared.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `value` - A integer to compare the field value against.
    - `convert` (optional) - Convert numerical strings and use a numerical
    comparison instead of using string length.
    By default the string length is compared.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The value '{0}' was not > '{1}'.
    -
    The field value '{0}' can not be compared with '{1}'.
    Examples:
 
    Rule 'Greater' {
        $Assert.Greater($TargetObject, 'value', 3)
    }
 
    GREATEROREQUAL
    The `GreaterOrEqual` assertion method checks the field value is greater or
    equal to the specified value. The field value can either be an integer,
    float, array, or string. When the field value is:
    - An integer or float, a numerical comparison is used.
    - An array, the number of elements is compared.
    - A string, the length of the string is compared.
    - A DateTime, the number of days from the current time is compared.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `value` - A integer to compare the field value against.
    - `convert` (optional) - Convert numerical strings and use a numerical
    comparison instead of using string length.
    By default the string length is compared.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The value '{0}' was not >= '{1}'.
    -
    The field value '{0}' can not be compared with '{1}'.
    Examples:
 
    Rule 'GreaterOrEqual' {
        $Assert.GreaterOrEqual($TargetObject, 'value', 3)
    }
 
    HASDEFAULTVALUE
    The `HasDefaultValue` assertion method check that the field does not exist
    or the field value is set to the default value.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `defaultValue` - The expected value if
    the field exists.
    This assertion will pass if:
    - The field does not exist.
    - The field value is set to `defaultValue`.
    This assertion will fail if:
    - The field value is set to a value different from `defaultValue`.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' is set to '{1}'.
    Examples:
 
    Rule 'HasDefaultValue' {
        $Assert.HasDefaultValue($TargetObject, 'Properties.osProfile.linuxConfiguration.provisionVMAgent', $True)
    }
 
    HASFIELD
    The `HasField` assertion method checks the object has any of the specified fields.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of one or more fields to check.
    By default, a case insensitive compare is used. If more than one field is
    specified, only one must exist. - `caseSensitive` (optional) - Use a case
    sensitive compare of the field name.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    Does not exist.
    Examples:
 
    Rule 'HasField' {
        $Assert.HasField($TargetObject, 'Name')
        $Assert.HasField($TargetObject, 'tag.Environment', $True)
        $Assert.HasField($TargetObject, @('tag.Environment', 'tag.Env'), $True)
    }
 
    HASFIELDS
    The `HasFields` assertion method checks the object has all of the specified fields.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified fields.
    - `field` - The name of one or more fields to check.
    By default, a case insensitive compare is used. If more than one field is
    specified, all fields must exist. - `caseSensitive` (optional) - Use a case
    sensitive compare of the field name.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    Examples:
 
    Rule 'HasFields' {
        $Assert.HasFields($TargetObject, 'Name')
        $Assert.HasFields($TargetObject, 'tag.Environment', $True)
        $Assert.HasFields($TargetObject, @('tag.Environment', 'tag.Env'), $True)
    }
 
    HASFIELDVALUE
    The `HasFieldValue` assertion method checks the field value of the object is
    not empty.
    A field value is empty if any of the following are true:
    - The field does not exist.
    - The field value is `$Null`.
    - The field value is an empty array or collection.
    - The field value is an empty string `''`.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `expectedValue` (optional) - Check that the field value is set to a
    specific value.
    To check `$Null` use `NullOrEmpty` instead. If `expectedValue` is `$Null`
    the field value will not be compared.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    Does not exist.
    -
    Is null or empty.
    -
    Is set to '{0}'.
    Examples:
 
    Rule 'HasFieldValue' {
        $Assert.HasFieldValue($TargetObject, 'Name')
        $Assert.HasFieldValue($TargetObject, 'tag.Environment', 'production')
    }
 
    HASJSONSCHEMA
    The `HasJsonSchema` assertion method determines if the input object has a
    `$schema` property defined. If the `$schema` property is defined, it must
    not be empty and match one of the supplied schemas. If a trailing `#` is
    specified it is ignored from the `$schema` property and `uri` parameter below.
    The following parameters are accepted:
    - `inputObject` - The object being compared.
    - `uri` - Optional.
    When specified, the object being compared must have a `$schema` property set
    to one of the specified schemas. - `ignoreScheme` - Optional. By default,
    `ignoreScheme` is `$False`. When `$True`, the schema will match if `http` or
    `https` is specified.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The field '$schema' does not exist.
    -
    The field value '$schema' is not a string.
    -
    The value of '$schema' is null or empty.
    -
    None of the specified schemas match '{0}'.
    Examples:
 
    Rule 'HasFieldValue' {
        $Assert.HasJsonSchema($TargetObject)
        $Assert.HasJsonSchema($TargetObject, "http://json-schema.org/draft-07/schema`#")
        $Assert.HasJsonSchema($TargetObject, "https://json-schema.org/draft-07/schema", $True)
    }
 
    JSONSCHEMA
    The `JsonSchema` assertion method compares the input object against a
    defined JSON schema.
    The following parameters are accepted:
    - `inputObject` - The object being compared against the JSON schema.
    - `uri` - A URL or file path to a JSON schema file formatted as UTF-8.
    Either a file path or URL can be used to specify the location of the schema file.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'uri' is null or empty.
    -
    The JSON schema '{0}' could not be found.
    -
    Failed schema validation on {0}. {1}
    Examples:
 
    Rule 'JsonSchema' {
        $Assert.JsonSchema($TargetObject, 'tests/PSRule.Tests/FromFile.Json.schema.json')
    }
 
    IN
    The `In` assertion method checks the field value is included in a set of
    values. The field value can either be an integer, float, array, or string.
    When the field value is an array, only one item must be included in the set.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive
    compare. - `values` - An array of values that the field value is compared
    against. When an empty array is specified, `In` will always fail. -
    `caseSensitive` (optional) - Use a case sensitive compare of the field
    value. Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'values' is null.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' was not included in the set.
    Examples:
 
    Rule 'In' {
        $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard'))
        $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard'), $True)
    }
 
    ISARRAY
    The `IsArray` assertion method checks the field value is an array type.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is null.
    -
    The field value '{1}' of type {0} is not [array].
    Examples:
 
    Rule 'IsArray' {
        # Require Value1 to be an array
        $Assert.IsArray($TargetObject, 'Value1')
    }
 
    ISBOOLEAN
    The `IsBoolean` assertion method checks the field value is a boolean type.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `convert` (optional) - Try to convert
    strings. By default strings are not converted.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is null.
    -
    The value '{0}' is not a boolean.
    Examples:
 
    Rule 'IsBoolean' {
        # Require Value1 to be a boolean
        $Assert.IsBoolean($TargetObject, 'Value1')
     
        # Require Value1 to be a boolean or a boolean string
        $Assert.IsBoolean($TargetObject, 'Value1', $True)
    }
 
    ISDATETIME
    The `IsDateTime` assertion method checks the field value is a DateTime type.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `convert` (optional) - Try to convert
    strings. By default strings are not converted.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is null.
    -
    The value '{0}' is not a date.
    Examples:
 
    Rule 'IsDateTime' {
        # Require Value1 to be a DateTime
        $Assert.IsDateTime($TargetObject, 'Value1')
     
        # Require Value1 to be a DateTime or a DateTime string
        $Assert.IsDateTime($TargetObject, 'Value1', $True)
    }
 
    ISINTEGER
    The `IsInteger` assertion method checks the field value is a integer type.
    The following types are considered integer types `int`, `long`, `byte`.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `convert` (optional) - Try to convert
    strings. By default strings are not converted.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is null.
    -
    The value '{0}' is not an integer.
    Examples:
 
    Rule 'IsInteger' {
        # Require Value1 to be an integer
        $Assert.IsInteger($TargetObject, 'Value1')
     
        # Require Value1 to be an integer or a integer string
        $Assert.IsInteger($TargetObject, 'Value1', $True)
    }
 
    ISLOWER
    The `IsLower` assertion method checks the field value uses only lowercase
    characters. Non-letter characters are ignored by default and will pass.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `requireLetters` (optional) - Require each character to be lowercase
    letters only.
    Non-letter characters are ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is not a string.
    -
    The value '{0}' does not contain only lowercase characters.
    -
    The value '{0}' does not contain only letters.
    Examples:
 
    Rule 'IsLower' {
        # Require Name to be lowercase
        $Assert.IsLower($TargetObject, 'Name')
     
        # Require Name to only contain lowercase letters
        $Assert.IsLower($TargetObject, 'Name', $True)
    }
 
    ISNUMERIC
    The `IsNumeric` assertion method checks the field value is a numeric type.
    The following types are considered numeric types `int`, `long`, `float`,
    `byte`, `double`.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `convert` (optional) - Try to convert
    numerical strings. By default strings are not converted.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is null.
    -
    The value '{0}' is not numeric.
    Examples:
 
    Rule 'IsNumeric' {
        # Require Value1 to be numeric
        $Assert.IsNumeric($TargetObject, 'Value1')
     
        # Require Value1 to be numeric or a numerical string
        $Assert.IsNumeric($TargetObject, 'Value1', $True)
    }
 
    ISSTRING
    The `IsString` assertion method checks the field value is a string type.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is null.
    -
    The value '{0}' is not a string.
    Examples:
 
    Rule 'IsString' {
        # Require Value1 to be a string
        $Assert.IsString($TargetObject, 'Value1')
    }
 
    ISUPPER
    The `IsUpper` assertion method checks the field value uses only uppercase
    characters. Non-letter characters are ignored by default and will pass.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `requireLetters` (optional) - Require each character to be uppercase
    letters only.
    Non-letter characters are ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is not a string.
    -
    The value '{0}' does not contain only uppercase characters.
    -
    The value '{0}' does not contain only letters.
    Examples:
 
    Rule 'IsUpper' {
        # Require Name to be uppercase
        $Assert.IsUpper($TargetObject, 'Name')
     
        # Require Name to only contain uppercase letters
        $Assert.IsUpper($TargetObject, 'Name', $True)
    }
 
    LESS
    The `Less` assertion method checks the field value is less than the
    specified value. The field value can either be an integer, float, array, or
    string. When the field value is:
    - An integer or float, a numerical comparison is used.
    - An array, the number of elements is compared.
    - A string, the length of the string is compared.
    - A DateTime, the number of days from the current time is compared.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `value` - A integer to compare the field value against.
    - `convert` (optional) - Convert numerical strings and use a numerical
    comparison instead of using string length.
    By default the string length is compared.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The value '{0}' was not < '{1}'.
    -
    The field value '{0}' can not be compared with '{1}'.
    Examples:
 
    Rule 'Less' {
        $Assert.Less($TargetObject, 'value', 3)
    }
 
    LESSOREQUAL
    The `LessOrEqual` assertion method checks the field value is less or equal
    to the specified value. The field value can either be an integer, float,
    array, or string. When the field value is:
    - An integer or float, a numerical comparison is used.
    - An array, the number of elements is compared.
    - A string, the length of the string is compared.
    - A DateTime, the number of days from the current time is compared.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `value` - A integer to compare the field value against.
    - `convert` (optional) - Convert numerical strings and use a numerical
    comparison instead of using string length.
    By default the string length is compared.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The value '{0}' was not <= '{1}'.
    -
    The field value '{0}' can not be compared with '{1}'.
    Examples:
 
    Rule 'LessOrEqual' {
        $Assert.LessOrEqual($TargetObject, 'value', 3)
    }
 
    LIKE
    The `Like` assertion method checks the field value matches a specified
    pattern. Optionally a case-sensitive compare can be used, however case is
    ignored by default.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `pattern` - A pattern or an array of
    patterns to compare the field value with. Only one pattern must match. When
    an empty array of patterns is specified, `Like` always passes. -
    `caseSensitive` (optional) - Use a case sensitive compare of the field
    value. Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'prefix' is null.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is not a string.
    -
    The value '{0}' is not like '{1}'.
    Examples:
 
    Rule 'Like' {
        $Assert.Like($TargetObject, 'ResourceGroupName', 'rg-*')
        $Assert.Like($TargetObject, 'Name', @('st*', 'diag*'), $True)
    }
 
    MATCH
    The `Match` assertion method checks the field value matches a regular
    expression pattern.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `pattern` - A regular expression pattern to match.
    - `caseSensitive` (optional) - Use a case sensitive compare of the field value.
    Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is not a string.
    -
    The field value '{0}' does not match the pattern '{1}'.
    Examples:
 
    Rule 'Match' {
        $Assert.Match($TargetObject, 'value', '^[a-z]*$')
        $Assert.Match($TargetObject, 'value', '^[a-z]*$', $True)
    }
 
    NOTCONTAINS
    The `NotContains` assertion method checks the operand contains the specified
    string. This condition fails when any of the specified sub-strings are
    found. If the operand is an array of strings, this condition fails if any of
    the strings contain the specified string. Optionally a case-sensitive
    compare can be used, however case is ignored by default.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `text` - A string or an array of
    strings to compare the field value with. When an empty array of strings is
    specified or text is an empty string, `NotContains` always passes. -
    `caseSensitive` (optional) - Use a case sensitive compare of the field
    value. Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'text' is null.
    -
    The field '{0}' does not exist.
    -
    The value '{0}' contains '{1}'.
    Examples:
 
    Rule 'NotContains' {
        $Assert.NotContains($TargetObject, 'ResourceGroupName', 'prod')
        $Assert.NotContains($TargetObject, 'Name', @('prod', 'test'), $True)
    }
 
    NOTCOUNT
    The `NotCount` assertion method checks the field value does not contain the
    specified number of items. The field value must be an array or collection.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `count` - The number of items that the field value must contain.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field '{0}' is not enumerable.
    -
    The field '{0}' has '{1}' items instead of '{2}'.
    Examples:
 
    Rule 'NotCount' {
        $Assert.NotCount($TargetObject, 'items', 2)
    }
 
    NOTENDSWITH
    The `NotEndsWith` assertion method checks the operand ends with the
    specified suffix. This condition fails when any of the specified sub-strings
    are found at the end of the operand. If the operand is an array of strings,
    this condition fails if any of the strings ends with the specified suffix.
    Optionally a case-sensitive compare can be used, however case is ignored by default.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `suffix` - A suffix or an array of
    suffixes to compare the field value with. When an empty array of suffixes is
    specified or suffix is an empty string, `NotEndsWith` always passes. -
    `caseSensitive` (optional) - Use a case sensitive compare of the field
    value. Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'suffix' is null.
    -
    The field '{0}' does not exist.
    -
    The value '{0}' ends with '{1}'.
    Examples:
 
    Rule 'NotEndsWith' {
        $Assert.NotEndsWith($TargetObject, 'ResourceGroupName', 'eus')
        $Assert.NotEndsWith($TargetObject, 'Name', @('db', 'web'), $True)
    }
 
    NOTHASFIELD
    The `NotHasField` assertion method checks the object does not have any of
    the specified fields.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of one or more fields to check.
    By default, a case insensitive compare is used. If more than one field is
    specified, all must not exist. - `caseSensitive` (optional) - Use a case
    sensitive compare of the field name.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' exists.
    Examples:
 
    Rule 'NotHasField' {
        $Assert.NotHasField($TargetObject, 'Name')
        $Assert.NotHasField($TargetObject, 'tag.Environment', $True)
        $Assert.NotHasField($TargetObject, @('tag.Environment', 'tag.Env'), $True)
    }
 
    NOTIN
    The `NotIn` assertion method checks the field value is not in a set of
    values. The field value can either be an integer, array, float, or string.
    When the field value is an array, none of the items must be included in the
    set. If the field does not exist at all, it is not in the set and passes. To
    check the field exists combine this assertion method with `HasFieldValue`.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `values` - An array values that the field value is compared against.
    When an empty array is specified, `NotIn` will always pass. -
    `caseSensitive` (optional) - Use a case sensitive compare of the field
    value. Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'values' is null.
    -
    The field value '{0}' was in the set.
    Examples:
 
    Rule 'In' {
        $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic'))
        $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic'), $True)
    }
 
    NOTLIKE
    The `NotLike` assertion method checks the field value matches a specified
    pattern. This condition fails when any of the specified patterns match the
    field value. Optionally a case-sensitive compare can be used, however case
    is ignored by default.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `pattern` - A pattern or an array of
    patterns to compare the field value with. When an empty array of pattens is
    specified, `NotLike` always passes. - `caseSensitive` (optional) - Use a
    case sensitive compare of the field value. Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'prefix' is null.
    -
    The field '{0}' does not exist.
    -
    The value '{0}' is like '{1}'
    Examples:
 
    Rule 'NotLike' {
        $Assert.NotLike($TargetObject, 'ResourceGroupName', 'rg-*')
        $Assert.NotLike($TargetObject, 'Name', @('st*', 'diag*'), $True)
    }
 
    NOTMATCH
    The `NotMatch` assertion method checks the field value does not match a
    regular expression pattern. If the field does not exist at all, it does not
    match and passes. To check the field exists combine this assertion method
    with `HasFieldValue`.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive compare.
    - `pattern` - A regular expression pattern to match.
    - `caseSensitive` (optional) - Use a case sensitive compare of the field value.
    Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field value '{0}' is not a string.
    -
    The field value '{0}' matches the pattern '{1}'.
    Examples:
 
    Rule 'NotMatch' {
        $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$')
        $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$', $True)
    }
 
    NOTNULL
    The `NotNull` assertion method checks the field value of the object is not null.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is null.
    Examples:
 
    Rule 'NotNull' {
        $Assert.NotNull($TargetObject, 'Name')
        $Assert.NotNull($TargetObject, 'tag.Environment')
    }
 
    NOTSTARTSWITH
    The `NotStartsWith` assertion method checks the operand starts with the
    specified prefix. This condition fails when any of the specified sub-strings
    are found at the start of the operand. If the operand is an array of
    strings, this condition fails if any of the strings start with the specified
    prefix. Optionally a case-sensitive compare can be used, however case is
    ignored by default.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `prefix` - A prefix or an array of
    prefixes to compare the field value with. When an empty array of prefixes is
    specified or prefix is an empty string, `NotStartsWith` always passes. -
    `caseSensitive` (optional) - Use a case sensitive compare of the field
    value. Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'prefix' is null.
    -
    The field '{0}' does not exist.
    -
    The value '{0}' starts with '{1}'.
    Examples:
 
    Rule 'NotStartsWith' {
        $Assert.NotStartsWith($TargetObject, 'ResourceGroupName', 'rg-')
        $Assert.NotStartsWith($TargetObject, 'Name', @('st', 'diag'), $True)
    }
 
    NOTWITHINPATH
    The `NotWithinPath` assertion method checks the file is not within a
    specified path. Checks use file system case-sensitivity rules by default.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field containing a file path.
    When the field is `InputFileInfo` or `FileInfo`, PSRule will automatically
    resolve the file path. - `path` - An array of one or more directory paths to
    check. Only one path must match. - `caseSensitive` (optional) - Determines
    if case-sensitive path matching is used. This can be set to `$True` or
    `$False`. When not set or `$Null`, the case-sensitivity rules of the working
    path file system will be used.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'path' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The file '{0}' is within the path '{1}'.
    Examples:
 
    Rule 'NotWithinPath' {
        # The file must not be within either policy/ or security/ sub-directories.
        $Assert.NotWithinPath($TargetObject, 'FullName', @('policy/', 'security/'));
    }
 
    NULL
    The `Null` assertion method checks the field value of the object is null.
    A field value is null if any of the following are true:
    - The field does not exist.
    - The field value is `$Null`.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field value '{0}' is not null.
    Examples:
 
    Rule 'Null' {
        $Assert.Null($TargetObject, 'NotField')
        $Assert.Null($TargetObject, 'tag.NullField')
    }
 
    NULLOREMPTY
    The `NullOrEmpty` assertion method checks the field value of the object is
    null or empty.
    A field value is null or empty if any of the following are true:
    - The field does not exist.
    - The field value is `$Null`.
    - The field value is an empty array or collection.
    - The field value is an empty string `''`.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' is not empty.
    Examples:
 
    Rule 'NullOrEmpty' {
        $Assert.NullOrEmpty($TargetObject, 'Name')
        $Assert.NullOrEmpty($TargetObject, 'tag.Environment')
    }
 
    TYPEOF
    The `TypeOf` assertion method checks the field value is a specified type.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `type` - One or more specified types
    to check. The field value only has to match a single type of more than one
    type is specified.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'type' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is null.
    -
    The field value '{2}' of type {1} is not {0}.
    Examples:
 
    Rule 'TypeOf' {
        # Require Value1 to be [int]
        $Assert.TypeOf($TargetObject, 'Value1', [int])
     
        # Require Value1 to be [int] or [long]
        $Assert.TypeOf($TargetObject, 'Value1', @([int], [long]))
    }
 
    SETOF
    The `SetOf` assertion method checks the field value only includes all of the
    specified values. The field value must be an array or collection. Specified
    values can be included in the field value in any order.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive
    compare. - `values` - An array of values that the field value is compared against.
    - `caseSensitive` (optional) - Use a case sensitive compare of the field value.
     Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'values' is null.
    -
    The field '{0}' does not exist.
    -
    The field '{0}' is not enumerable.
    -
    The field '{0}' did not contain '{1}'.
    -
    The field '{0}' has '{1}' items instead of '{2}'.
    Examples:
 
    Rule 'Subset' {
        $Assert.SetOf($TargetObject, 'zones', @('1', '2', '3'))
    }
 
    STARTSWITH
    The `StartsWith` assertion method checks the operand starts with the
    specified prefix. If the operand is an array of strings, only one string
    must start with the specified prefix. Optionally a case-sensitive compare
    can be used, however case is ignored by default.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `prefix` - A prefix or an array of
    prefixes to compare the field value with. Only one prefix must match. When
    an empty array of prefixes is specified or prefix is an empty string,
    `StartsWith` always passes. - `caseSensitive` (optional) - Use a case
    sensitive compare of the field value. Case is ignored by default.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'prefix' is null.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is not a string.
    -
    The field '{0}' does not start with '{1}'.
    Examples:
 
    Rule 'StartsWith' {
        $Assert.StartsWith($TargetObject, 'ResourceGroupName', 'rg-')
        $Assert.StartsWith($TargetObject, 'Name', @('st', 'diag'), $True)
    }
 
    SUBSET
    The `Subset` assertion method checks the field value includes all of the
    specified values. The field value may also contain additional values that
    are not specified in the `values` parameter. The field value must be an
    array or collection. Specified values can be included in the field value in
    any order.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check. This is a case insensitive
    compare. - `values` - An array of values that the field value is compared
    against. When an empty array is specified, `Subset` will always pass. -
    `caseSensitive` (optional) - Use a case sensitive compare of the field
    value. Case is ignored by default. - `unique` (optional) - A boolean value
    that indicates if the items must be unique. When `true` the field value
    must not contain duplicate items.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'values' is null.
    -
    The field '{0}' does not exist.
    -
    The field '{0}' is not enumerable.
    -
    The field '{0}' did not contain '{1}'.
    -
    The field '{0}' included multiple instances of '{1}'.
    Examples:
 
    Rule 'Subset' {
        $Assert.Subset($TargetObject, 'logs', @('cluster-autoscaler', 'kube-apiserver', 'kube-scheduler'), $True, $True)
    }
 
    VERSION
    The `Version` assertion method checks the field value is a valid semantic
    version. A constraint can optionally be provided to require the semantic
    version to be within a range.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field to check.
    This is a case insensitive compare. - `constraint` (optional) - A version
    constraint, see below for details of version constrain format.
    - `includePrerelease` (optional) - Determines if prerelease versions are included.
    Unless specified this defaults to `$False`.
    The following are supported constraints:
    - `version` - Must match version exactly. This also accepts the following
    prefixes; `=`, `v`, `V`. - e.g. `1.2.3`, `=1.2.3` - `>version` - Must be
    greater than version. - e.g. `>1.2.3` - `>=version` - Must be greater than
    or equal to version. - e.g. `>=1.2.3` - `<version` - Must be less than
    version. - e.g. `<1.2.3` - `<=version` - Must be less than or equal to
    version. - e.g. `<=1.2.3` - `^version` - Compatible with version. - e.g.
    `^1.2.3` - `>=1.2.3`, `<2.0.0` - `~version` - Approximately equivalent to
    version - e.g. `~1.2.3` - `>=1.2.3`, `<1.3.0`
    An empty, null or `*` constraint matches all valid semantic versions.
    Multiple constraints can be joined together:
    - Use a
    space
    to separate multiple constraints, each must be true (
    logical AND
    ). - Separates constraint sets with the double pipe `||`. Only one
    constraint set must be true (
    logical OR
    ).
    By example:
    - `1.2.3 || >=3.4.5 <5.0.0` results in: - Pass: `1.2.3`, `3.4.5`, `3.5.0`,
    `4.9.9`. - Fail: `3.0.0`, `5.0.0`.
    Handling for prerelease versions:
    - Constraints and versions containing prerelease identifiers are supported.
    i.e. `>=1.2.3-build.1` or `1.2.3-build.1`. - A version containing a
    prerelease identifer follows semantic versioning rules. i.e. `1.2.3-alpha` <
    `1.2.3-alpha.1` < `1.2.3-alpha.beta` < `1.2.3-beta` < `1.2.3-beta.2` <
    `1.2.3-beta.11` < `1.2.3-rc.1` < `1.2.3`. - A constraint without a
    prerelease identifer will only match a stable version by default. Set
    `includePrerelease` to `$True` to include prerelease versions. - Constraints
    with a prerelease identifer will only match: - Matching prerelease
    versions of the same major.minor.patch version by default. Set
    `includePrerelease` to `$True` to include prerelease versions of all
    matching versions. Alternatively use the `@pre` or `@prerelease` flag in a
    constraint. - Matching stable versions.
    By example:
    - `>=1.2.3` results in: - Pass: `1.2.3`, `9.9.9`. - Fail:
    `1.2.3-build.1`, `9.9.9-build.1`. - `>=1.2.3-0` results in: - Pass:
    `1.2.3`, `1.2.3-build.1`, `9.9.9`. - Fail: `9.9.9-build.1`. - `<1.2.3`
    results in: - Pass: `1.2.2`, `1.0.0`. - Fail: `1.0.0-build.1`,
    `1.2.3-build.1`. - `<1.2.3-0` results in: - Pass: `1.2.2`, `1.0.0`. -
    Fail: `1.0.0-build.1`, `1.2.3-build.1`. - `@pre >=1.2.3` results in: -
    Pass: `1.2.3`, `9.9.9`, `9.9.9-build.1` - Fail: `1.2.3-build.1`. - `@pre
    >=1.2.3-0` results in: - Pass: `1.2.3`, `1.2.3-build.1`, `9.9.9`, `9.9.9-build.1`.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The field value '{0}' is not a version string.
    -
    The version '{0}' does not match the constraint '{1}'.
    Examples:
 
    Rule 'ValidVersion' {
        $Assert.Version($TargetObject, 'version')
    }
     
    Rule 'MinimumVersion' {
        $Assert.Version($TargetObject, 'version', '>=1.2.3')
    }
     
    Rule 'MinimumVersionWithPrerelease' {
        $Assert.Version($TargetObject, 'version', '>=1.2.3-0', $True)
    }
     
    Rule 'MinimumVersionWithFlag' {
        $Assert.Version($TargetObject, 'version', '@pre >=1.2.3-0')
    }
 
    WITHINPATH
    The `WithinPath` assertion method checks if the file path is within a
    required path. Checks use file system case-sensitivity rules by default.
    The following parameters are accepted:
    - `inputObject` - The object being checked for the specified field.
    - `field` - The name of the field containing a file path.
    When the field is `InputFileInfo` or `FileInfo`, PSRule will automatically
    resolve the file path. - `path` - An array of one or more directory paths to
    check. Only one path must match. - `caseSensitive` (optional) - Determines
    if case-sensitive path matching is used. This can be set to `$True` or
    `$False`. When not set or `$Null`, the case-sensitivity rules of the working
    path file system will be used.
    Reasons include:
    -
    The parameter 'inputObject' is null.
    -
    The parameter 'field' is null or empty.
    -
    The parameter 'path' is null or empty.
    -
    The field '{0}' does not exist.
    -
    The file '{0}' is not within the path '{1}'.
    Examples:
 
    Rule 'WithinPath' {
        # Require the file to be within either policy/ or security/ sub-directories.
        $Assert.WithinPath($TargetObject, 'FullName', @('policy/', 'security/'));
    }
 
    ADVANCED USAGE
    The `AssertResult` object returned from assertion methods:
    - Handles pass/ fail conditions and collection of reason information.
    - Allows rules to implement their own handling or forward it up the stack to
    affect the rule outcome.
    The following properties are available:
    - `Result` - Either `$True` (Pass) or `$False` (Fail).
    The following methods are available:
    - `AddReason(<string> text)` - Can be used to append additional reasons to
    the result. A reason can only be set if the assertion failed. Reason
    text should be localized before calling this method. Localization can be
    done using the `$LocalizedData` automatic variable. - `WithReason(<string>
    text, <bool> replace)` - Can be used to append or replace reasons on the
    result. In addition, `WithReason` can be chained. - `Reason(<string> text,
    params <object[]> args)` - Replaces the reason on the results with a
    formatted string. This method can be chained. For usage see examples
    below. - `ReasonFrom(<string> path, <string> text, params <object[]> args)`
    - Replaces the reason on the results with a formatted string. Path
    specifies the object path that affected the reason. This method can be
    chained. For usage see examples below. - `ReasonIf(<bool> condition,
    <string> text, params <object[]> args)` - Replaces the reason if the
    condition is true. This method can be chained, similar to `Reason`. -
    `ReasonIf(<string> path, <bool> condition, <string> text, params <object[]>
    args)` - Replaces the reason if the condition is true. This method can be
    chained, similar to `ReasonFrom`. - `PathPrefix(<string> path)` - Adds a
    path prefix to any reasons. This method can be chained. For usage see
    examples below. - `GetReason()` - Gets any reasons currently associated with
    the failed result.
    - `Complete()` - Returns `$True` (Pass) or `$False` (Fail) to the rule record.
     If the assertion failed, any reasons are automatically added to the rule
    record. To read the result without adding reason to the rule record use
    the `Result` property. - `Ignore()` - Ignores the result. Nothing future is
    returned and any reasons are cleared. Use this method when implementing
    custom handling.
    Use of `Complete` is optional, uncompleted results are automatically
    completed after the rule has executed. Uncompleted results may return
    reasons out of sequence.
    Using these advanced methods is not supported in rule script pre-conditions.
    In this example, `Complete` is used to find the first field with an empty
    value.
 
    Rule 'Assert.HasFieldValue' {
        $Assert.HasFieldValue($TargetObject, 'Name').Complete() -and
            $Assert.HasFieldValue($TargetObject, 'Type').Complete() -and
            $Assert.HasFieldValue($TargetObject, 'Value').Complete()
    }
 
    In this example, the built-in reason is replaced with a custom reason, and
    immediately returned. The reason text is automatically formatted with any
    parameters provided.
 
    Rule 'Assert.HasCustomValue' {
        $Assert.
            HasDefaultValue($TargetObject, 'value', 'test').
            Reason('The field {0} is using a non-default value: {1}', 'value', $TargetObject.value)
     
        # With localized string
        $Assert.
            HasDefaultValue($TargetObject, 'value', 'test').
            Reason($LocalizedData.NonDefaultValue, 'value', $TargetObject.value)
    }
 
    In this example, the built-in reason has a path prefix added to any reasons.
 
    Rule 'Assert.ChildHasFieldValue' {
        $items = @($TargetObject.items)
        for ($i = 0; $i -lt $items.Length; $i++) {
            $Assert.HasFieldValue($items[$i], 'Name').PathPrefix("items[$i]")
        }
    }
 
    DOWNSTREAM ISSUES
    Before PSRule performs analysis external tools or rules modules may have
    already performed analysis. Issues identified by downstream tools can be
    consumed by PSRule using the `_PSRule.issue` property. If a `_PSRule`
    property exists with `issue` sub-property PSRule will consume `issue` as an
    array of issues.
    Each issue has the following properties:
    - `type` - The issue type. Issues are filtered by type. - `name` - The
    name of a specific issue.
    - `message` - The reason message for the issue.
    To get issues for an object use the `Get` or `Any` methods.
 
    # Get an array of all issues for the current object.
    $PSRule.Issue.Get();
     
    # Get an array of issues of a specific type.
    $PSRule.Issue.Get('CustomIssue');
     
    # Return true of any issues exist.
    $PSRule.Issue.Any();
     
    # Return true of any issues of a specific type exist.
    $PSRule.Issue.Any('CustomIssue');
 
    For example:
 
    # Synopsis: Fail if the object has any 'PSRule.Rules.Azure.Parameter.Insecure' issues.
    Rule 'IssueReportTest' {
        $Assert.Create($PSRule.Issue.Get('PSRule.Rules.Azure.Parameter.Insecure'));
    }
 
    AUTHORING ASSERTION METHODS
    The following built-in helper methods are provided for working with
    `$Assert` when authoring new assertion methods:
    - `Create(<bool> condition, <string> reason, params <object[]> args)` -
    Returns a result either pass or fail assertion result. Additional
    arguments can be provided to format the custom reason string. -
    `Create(<TargetIssueInfo[]>)` - Returns a result based on reported
    downstream issues.
    - `Pass()` - Returns a pass assertion result.
    - `Fail()` - Results a fail assertion result.
    - `Fail(<string> reason, params <object[]> args)` - Results a fail assertion
    result with a custom reason. Additional arguments can be provided to format
    the custom reason string.
 
    AGGREGATING ASSERTION METHODS
    The following built-in helper methods are provided for aggregating assertion results:
    - `AnyOf(<AssertResult[]> results)` - Results from assertion methods are
    aggregated into a single result. If any result is a pass, the result is a
    pass. If all results are fails, the result is a fail and any reasons are
    added to the result. If no results are provided, the result is a fail. -
    `AllOf(<AssertResult[]> results)` - Results from assertion methods are
    aggregated into a single result. If all results are passes, the result is
    a pass. If any result is a fail, the result is a fail and any reasons are
    added to the result. If no results are provided, the result is a fail.
    For example:
 
    Rule 'Assert.HasFieldValue' {
        $Assert.AllOf(
            $Assert.HasFieldValue($TargetObject, 'Name'),
            $Assert.HasFieldValue($TargetObject, 'Type'),
            $Assert.HasFieldValue($TargetObject, 'Value')
        )
    }
 
NOTE
    An online version of this document is available at
    https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Assert/.
 
SEE ALSO
    -
    about_PSRule_Variables
 
KEYWORDS
    - Assert
    - Contains
    - EndsWith
    - Greater
    - GreaterOrEqual
    - HasDefaultValue
    - HasField
    - HasFieldValue
    - JsonSchema
    - Less
    - LessOrEqual
    - NullOrEmpty
    - StartsWith
    - Version
    - Rule