`about_Case-Sensitivity` lacks detail in a lot of areas

[surfingoldelephant]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in Get-Foo cmdlet" instead of "Typo."
• Verify Version: If there is a mismatch between documentation and the behavior on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.

Links

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_case-sensitivity

Summary

about_Case-Sensitivity lacks detail in a lot of areas.

The purpose of this issue is to document areas of PowerShell which are case-sensitive by default or handle case inconsistently/conditionally.

Details

Areas of PowerShell which are either case-sensitive by default or handle case inconsistently/conditionally:

• PS providers:
  • The FileSystem and Environment providers are case-sensitive on case-sensitive file systems. Generally, but not always, that means case-insensitive for Windows systems and case-sensitive for non-Windows systems. See: about_Case-Sensitivity lacks detail in a lot of areas #12624 (comment)
  • However, wildcard matching by provider cmdlets is case-insensitive, irrespective of the system.

    [void] (New-Item -Path Temp:foo.txt -Force)
    
    (Get-Item -Path Temp:FOO.txt).Name
    # Get-Item: Cannot find path 'Temp:/FOO.txt' because it does not exist.
    
    (Get-Item -Path Temp:F[O]*.txt).Name 
    # foo.txt
    
    (Get-Item -Path Env:hOME).Name
    # Get-Item: Cannot find path 'Env:/hOME' because it does not exist.
    
    (Get-Item -Path Env:hOM[E]).Name
    # HOME

• Parameter set names:
  • DefaultParameterSetName case must be identical to ParameterSetName.
  • Parameter set names are unexpectedly case-sensitive PowerShell/PowerShell#11183
  • New Rule Suggestion: ParameterSetName mismatch. PowerShell/PSScriptAnalyzer#396
• .NET methods often exhibit case-sensitive behavior by default. E.g.,
  • Equivalent .NET methods (without explicit opt-in) for common PowerShell operators.
    • E.g., Array.Contains(), String.Contains(), String.Replace(), Regex.Match(), Regex.Replace(), etc.
  • Reflection (member names must use the correct case).
  • Non-literal dictionary instantiation.
    • E.g., [hashtable]::new() has case-sensitive keys, whereas a hash table literal @{} has case-insensitive keys. Likewise with [ordered] @{} vs [ordered]::new() ([ordered] is only a type accelerator in PS v7+).
  • Explicitly calling Enum.Parse() is case-sensitive by default, whereas PowerShell typically handles enums in a case-insensitive manner.
• -Unique cmdlets:
  • Select-Object -Unique and Get-Unique are case-sensitive by default (-CaseInsensitive switch added in PS v7.4).
  • Sort-Object -Unique is case-insensitive by default (has always had -CaseSensitive switch).
• Compare-Object:
  • Case-insensitive by default, but does have a -CaseSensitive switch.
  • Input of type [char] is unexpectedly case-sensitive by default; string input is case-insensitive by default.
  • Compare-Object with [char] instances is unexpectedly case-sensitive by default PowerShell/PowerShell#17758

    Compare-object -ReferenceObject a            -DifferenceObject A            # Equal (no output)
    Compare-object -ReferenceObject ([char] 'a') -DifferenceObject ([char] 'A') # Different (output)

• ConvertFrom-Json -AsHashtable:
  • -AsHashtable was added in PS v6. In PS v7.3, a change was made to treat JSON keys as case-sensitive when this parameter is specified.
    • With the parameter, an object of type Management.Automation.OrderedHashtable is emitted, which has case-sensitive keys.
    • Without the parameter, JSON keys are treated as case-insensitive. Output is a custom object; last case-insensitive key wins.
  • Case insensitive ConvertFrom-Json -AsHashtable  PowerShell/PowerShell#19928
