From d9fabd586ebbf80f03ec4c933a7741ca54cd611b Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 14 Nov 2017 20:20:34 +0000 Subject: [PATCH 1/6] add documentation of new -AsHashTable switch for ConvertFrom-Json and also document the behaviour in case of duplicate strings. --- .../ConvertFrom-Json.md | 36 +++++++++++++++++-- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index e3e0bb0c99a9..7f03a349857c 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -11,18 +11,19 @@ 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 duplicate keys and in this case the cmdlet would disregard the duplicates and only use the last one. If keys differ only in casing then the `-AsHashTable` switch has to be used. To generate a JSON string from any object, use the ConvertTo-Json cmdlet. @@ -77,6 +78,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", "":"value3 }' | ConvertFrom-Json -AsHashtable +```` + +This command shows 2 cases 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 and the key that is just an empty string. Without the switch, the command would have thrown an error. + + ## PARAMETERS ### -InformationAction @@ -127,6 +136,25 @@ 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 + Parameter Sets: UNNAMED_PARAMETER_SET_1 + Aliases: + + Required: False + Position: Named + Default value: False + Accept pipeline input: True (ByValue) + 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). From 7b7c5578bcf41b7d4bbb5cde569c678c6380fee9 Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 14 Nov 2017 20:25:10 +0000 Subject: [PATCH 2/6] correct casing of -AsHashtable switch. --- .../6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index 7f03a349857c..4f5387760912 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -23,7 +23,7 @@ ConvertFrom-Json [-InputObject] [-AsHashtable] ## 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 duplicate keys and in this case the cmdlet would disregard the duplicates and only use the last one. If keys differ only in casing then the `-AsHashTable` switch has to be used. +The JSON standard does not prohibit duplicate keys and in this case the cmdlet would disregard the duplicates and only use the last one. If keys differ only in casing then the `-AsHashtable` switch has to be used. To generate a JSON string from any object, use the ConvertTo-Json cmdlet. @@ -83,7 +83,7 @@ The Join operator is required, because the **ConvertFrom-Json** cmdlet expects a PS C:\> '{ "key":"value1", "Key":"value2", "":"value3 }' | ConvertFrom-Json -AsHashtable ```` -This command shows 2 cases 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 and the key that is just an empty string. Without the switch, the command would have thrown an error. +This command shows 2 cases 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 and the key that is just an empty string. Without the switch, the command would have thrown an error. ## PARAMETERS @@ -136,7 +136,7 @@ Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` -### -AsHashTable +### -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. From 772c2a547f445118124e769780d58e87f146d05e Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 15 Nov 2017 19:18:11 +0000 Subject: [PATCH 3/6] Address PR comments about -AsHashtable switch for ConvertFrom-Json.md --- .../6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index 4f5387760912..a4492afa7682 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -23,7 +23,9 @@ ConvertFrom-Json [-InputObject] [-AsHashtable] ## 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 duplicate keys and in this case the cmdlet would disregard the duplicates and only use the last one. If keys differ only in casing then the `-AsHashtable` switch has to be used. +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. @@ -80,10 +82,10 @@ The Join operator is required, because the **ConvertFrom-Json** cmdlet expects a ### Example 4: Convert a JSON string to a hash table ```` -PS C:\> '{ "key":"value1", "Key":"value2", "":"value3 }' | ConvertFrom-Json -AsHashtable +PS C:\> '{ "key":"value1", "Key":"value2" }' | ConvertFrom-Json -AsHashtable ```` -This command shows 2 cases 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 and the key that is just an empty string. Without the switch, the command would have thrown an error. +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 @@ -145,11 +147,9 @@ There are several scenarios where it can overcome some limitations of the `Conve ```yaml Type: SwitchParameter - Parameter Sets: UNNAMED_PARAMETER_SET_1 Aliases: Required: False - Position: Named Default value: False Accept pipeline input: True (ByValue) Accept wildcard characters: False From 6e76191c4546d97c8621054c8394715083ab4626 Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 15 Nov 2017 20:14:18 +0000 Subject: [PATCH 4/6] Accept pipeline input: False for -AsHashtable switch in ConvertFrom-Json.md --- reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index a4492afa7682..47374616a534 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -134,7 +134,7 @@ Aliases: Required: True Position: 1 Default value: None -Accept pipeline input: True (ByValue) +Accept pipeline input: False Accept wildcard characters: False ``` From 853e9b38b061e63602a8232ec4a3c2ad6caa847d Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 15 Nov 2017 21:00:52 +0000 Subject: [PATCH 5/6] Revert "Accept pipeline input: False for -AsHashtable switch in ConvertFrom-Json.md" Accidentally change the wrong field. This reverts commit 6e76191c4546d97c8621054c8394715083ab4626. --- reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index 47374616a534..a4492afa7682 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -134,7 +134,7 @@ Aliases: Required: True Position: 1 Default value: None -Accept pipeline input: False +Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` From cd44c03b2d77296044ae76fb5259809eb7b0f20e Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 15 Nov 2017 21:02:00 +0000 Subject: [PATCH 6/6] Accept pipeline input: False for -AsHashtable switch in ConvertFrom-Json.md --- reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index a4492afa7682..f698d3c1ee90 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -151,7 +151,7 @@ There are several scenarios where it can overcome some limitations of the `Conve Required: False Default value: False - Accept pipeline input: True (ByValue) + Accept pipeline input: False Accept wildcard characters: False ```