Added support for reading objects from file and serializing output (#107

) - Added support for using `-InputPath` instead of using `-InputObject` to handle serialized objects. [#106](BernieWhite#106) - `-Format` is automatically detected for `.yaml`, `.yml` and `.json` file extensions. - Added `-OutputFormat` parameter to serialize output from `Invoke-PSRule`. [#29](BernieWhite#29)
microsoft · Mar 20, 2019 · 94abb89 · 94abb89
1 parent 2f52ab0
commit 94abb89
Show file tree

Hide file tree

Showing 30 changed files with 779 additions and 78 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,9 @@
 
 ## Unreleased
 
+- Added support for using `-InputPath` instead of using `-InputObject` to handle serialized objects. [#106](https://github.com/BernieWhite/PSRule/issues/106)
+  - `-Format` is automatically detected for `.yaml`, `.yml` and `.json` file extensions.
+- Added `-OutputFormat` parameter to serialize output from `Invoke-PSRule`. [#29](https://github.com/BernieWhite/PSRule/issues/29)
 - Added support for logging pass or fail outcomes to a data stream such as Error, Warning or Information [#97](https://github.com/BernieWhite/PSRule/issues/97)
 - **Breaking change** - Deprecated usage of the `-TargetName` parameter on the `Hint` keyword has been removed [#81](https://github.com/BernieWhite/PSRule/issues/81)
 

diff --git a/README.md b/README.md
@@ -172,6 +172,7 @@ The following conceptual topics exist in the `PSRule` module:
   - [Input.ObjectPath](docs/concepts/PSRule/en-US/about_PSRule_Options.md#inputobjectpath)
   - [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.Format](docs/concepts/PSRule/en-US/about_PSRule_Options.md#outputformat)
   - [Suppression](docs/concepts/PSRule/en-US/about_PSRule_Options.md#rule-suppression)
 - [Variables](docs/concepts/PSRule/en-US/about_PSRule_Variables.md)
   - [$Configuration](docs/concepts/PSRule/en-US/about_PSRule_Variables.md#configuration)

diff --git a/docs/commands/PSRule/en-US/Invoke-PSRule.md b/docs/commands/PSRule/en-US/Invoke-PSRule.md
@@ -13,10 +13,20 @@ Evaluate pipeline objects against matching rules.
 
 ## SYNTAX
 
+### Input (Default)
+
 ```text
 Invoke-PSRule [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] -InputObject <PSObject>
  [-Outcome <RuleOutcome>] [-Option <PSRuleOption>] [-As <ResultFormat>] [-Format <InputFormat>]
- [-ObjectPath <String>] [-Module <String[]>] [<CommonParameters>]
+ [-ObjectPath <String>] [-Module <String[]>] [-OutputFormat <OutputFormat>] [<CommonParameters>]
+```
+
+### InputPath
+
+```text
+Invoke-PSRule [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Outcome <RuleOutcome>]
+ [-Option <PSRuleOption>] [-As <ResultFormat>] [-Format <InputFormat>] [-ObjectPath <String>]
+ [-Module <String[]>] [-OutputFormat <OutputFormat>] -InputPath <String[]> [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -183,7 +193,7 @@ The pipeline object to process rules for.
 
 ```yaml
 Type: PSObject
-Parameter Sets: (All)
+Parameter Sets: Input
 Aliases: TargetObject
 
 Required: True
@@ -235,17 +245,20 @@ Accept wildcard characters: False
 
 ### -Format
 
-Configures the input format for when a string is passed in as a target object. By default, strings are just treated as raw text. However, when set strings can be read as YAML or JSON and converted to an object.
+Configures the input format for when a string is passed in as a target object.
+
+- When the `-InputObject` parameter or pipeline input is used, strings are treated as plain text by default. When this option is used and set to either `Yaml` or `Json`, strings are read as YAML or JSON and are converted to an object.
+- When the `-InputPath` parameter is used with a file path or URL, by default the file extension (either `.yaml`, `.yml` or `.json`) will be used to automatically detect the format as YAML or JSON.
 
 ```yaml
 Type: InputFormat
 Parameter Sets: (All)
 Aliases:
-Accepted values: None, Yaml, Json
+Accepted values: None, Yaml, Json, Detect
 
 Required: False
 Position: Named
-Default value: None
+Default value: Detect
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
@@ -284,6 +297,39 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -InputPath
+
+Instead of processing objects from the pipeline, import objects file the specified file paths.
+
+```yaml
+Type: String[]
+Parameter Sets: InputPath
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -OutputFormat
+
+Configures the format that output is presented in.
+
+```yaml
+Type: OutputFormat
+Parameter Sets: (All)
+Aliases:
+Accepted values: None, Yaml, Json
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

diff --git a/docs/commands/PSRule/en-US/Test-PSRuleTarget.md b/docs/commands/PSRule/en-US/Test-PSRuleTarget.md
@@ -13,12 +13,21 @@ Pass or fail pipeline objects against matching rules.
 
 ## SYNTAX
 
+### Input (Default)
+
 ```text
 Test-PSRuleTarget [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] -InputObject <PSObject>
  [-Option <PSRuleOption>] [-Format <InputFormat>] [-ObjectPath <String>] [-Module <String[]>]
  [<CommonParameters>]
 ```
 
+### InputPath
+
+```text
+Test-PSRuleTarget [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>]
+ [-Format <InputFormat>] [-ObjectPath <String>] [-Module <String[]>] -InputPath <String[]> [<CommonParameters>]
+```
+
 ## DESCRIPTION
 
 Evaluate pipeline objects against matching rules and return an overall pass or fail for the object as `$True` (pass) or `$False` (fail).
@@ -104,7 +113,7 @@ The pipeline object to process rules for.
 
 ```yaml
 Type: PSObject
-Parameter Sets: (All)
+Parameter Sets: Input
 Aliases: TargetObject
 
 Required: True
@@ -134,17 +143,20 @@ Accept wildcard characters: False
 
 ### -Format
 
-Configures the input format for when a string is passed in as a target object. By default, strings are just treated as raw text. However, when set strings can be read as YAML or JSON and converted to an object.
+Configures the input format for when a string is passed in as a target object.
+
+- When the `-InputObject` parameter or pipeline input is used, strings are treated as plain text by default. When this option is used and set to either `Yaml` or `Json`, strings are read as YAML or JSON and are converted to an object.
+- When the `-InputPath` parameter is used with a file path or URL, by default the file extension (either `.yaml`, `.yml` or `.json`) will be used to automatically detect the format as YAML or JSON.
 
 ```yaml
 Type: InputFormat
 Parameter Sets: (All)
 Aliases:
-Accepted values: None, Yaml, Json
+Accepted values: None, Yaml, Json, Detect
 
 Required: False
 Position: Named
-Default value: None
+Default value: Detect
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
@@ -183,6 +195,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -InputPath
+
+Instead of processing objects from the pipeline, import objects file the specified file paths.
+
+```yaml
+Type: String[]
+Parameter Sets: InputPath
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

diff --git a/docs/concepts/PSRule/en-US/about_PSRule_Options.md b/docs/concepts/PSRule/en-US/about_PSRule_Options.md
@@ -25,6 +25,7 @@ The following options are available for use:
 - [Input.ObjectPath](#inputobjectpath)
 - [Logging.RuleFail](#loggingrulefail)
 - [Logging.RulePass](#loggingrulepass)
+- [Output.Format](#outputformat)
 - [Suppression](#rule-suppression)
 
 Options can be used by:
@@ -330,15 +331,20 @@ execution:
 
 ### Input.Format
 
-Configures the input format for when a string is passed in as a target object. By default, strings are just treated as raw text. However, when set strings can be read as YAML or JSON and converted to an object.
+Configures the input format for when a string is passed in as a target object.
 
-When using `Invoke-PSRule` and `Test-PSRuleTarget` the `-Format` parameter will override any value set in configuration.
+Using this option with `Invoke-PSRule` or `Test-PSRuleTarget`:
+
+- When the `-InputObject` parameter or pipeline input is used, strings are treated as plain text by default. When this option is used and set to either `Yaml` or `Json`, strings are read as YAML or JSON and are converted to an object.
+- When the `-InputPath` parameter is used with a file path or URL, by default the file extension (either `.yaml`, `.yml` or `.json`) will be used to automatically detect the format as YAML or JSON.
+- The `-Format` parameter will override any value set in configuration.
 
 The following formats are available:
 
-- None
-- Yaml
-- Json
+- None - Treat strings as plain text.
+- Yaml - Treat strings as one or more YAML objects.
+- Json - Treat strings as one or more JSON objects.
+- Detect - Detect format based on file extension. Detection only applies when used with the `-InputPath` parameter. In all other cases, `Detect` is the same as `None`. This is the default configuration.
 
 This option can be specified using:
 
@@ -432,6 +438,29 @@ logging:
   rulePass: Information
 ```
 
+### Output.Format
+
+Configures the format that results will be presented in.
+
+The following format options are available:
+
+- None - Output is presented as an object using PowerShell defaults. This is the default configuration.
+- Yaml - Output is serialized as YAML.
+- Json - Output is serialized as JSON.
+
+This option can be specified using:
+
+```powershell
+# PowerShell: Using the Output.Format hashtable key
+$option = New-PSRuleOption -Option @{ 'Output.Format' = 'Yaml' };
+```
+
+```yaml
+# YAML: Using the output/format property
+output:
+  format: Yaml
+```
+
 ### Rule suppression
 
 In certain circumstances it may be necessary to exclude or suppress rules from processing objects that are in a known failed state.
@@ -536,6 +565,9 @@ logging:
   ruleFail: Error
   rulePass: Information
 
+output:
+  format: Json
+
 # Configure rule suppression
 suppression:
   storageAccounts.UseHttps:
@@ -576,14 +608,17 @@ execution:
 
 # Configures input options
 input:
-  format: None
+  format: Detect
   objectPath:
 
 # Configures outcome logging options
 logging:
   ruleFail: None
   rulePass: None
 
+output:
+  format: None
+
 # Configure rule suppression
 suppression: { }
 ```

diff --git a/schemas/PSRule-options-0.4.0.schema.json b/schemas/PSRule-options-0.4.0.schema.json
@@ -127,6 +127,28 @@
             },
             "additionalProperties": false
         },
+        "input-v0.4.0": {
+            "type": "object",
+            "description": "Options that affect how input types are processed.",
+            "properties": {
+                "format": {
+                    "type": "string",
+                    "description": "The input string format.",
+                    "enum": [
+                        "None",
+                        "Yaml",
+                        "Json",
+                        "Detect"
+                    ],
+                    "default": "Detect"
+                },
+                "objectPath": {
+                    "type": "string",
+                    "description": "The object path to a property to use instead of the pipeline object."
+                }
+            },
+            "additionalProperties": false
+        },
         "logging-v0.4.0": {
             "type": "object",
             "description": "Options for logging outcomes to a informational streams.",
@@ -160,6 +182,23 @@
             "type": "object",
             "description": "Specifies suppression rules."
         },
+        "output-v0.4.0": {
+            "type": "object",
+            "description": "Options that affect how output is generated.",
+            "properties": {
+                "format": {
+                    "type": "string",
+                    "description": "The output format.",
+                    "enum": [
+                        "None",
+                        "Yaml",
+                        "Json"
+                    ],
+                    "default": "None"
+                }
+            },
+            "additionalProperties": false
+        },
         "options-v0.2.0": {
             "properties": {
                 "baseline": {
@@ -272,7 +311,7 @@
                     "type": "object",
                     "oneOf": [
                         {
-                            "$ref": "#/definitions/input-v0.3.0"
+                            "$ref": "#/definitions/input-v0.4.0"
                         }
                     ]
                 },
@@ -284,6 +323,14 @@
                         }
                     ]
                 },
+                "output": {
+                    "type": "object",
+                    "oneOf": [
+                        {
+                            "$ref": "#/definitions/output-v0.4.0"
+                        }
+                    ]
+                },
                 "suppression": {
                     "type": "object",
                     "oneOf": [