en-US/about_PSRule_Selectors.help.txt
|
TOPIC
about_psrule_selectors SHORT DESCRIPTION Describes PSRule Selectors including how to use and author them. LONG DESCRIPTION PSRule executes rules to validate an object from input. When evaluating an object from input, PSRule can use selectors to perform complex matches of an object. - A selector is a YAML/JSON based expression that evaluates an object. - Each selector is comprised of nested conditions, operators, and comparison properties. - Selectors must use one or more available conditions with a comparison property to evaluate the object. - Optionally a condition can be nested in an operator. - Operators can be nested within other operators. The following conditions are available: - Contains - Count - Equals - EndsWith - Exists - Greater - GreaterOrEquals - HasDefault - HasSchema - HasValue - In - IsLower - IsString - IsArray - IsBoolean - IsDateTime - IsInteger - IsNumeric - IsUpper - Less - LessOrEquals - Match - NotEquals - NotIn - NotMatch - SetOf - StartsWith - Subset - Version The following operators are available: - AllOf - AnyOf - Not The following comparison properties are available: - Field - Name - Type To learn more about conditions, operators, and properties see about_PSRule_Expressions . Currently the following limitations apply: - Selectors can evaluate: - Fields of the target object. - Type and name binding of the target object by using `name` and `type` comparison properties. - State variables such has `$PSRule` can not be evaluated. - Bound fields can not be evaluated. USING SELECTORS AS PRE-CONDITIONS Selectors can be referenced by name as a rule pre-condition by using the `-With` parameter. For example: Rule 'RuleWithSelector' -With 'BasicSelector' { # Rule condition } Selector pre-conditions can be used together with type and script block pre-conditions. If one or more selector pre-conditions are used, they are evaluated before type or script block pre-conditions. DEFINING SELECTORS Selectors can be defined with either YAML or JSON format, and can be included with a module or standalone `.Rule.yaml` or `.Rule.jsonc` file. In either case, define a selector within a file ending with the `.Rule.yaml` or `.Rule.jsonc` extension. A selector can be defined side-by-side with other resources such as baselines or module configurations. Selectors can also be defined within `.json` files. We recommend using `.jsonc` to view JSON with Comments in Visual Studio Code. Use the following template to define a selector: ```yaml SYNOPSIS: {{ SYNOPSIS }} apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: '{{ Name }}' spec: if: { } jsonc [ { // Synopsis: {{ Synopsis }} "apiVersion": "github.com/microsoft/PSRule/v1", "kind": "Selector", "metadata": { "name": "{{ Name }}" }, "spec": { "if": {} } } ] Within the `if` object, one or more conditions or logical operators can be used. ## EXAMPLES ### Example Selectors.Rule.yaml yaml EXAMPLE SELECTORS.RULE.YAML --- SYNOPSIS: REQUIRE THE CUSTOMVALUE FIELD. apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: RequireCustomValue spec: if: field: 'CustomValue' exists: true --- SYNOPSIS: REQUIRE A NAME OR ALTERNATIVENAME. apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: RequireName spec: if: anyOf: - field: 'AlternateName' exists: true - field: 'Name' exists: true --- SYNOPSIS: REQUIRE A SPECIFIC CUSTOMVALUE apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: RequireSpecificCustomValue spec: if: field: 'CustomValue' in: - 'Value1' - 'Value2' ### Example Selectors.Rule.jsonc jsonc // Example Selectors.Rule.jsonc [ { // Synopsis: Require the CustomValue field. "apiVersion": "github.com/microsoft/PSRule/v1", "kind": "Selector", "metadata": { "name": "RequireCustomValue" }, "spec": { "if": { "field": "CustomValue", "exists": true } } }, { // Synopsis: Require a Name or AlternativeName. "apiVersion": "github.com/microsoft/PSRule/v1", "kind": "Selector", "metadata": { "name": "RequireName" }, "spec": { "if": { "anyOf": [ { "field": "AlternateName", "exists": true }, { "field": "Name", "exists": true } ] } } }, { // Synopsis: Require a specific CustomValue "apiVersion": "github.com/microsoft/PSRule/v1", "kind": "Selector", "metadata": { "name": "RequireSpecificCustomValue" }, "spec": { "if": { "field": "CustomValue", "in": [ "Value1", "Value2" ] } } } ] ``` NOTE An online version of this document is available at https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Selectors/. SEE ALSO - Invoke-PSRule KEYWORDS - Selectors - Expressions - PSRule |