Add documentation of new -AsHashtable switch for ConvertFrom-Json introduced by PR #5043

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] <String> [-InformationAction <ActionPreference>]
- [-InformationVariable <String>] [<CommonParameters>]
+ConvertFrom-Json [-InputObject] <String> [-AsHashtable]
+[-InformationAction <ActionPreference>] [-InformationVariable <String>] [<CommonParameters>]
 ```
 
 ## 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).