diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index e3e0bb0c99a9..f698d3c1ee90 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -11,18 +11,21 @@ title: ConvertFrom-Json # ConvertFrom-Json ## SYNOPSIS -Converts a JSON-formatted string to a custom object. +Converts a JSON-formatted string to a custom object or a hash table. ## SYNTAX ``` -ConvertFrom-Json [-InputObject] [-InformationAction ] - [-InformationVariable ] [] +ConvertFrom-Json [-InputObject] [-AsHashtable] +[-InformationAction ] [-InformationVariable ] [] ``` ## DESCRIPTION The **ConvertFrom-Json** cmdlet converts a JavaScript Object Notation (JSON) formatted string to a custom **PSCustomObject** object that has a property for each field in the JSON string. JSON is commonly used by web sites to provide a textual representation of objects. +The JSON standard does not prohibit usage that is prohibited with a PSCustomObject. +For example, if the JSON string contains duplicate keys, only the last key is used by this cmdlet. +See other examples below. To generate a JSON string from any object, use the ConvertTo-Json cmdlet. @@ -77,6 +80,14 @@ Then it uses the pipeline operator to send the delimited string to the **Convert The Join operator is required, because the **ConvertFrom-Json** cmdlet expects a single string. +### Example 4: Convert a JSON string to a hash table +```` +PS C:\> '{ "key":"value1", "Key":"value2" }' | ConvertFrom-Json -AsHashtable +```` + +This command shows an example where the `-AsHashtable` switch can overcome limitations of the command: the JSON string contains 2 key value pairs with keys that differ only in casing. Without the switch, the command would have thrown an error. + + ## PARAMETERS ### -InformationAction @@ -127,6 +138,23 @@ Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` +### -AsHashtable +Converts the JSON to a hash table object. This switch was introduced in PowerShell 6.0. +There are several scenarios where it can overcome some limitations of the `ConvertFrom-Json` cmdlet +- If the JSON contains a list with keys that only differ in casing. Without the switch, those keys would be seen as identical keys and therefore only the last one would get used. +- If the JSON contains a key that is an empty string. Without the switch, the cmdlet would throw an error since a `PSCustomObject` does not allow for that but a hash table does. An example use case where this can occurs are `project.lock.json` files. +- Hash tables can be processed faster for certain data structures. + + ```yaml + Type: SwitchParameter + Aliases: + + Required: False + Default value: False + 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). @@ -139,6 +167,8 @@ You can pipe a JSON string to **ConvertFrom-Json**. ### PSCustomObject +### System.Collections.Hashtable + ## NOTES * The **ConvertFrom-Json** cmdlet is implemented by using the [JavaScriptSerializer class](https://msdn.microsoft.com/library/system.web.script.serialization.javascriptserializer).