Add debug messages and verbose limiting #146 #235 (#236)

- Add debug messages and verbose limiting #146 #235 - Fix test to handle DebugPreference for Window PS - Fix within comparison issue #237
microsoft · Jul 4, 2019 · c24358d · c24358d
1 parent 0d57f6d
commit c24358d
Show file tree

Hide file tree

Showing 31 changed files with 956 additions and 282 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,10 @@
 ## Unreleased
 
 - Fix YAML options file discovery issue in dotted directory. [#232](https://github.com/BernieWhite/PSRule/issues/232)
+- Fix comparison of wrapped types and null with `Within`. [#237](https://github.com/BernieWhite/PSRule/issues/237)
 - PSRule options are now displayed as YAML instead of complex object. [#233](https://github.com/BernieWhite/PSRule/issues/233)
+- Add support for debug messages and `Write-Debug` in rule definitions. [#146](https://github.com/BernieWhite/PSRule/issues/146)
+- Added `Logging.LimitDebug` and `Logging.LimitVerbose` options to limit logging to named scopes. [#235](https://github.com/BernieWhite/PSRule/issues/235)
 
 ## v0.7.0
 

diff --git a/README.md b/README.md
@@ -188,6 +188,8 @@ The following conceptual topics exist in the `PSRule` module:
   - [Execution.NotProcessedWarning](docs/concepts/PSRule/en-US/about_PSRule_Options.md#not-processed-warning)
   - [Input.Format](docs/concepts/PSRule/en-US/about_PSRule_Options.md#inputformat)
   - [Input.ObjectPath](docs/concepts/PSRule/en-US/about_PSRule_Options.md#inputobjectpath)
+  - [Logging.LimitDebug](docs/concepts/PSRule/en-US/about_PSRule_Options.md#logginglimitdebug)
+  - [Logging.LimitVerbose](docs/concepts/PSRule/en-US/about_PSRule_Options.md#logginglimitverbose)
   - [Logging.RuleFail](docs/concepts/PSRule/en-US/about_PSRule_Options.md#loggingrulefail)
   - [Logging.RulePass](docs/concepts/PSRule/en-US/about_PSRule_Options.md#loggingrulepass)
   - [Output.As](docs/concepts/PSRule/en-US/about_PSRule_Options.md#outputas)

diff --git a/docs/commands/PSRule/en-US/New-PSRuleOption.md b/docs/commands/PSRule/en-US/New-PSRuleOption.md
@@ -18,9 +18,10 @@ New-PSRuleOption [[-Path] <String>] [[-Option] <PSRuleOption>] [-BaselineConfigu
  [-SuppressTargetName <SuppressionOption>] [-BindTargetName <BindTargetName[]>]
  [-BindTargetType <BindTargetName[]>] [-BindingIgnoreCase <Boolean>] [-TargetName <String[]>]
  [-TargetType <String[]>] [-InconclusiveWarning <Boolean>] [-NotProcessedWarning <Boolean>]
- [-Format <InputFormat>] [-ObjectPath <String>] [-LoggingRuleFail <OutcomeLogStream>]
- [-LoggingRulePass <OutcomeLogStream>] [-OutputAs <ResultFormat>] [-OutputEncoding <OutputEncoding>]
- [-OutputFormat <OutputFormat>] [-OutputPath <String>] [<CommonParameters>]
+ [-Format <InputFormat>] [-ObjectPath <String>] [-LoggingLimitDebug <String[]>]
+ [-LoggingLimitVerbose <String[]>] [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>]
+ [-OutputAs <ResultFormat>] [-OutputEncoding <OutputEncoding>] [-OutputFormat <OutputFormat>]
+ [-OutputPath <String>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -300,6 +301,38 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -LoggingLimitDebug
+
+Sets the `Logging.LimitDebug` option to limit debug messages to a list of named debug scopes.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -LoggingLimitVerbose
+
+Sets the `Logging.LimitVerbose` option to limit verbose messages to a list of named verbose scopes.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -LoggingRuleFail
 
 Sets the `Logging.RuleFail` option to generate an informational message for each rule fail.

diff --git a/docs/commands/PSRule/en-US/Set-PSRuleOption.md b/docs/commands/PSRule/en-US/Set-PSRuleOption.md
@@ -17,9 +17,10 @@ Sets options that configure PSRule execution.
 Set-PSRuleOption [[-Path] <String>] [-Option <PSRuleOption>] [-PassThru] [-Force] [-AllowClobber]
  [-BindingIgnoreCase <Boolean>] [-TargetName <String[]>] [-TargetType <String[]>]
  [-InconclusiveWarning <Boolean>] [-NotProcessedWarning <Boolean>] [-Format <InputFormat>]
- [-ObjectPath <String>] [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>]
- [-OutputAs <ResultFormat>] [-OutputEncoding <OutputEncoding>] [-OutputFormat <OutputFormat>]
- [-OutputPath <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
+ [-ObjectPath <String>] [-LoggingLimitDebug <String[]>] [-LoggingLimitVerbose <String[]>]
+ [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>] [-OutputAs <ResultFormat>]
+ [-OutputEncoding <OutputEncoding>] [-OutputFormat <OutputFormat>] [-OutputPath <String>] [-WhatIf] [-Confirm]
+ [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -245,6 +246,38 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -LoggingLimitDebug
+
+Sets the `Logging.LimitDebug` option to limit debug messages to a list of named debug scopes.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -LoggingLimitVerbose
+
+Sets the `Logging.LimitVerbose` option to limit verbose messages to a list of named verbose scopes.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -LoggingRuleFail
 
 Sets the `Logging.RuleFail` option to generate an informational message for each rule fail.

diff --git a/docs/concepts/PSRule/en-US/about_PSRule_Options.md b/docs/concepts/PSRule/en-US/about_PSRule_Options.md
@@ -23,6 +23,8 @@ The following options are available for use:
 - [Execution.NotProcessedWarning](#not-processed-warning)
 - [Input.Format](#inputformat)
 - [Input.ObjectPath](#inputobjectpath)
+- [Logging.LimitDebug](#logginglimitdebug)
+- [Logging.LimitVerbose](#logginglimitverbose)
 - [Logging.RuleFail](#loggingrulefail)
 - [Logging.RulePass](#loggingrulepass)
 - [Output.As](#outputas)
@@ -477,6 +479,82 @@ input:
   objectPath: items
 ```
 
+### Logging.LimitDebug
+
+Limits debug messages to a list of named debug scopes.
+
+When using the `-Debug` switch or preference variable, by default PSRule cmdlets log all debug output. When using debug output for debugging a specific rule, it my be helpful to limit debug message to a specific rule.
+
+To identify a rule to include in debug output use the rule name.
+
+The following built-in scopes exist in addition to rule names:
+
+- `[Discovery.Source]` - Discovery messages for `.Rule.ps1` files and rule modules.
+- `[Discovery.Rule]` - Discovery messages for individual rules within `.Rule.ps1` files.
+
+This option can be specified using:
+
+```powershell
+# PowerShell: Using the LoggingLimitDebug parameter
+$option = New-PSRuleOption -LoggingLimitDebug Rule1, Rule2;
+```
+
+```powershell
+# PowerShell: Using the Logging.LimitDebug hashtable key
+$option = New-PSRuleOption -Option @{ 'Logging.LimitDebug' = Rule1, Rule2 };
+```
+
+```powershell
+# PowerShell: Using the LoggingLimitDebug parameter to set YAML
+Set-PSRuleOption -LoggingLimitDebug Rule1, Rule2;
+```
+
+```yaml
+# YAML: Using the logging/limitDebug property
+logging:
+  limitDebug:
+  - Rule1
+  - Rule2
+```
+
+### Logging.LimitVerbose
+
+Limits verbose messages to a list of named verbose scopes.
+
+When using the `-Verbose` switch or preference variable, by default PSRule cmdlets log all verbose output. When using verbose output for troubleshooting a specific rule, it may be helpful to limit verbose messages to a specific rule.
+
+To identify a rule to include in verbose output use the rule name.
+
+The following built-in scopes exist in addition to rule names:
+
+- `[Discovery.Source]` - Discovery messages for `.Rule.ps1` files and rule modules.
+- `[Discovery.Rule]` - Discovery messages for individual rules within `.Rule.ps1` files.
+
+This option can be specified using:
+
+```powershell
+# PowerShell: Using the LoggingLimitVerbose parameter
+$option = New-PSRuleOption -LoggingLimitVerbose Rule1, Rule2;
+```
+
+```powershell
+# PowerShell: Using the Logging.LimitVerbose hashtable key
+$option = New-PSRuleOption -Option @{ 'Logging.LimitVerbose' = Rule1, Rule2 };
+```
+
+```powershell
+# PowerShell: Using the LoggingLimitVerbose parameter to set YAML
+Set-PSRuleOption -LoggingLimitVerbose Rule1, Rule2;
+```
+
+```yaml
+# YAML: Using the logging/limitVerbose property
+logging:
+  limitVerbose:
+  - Rule1
+  - Rule2
+```
+
 ### Logging.RuleFail
 
 When an object fails a rule condition the results are written to output as a structured object marked with the outcome of _Fail_. If the rule executed successfully regardless of outcome no other informational messages are shown by default.
@@ -796,6 +874,12 @@ input:
 
 # Configures outcome logging options
 logging:
+  limitDebug:
+  - Rule1
+  - Rule2
+  limitVerbose:
+  - Rule1
+  - Rule2
   ruleFail: Error
   rulePass: Information
 
@@ -848,6 +932,8 @@ input:
 
 # Configures outcome logging options
 logging:
+  limitDebug: [ ]
+  limitVerbose: [ ]
   ruleFail: None
   rulePass: None
 

diff --git a/schemas/PSRule-options.schema.json b/schemas/PSRule-options.schema.json
@@ -4,7 +4,7 @@
     "description": "A schema for PSRule YAML options files.",
     "oneOf": [
         {
-            "$ref": "#/definitions/options-v0.7.0"
+            "$ref": "#/definitions/options-v0.8.0"
         }
     ],
     "definitions": {
@@ -109,10 +109,26 @@
             },
             "additionalProperties": false
         },
-        "logging-v0.5.0": {
+        "logging-v0.8.0": {
             "type": "object",
             "description": "Options for logging outcomes to a informational streams.",
             "properties": {
+                "limitDebug": {
+                    "type": "array",
+                    "description": "Limits debug messages to a list of named debug scopes.",
+                    "items": {
+                        "type": "string"
+                    },
+                    "uniqueItems": true
+                },
+                "limitVerbose": {
+                    "type": "array",
+                    "description": "Limits verbose messages to a list of named verbose scopes.",
+                    "items": {
+                        "type": "string"
+                    },
+                    "uniqueItems": true
+                },
                 "ruleFail": {
                     "type": "string",
                     "description": "Log fail outcomes for each rule to a specific informational stream.",
@@ -187,7 +203,7 @@
             },
             "additionalProperties": false
         },
-        "options-v0.7.0": {
+        "options-v0.8.0": {
             "properties": {
                 "baseline": {
                     "type": "object",
@@ -225,7 +241,7 @@
                     "type": "object",
                     "oneOf": [
                         {
-                            "$ref": "#/definitions/logging-v0.5.0"
+                            "$ref": "#/definitions/logging-v0.8.0"
                         }
                     ]
                 },

diff --git a/src/PSRule/Commands/AssertExistsCommand.cs b/src/PSRule/Commands/AssertExistsCommand.cs
@@ -1,4 +1,5 @@
 using PSRule.Pipeline;
+using PSRule.Resources;
 using PSRule.Runtime;
 using System.Management.Automation;
 
@@ -41,17 +42,14 @@ protected override void ProcessRecord()
             {
                 actual = ObjectHelper.GetField(bindingContext: PipelineContext.CurrentThread, targetObject: targetObject, name: Field[i], caseSensitive: CaseSensitive, value: out object fieldValue);
 
-                if (expected && actual == expected)
+                if (actual)
                 {
-                    PipelineContext.CurrentThread.WriteVerbose($"[Exists] -- The field {Field[i]} exists");
+                    PipelineContext.CurrentThread.VerboseConditionMessage(condition: RuleLanguageNouns.Exists, message: PSRuleResources.ExistsTrue, args: Field[i]);
                 }
             }
 
-            if (!actual)
-            {
-                PipelineContext.CurrentThread.WriteVerbose($"[Exists] -- The field(s) {string.Join(", ", Field)} do not exist");
-            }
-
+            var result = expected == actual;
+            PipelineContext.CurrentThread.VerboseConditionResult(condition: RuleLanguageNouns.Exists, outcome: result);
             WriteObject(expected == actual);
         }
     }

diff --git a/src/PSRule/Commands/AssertMatchCommand.cs b/src/PSRule/Commands/AssertMatchCommand.cs
@@ -1,4 +1,5 @@
 using PSRule.Pipeline;
+using PSRule.Resources;
 using PSRule.Runtime;
 using System.Management.Automation;
 using System.Text.RegularExpressions;
@@ -63,12 +64,12 @@ protected override void ProcessRecord()
                     if (_Expressions[i].IsMatch(fieldValue.ToString()))
                     {
                         match = true;
+                        PipelineContext.CurrentThread.VerboseConditionMessage(condition: RuleLanguageNouns.Match, message: PSRuleResources.MatchTrue, args: fieldValue);
                     }
                 }
             }
 
             var result = expected == match;
-
             PipelineContext.CurrentThread.VerboseConditionResult(condition: RuleLanguageNouns.Match, outcome: result);
             WriteObject(result);
         }