• Group-Object:
  • Case-insensitive by default, but does have a -CaseSensitive switch.
    • In Windows PowerShell v5.1, -CaseSensitive and -AsHashtable produces a case-insensitive hash table. Duplicate keys result in an error.
    • In PowerShell v7+, -CaseSensitive and -AsHashtable produces a case-sensitive hash table. No error occurs with duplicate keys.
    • Group-Object - Use Case-Sensitive Hashtable for -CaseSensitive -AsHashtable PowerShell/PowerShell#11030

      [pscustomobject] @{ Foo = 'Bar' }, [pscustomobject] @{ Foo = 'bar' } |
          Group-Object -Property Foo -CaseSensitive -AsHashtable
      # Win PS: The objects grouped by this property cannot be expanded because there is a key duplication.
      # PS 7+:  OK.

• Select-String:
  • Case-insensitive by default, but does have a -CaseSensitive switch.
• Get-Command and command discovery/invocation:
  • On case-sensitive file systems, ExternalScript and Application command type discovery/invocation is case-sensitive.
  • Get-Command wildcard matching with these types is also case-sensitive.
  • All other CommandTypes are case-insensitive (functions, cmdlets, etc).
• Comparison operators:
  • By default, operators are case-insensitive.
  • -c* operators are case-sensitive.
  • -i* operators are case-insensitive.
  • -replace/-ireplace is case-insensitive by default, except with named capture groups, which are case-sensitive.

    'Bar' -replace '(?<a>a)', '${a}${a}'
    # Baar
    
    'Bar' -replace '(?<a>a)', '${A}${A}'
    # B${A}${A}r

• -split operator:
  • -split and -isplit are case-insensitive.
  • -csplit is case-sensitive, unless the IgnoreCase option is specified.

    'Bar' -csplit 'A', 0
    # Bar
    
    'Bar' -csplit 'A', 0, 'IgnoreCase'
    # B
    # r

• Tab completion:
  • On case-sensitive file systems, tab completion and globbing are both case-insensitive.
  • E.g., TabExpansion2 -inputScript ./foo will complete to ./Foo.txt on Linux.
  • Enable case-insensitive tab completion for files and folders on case-sensitive filesystem PowerShell/PowerShell#8128
• using statement:
  • On case-sensitive file systems, using module and using assembly are case-sensitive when a path is specified.
  • using module with just a module name is case-insensitive.
  • using namespace is always case-insensitive.
