From 74c8502cacc4bcd42b17cd0591656a44bad18fc1 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 2 Jul 2024 10:02:57 -0500 Subject: [PATCH] Add note about case-preserving key names (#11228) --- .../About/about_PSCustomObject.md | 54 +++++++++++++++--- .../About/about_PSCustomObject.md | 56 ++++++++++++++++++- .../About/about_PSCustomObject.md | 56 ++++++++++++++++++- .../About/about_PSCustomObject.md | 54 +++++++++++++++++- 4 files changed, 205 insertions(+), 15 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSCustomObject.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSCustomObject.md index fd13f269678..5a458b43cde 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSCustomObject.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSCustomObject.md @@ -1,7 +1,7 @@ --- description: Explains the differences between the [psobject] and [pscustomobject] type accelerators. Locale: en-US -ms.date: 10/11/2023 +ms.date: 07/02/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_pscustomobject?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about PSCustomObject @@ -187,7 +187,7 @@ While, casting an object to `[psobject]` appears to have no affect on the type, PowerShell adds an _invisible_ `[psobject]` wrapper around the object. This can have subtle side effects. -- Wrapped objects will match their original type and the `[psobject]` type. +- Wrapped objects match their original type and the `[psobject]` type. ```powershell PS> 1 -is [Int32] @@ -209,13 +209,53 @@ have subtle side effects. PS> '{0} {1}' -f ([psobject] (1, 2)) Error formatting a string: Index (zero based) must be greater than or equal to zero and less than the size of the argument list.. - At line:1 char:1 - + '{0} {1}' -f ([psobject] (1, 2)) - + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - + CategoryInfo : InvalidOperation: ({0} {1}:String) [], RuntimeException - + FullyQualifiedErrorId : FormatError ``` +## Conversion of hashtables containing similar keys + +Case-sensitive dictionaries might contain key names that only differ by case. +When you cast such a dictionary to a `[pscustomobject]`, PowerShell preserves +that case of the keys but isn't case-sensitive. As a result: + +- The case of the first duplicate key becomes the name of that key. +- The value of the last case-variant key becomes the property value. + +The following example demonstrates this behavior: + +```powershell +$OrderedHashTable = [System.Collections.Specialized.OrderedDictionary]::new() +$OrderedHashTable['One'] = 1 +$OrderedHashTable['TWO'] = 2 +$OrderedHashTable['two'] = 3 # case variation +$OrderedHashTable['Three'] = 3 +$OrderedHashTable +``` + +Notice that the ordered hashtable contains multiple keys that differ only by +case. + +```Output +Name Value +---- ----- +One 1 +TWO 2 +two 3 +Three 3 +``` + +When that hashtable is cast to a `[pscustomobject]`, the case of the name of +first key is used, but that value of the last matching key name is used. + +```powershell +[PSCustomObject]$OrderedHashTable +``` + +```Output +One TWO Three +--- --- ----- + 1 3 3 +``` + ## Notes In Windows PowerShell, objects created by casting a **Hashtable** to diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_PSCustomObject.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_PSCustomObject.md index 0bd6e7544bc..fe86e114116 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_PSCustomObject.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_PSCustomObject.md @@ -1,7 +1,7 @@ --- description: Explains the differences between the [psobject] and [pscustomobject] type accelerators. Locale: en-US -ms.date: 10/11/2023 +ms.date: 07/02/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_PSCustomObject?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about PSCustomObject @@ -186,8 +186,7 @@ While, casting an object to `[psobject]` appears to have no affect on the type, PowerShell adds an _invisible_ `[psobject]` wrapper around the object. This can have subtle side effects. -- Wrapped objects will match their original type and the - `[psobject]` type. +- Wrapped objects match their original type and the `[psobject]` type. ```powershell PS> 1 -is [Int32] @@ -211,6 +210,57 @@ have subtle side effects. to zero and less than the size of the argument list.. ``` +## Conversion of hashtables containing similar keys + +Case-sensitive dictionaries might contain key names that only differ by case. +When you cast such a dictionary to a `[pscustomobject]`, PowerShell preserves +that case of the keys but isn't case-sensitive. As a result: + +- The case of the first duplicate key becomes the name of that key. +- The value of the last case-variant key becomes the property value. + +The following example demonstrates this behavior: + +```powershell +$Json = '{ + "One": 1, + "two": 2, + "Two": 3, + "three": 3, + "Three": 4, + "THREE": 5 +}' +$OrderedHashTable = $Json | ConvertFrom-Json -AsHashTable +$OrderedHashTable +``` + +Notice that the ordered hashtable contains multiple keys that differ only by +case. + +```Output +Name Value +---- ----- +One 1 +two 2 +Two 3 +three 3 +Three 4 +THREE 5 +``` + +When that hashtable is cast to a `[pscustomobject]`, the case of the name of +first key is used, but that value of the last matching key name is used. + +```powershell +[PSCustomObject]$OrderedHashTable +``` + +```Output +One two three +--- --- ----- + 1 3 5 +``` + ## Notes In Windows PowerShell, objects created by casting a **Hashtable** to diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_PSCustomObject.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_PSCustomObject.md index 6c2fa254128..669676b9ac3 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_PSCustomObject.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_PSCustomObject.md @@ -1,7 +1,7 @@ --- description: Explains the differences between the [psobject] and [pscustomobject] type accelerators. Locale: en-US -ms.date: 10/11/2023 +ms.date: 07/02/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_pscustomobject?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about PSCustomObject @@ -186,8 +186,7 @@ While, casting an object to `[psobject]` appears to have no affect on the type, PowerShell adds an _invisible_ `[psobject]` wrapper around the object. This can have subtle side effects. -- Wrapped objects will match their original type and the - `[psobject]` type. +- Wrapped objects match their original type and the `[psobject]` type. ```powershell PS> 1 -is [Int32] @@ -211,6 +210,57 @@ have subtle side effects. to zero and less than the size of the argument list.. ``` +## Conversion of hashtables containing similar keys + +Case-sensitive dictionaries might contain key names that only differ by case. +When you cast such a dictionary to a `[pscustomobject]`, PowerShell preserves +that case of the keys but isn't case-sensitive. As a result: + +- The case of the first duplicate key becomes the name of that key. +- The value of the last case-variant key becomes the property value. + +The following example demonstrates this behavior: + +```powershell +$Json = '{ + "One": 1, + "two": 2, + "Two": 3, + "three": 3, + "Three": 4, + "THREE": 5 +}' +$OrderedHashTable = $Json | ConvertFrom-Json -AsHashTable +$OrderedHashTable +``` + +Notice that the ordered hashtable contains multiple keys that differ only by +case. + +```Output +Name Value +---- ----- +One 1 +two 2 +Two 3 +three 3 +Three 4 +THREE 5 +``` + +When that hashtable is cast to a `[pscustomobject]`, the case of the name of +first key is used, but that value of the last matching key name is used. + +```powershell +[PSCustomObject]$OrderedHashTable +``` + +```Output +One two three +--- --- ----- + 1 3 5 +``` + ## Notes In Windows PowerShell, objects created by casting a **Hashtable** to diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_PSCustomObject.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_PSCustomObject.md index a7bc7fe193c..de55e85f806 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_PSCustomObject.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_PSCustomObject.md @@ -186,8 +186,7 @@ While, casting an object to `[psobject]` appears to have no affect on the type, PowerShell adds an _invisible_ `[psobject]` wrapper around the object. This can have subtle side effects. -- Wrapped objects will match their original type and the - `[psobject]` type. +- Wrapped objects match their original type and the `[psobject]` type. ```powershell PS> 1 -is [Int32] @@ -211,6 +210,57 @@ have subtle side effects. to zero and less than the size of the argument list.. ``` +## Conversion of hashtables containing similar keys + +Case-sensitive dictionaries might contain key names that only differ by case. +When you cast such a dictionary to a `[pscustomobject]`, PowerShell preserves +that case of the keys but isn't case-sensitive. As a result: + +- The case of the first duplicate key becomes the name of that key. +- The value of the last case-variant key becomes the property value. + +The following example demonstrates this behavior: + +```powershell +$Json = '{ + "One": 1, + "two": 2, + "Two": 3, + "three": 3, + "Three": 4, + "THREE": 5 +}' +$OrderedHashTable = $Json | ConvertFrom-Json -AsHashTable +$OrderedHashTable +``` + +Notice that the ordered hashtable contains multiple keys that differ only by +case. + +```Output +Name Value +---- ----- +One 1 +two 2 +Two 3 +three 3 +Three 4 +THREE 5 +``` + +When that hashtable is cast to a `[pscustomobject]`, the case of the name of +first key is used, but that value of the last matching key name is used. + +```powershell +[PSCustomObject]$OrderedHashTable +``` + +```Output +One two three +--- --- ----- + 1 3 5 +``` + ## Notes In Windows PowerShell, objects created by casting a **Hashtable** to