• Special characters:
  • Escape sequences like `n are case-sensitive.

Areas of PowerShell which are guaranteed to be case-insensitive on all systems:

• Non-dictionary member-access
• Operator names
• Non-ExternalScript/Application command discovery
• Parameter names
• Variable names/Get-Variable/Variable:
• Keywords
• using namespace statements
• Type literals
• #Requires
• Comment-based help
• PS provider names
• PS drive names
• Scope modifiers

Suggested Fix

• Be explicitly clear that on systems with a case-sensitive file system, the FileSystem and Environment PS providers are case-sensitive, except with wildcard matching/globbing.
• Call out areas of PowerShell which are either case-sensitive by default on all systems or are inconsistent/conditional with case handling. See details above.
• Add additional examples in which case-insensitivity is guaranteed on all systems.
• Perhaps document exactly how case-sensitivity is handled in all of the main serialization/deserialization formats (CSV, JSON, XML, CLIXML) and potential workarounds with problematic input.

[sdwheeler]

• Input of type [char] is unexpectedly case-sensitive by default; string input is case-insensitive by default.

I would argue that this is not unexpected since [char]'a' is not a string, it's a value type. But, it's still confusing to people so it's worth calling out.

[sdwheeler]

• Perhaps document exactly how case-sensitivity is handled in all of the main serialization/deserialization formats (CSV, JSON, XML, CLIXML) and potential workarounds with problematic input.

Do you have some examples you can share?

[surfingoldelephant]

• Input of type [char] is unexpectedly case-sensitive by default; string input is case-insensitive by default.

I would argue that this is not unexpected since [char]'a' is not a string, it's a value type. But, it's still confusing to people so it's worth calling out.

I think the main confusion stems from the ability to opt-in to case-sensitivity. The existence of -CaseSensitive implies Compare-Object is case-insensitive by default, so I don't think it's unreasonable to expect a case-insensitive comparison here, even if we are dealing with [char] instead of [string].

Also worth noting that PowerShell hardcodes -eq comparisons involving [char] as case-insensitive (by calling ToUpperInvariant() on each [char] before comparing). And again, provides the ability to opt-in to case-sensitivity with -ceq.

([char] 'a') -eq ([char] 'A') # True

[surfingoldelephant]

• Perhaps document exactly how case-sensitivity is handled in all of the main serialization/deserialization formats (CSV, JSON, XML, CLIXML) and potential workarounds with problematic input.

Do you have some examples you can share?

I see this kind of issue most often with CSV, where the header contains duplicates that are either identical or differ by case.

@'
H1,H2,h1
V1,V2,V3
'@ | ConvertFrom-Csv

# Error: The member "h1" is already present.

The simplest workaround is to use -Header and hardcode unique values. However, quite often the original values need to be retained (with the duplicates appended/prepended with something to make them unique). Here's one workaround to the issue, although granted it might not be suitable for documentation purposes.

With JSON, the spec permits keys that differ by case. However, the default ConvertFrom-Json behavior is to produce an error.

'{"Foo": "Bar", "foo": "bar"}' | ConvertFrom-Json

# Cannot convert the JSON string because it contains keys with different casing.
# Please use the -AsHashTable switch instead.
# The key that was attempted to be added to the existing key 'Foo' was 'foo'.

The PS v7.3+ workaround is to use -AsHashtable.
Unrelated side note: Even the error uses the wrong case for the switch name (should be -AsHashtable in the error message).

For PS v5.1, the workarounds are probably too convoluted to include in documentation and users should seek out their own solution (or delegate to a third-party library like Newtonsoft's Json.NET).

Duplicates (case-aside) are handled fine in XML/CLIXML serialization/deserialization.

$h = [hashtable]::new() # Case-sensitive
$h['Foo'] = 'Bar'; $h['foo'] = 'bar'

$h | ConvertTo-CliXml | ConvertFrom-CliXml # OK

# Name                           Value
# ----                           -----
# Foo                            Bar
# foo                            bar

[surfingoldelephant]

@sdwheeler Thanks for reviewing this. I see the following edit you made:

EDIT: The FileSystem and Environment providers are case-sensitive on case-sensitive file systems non-Windows systems.

That isn't quite accurate. For example, on Windows, case-sensitivity can be enabled on a per directory basis.

In which case, FileSystem provider cmdlets behave in a case-sensitive manner despite it being a Windows system.

$dir = New-Item Temp:\CaseTest -ItemType Directory -Force
fsutil.exe file setCaseSensitiveInfo $dir.FullName enable # Elevation required

'foo', 'Foo' | New-Item -Path $dir.FullName -Name { $_ } -Force

Test-Path -LiteralPath "$($dir.FullName)\FOO"
# False

Test-Path -LiteralPath "$($dir.FullName)\Foo"
# True

Convert-Path -LiteralPath "$($dir.FullName)\FOO"
# Convert-Path: Cannot find path '...\AppData\Local\Temp\CaseTest\FOO' because it does not exist.

Convert-Path -LiteralPath "$($dir.FullName)\foo"
# ...\AppData\Local\Temp\CaseTest\foo

On Windows with case-sensitivity enabled, wildcard matching is:

• Case-insensitive in PS v7+.
• Case-sensitive in Windows PowerShell (so yet another inconsistency).

(Get-Item -Path "$($dir.FullName)\FO*").Count 
# PS v7+:      2
# Win PS v5.1: 0

(Convert-Path -Path "$($dir.FullName)\fo*").Count 
# PS v7+:      2
# Win PS v5.1: 1