From 1b732966e96a6138a5b6ab169b00ad04bb6782b9 Mon Sep 17 00:00:00 2001
From: Sean Wheeler <sean.wheeler@microsoft.com>
Date: Thu, 2 Jan 2025 17:57:41 -0600
Subject: [PATCH 1/4] Add information about numeric parameter names (#11623)
---
.../About/about_Functions_Advanced.md | 37 ++++++-----
.../about_Functions_Advanced_Parameters.md | 61 ++++++++++++++++-
.../About/about_Variables.md | 19 +++---
.../About/about_Functions_Advanced.md | 37 ++++++-----
.../about_Functions_Advanced_Parameters.md | 65 +++++++++++++++++--
.../About/about_Variables.md | 19 +++---
.../About/about_Functions_Advanced.md | 38 +++++------
.../about_Functions_Advanced_Parameters.md | 65 +++++++++++++++++--
.../About/about_Variables.md | 19 +++---
9 files changed, 268 insertions(+), 92 deletions(-)
diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md
index 34bb009b26d1..f625a3a28ba0 100644
--- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md
+++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md
@@ -1,7 +1,7 @@
---
description: Introduces advanced functions that are a way to create cmdlets using scripts.
Locale: en-US
-ms.date: 01/20/2023
+ms.date: 01/02/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Functions_Advanced
@@ -14,8 +14,8 @@ Introduces advanced functions that are a way to create cmdlets using scripts.
## Long description
A cmdlet is a single command that participates in the pipeline semantics of
-PowerShell. This includes binary cmdlets, advanced script functions, CDXML, and
-Workflows.
+PowerShell. This includes binary cmdlets, PowerShell advanced script
+functions, CDXML, and Workflows.
Advanced functions allow you create cmdlets that are written as a PowerShell
function. Advanced functions make it easier to create cmdlets without having to
@@ -28,6 +28,12 @@ the Cmdlet attribute that's used in compiled cmdlet classes to identify the
class as a cmdlet. For more information about this attribute, see
[about_Functions_CmdletBindingAttribute][03].
+The parameters of the function are variables declared in the `param()`
+statement. You can use the optional `[Parameter()]` attribute alone or in
+combination with the `[Alias()]` attribute or any of the parameter validation
+attributes. For more information about how to declare parameters, see
+[about_Functions_Advanced_Parameters][02].
+
The following example shows a function that accepts a name and then prints a
greeting using the supplied name. Also notice that this function defines a name
that includes a verb (Send) and noun (Greeting) pair like the verb-noun pair of
@@ -37,36 +43,29 @@ a compiled cmdlet. However, functions aren't required to have a verb-noun name.
function Send-Greeting
{
[CmdletBinding()]
- Param(
+ param(
[Parameter(Mandatory=$true)]
[string] $Name
)
- Process
+ process
{
Write-Host ("Hello " + $Name + "!")
}
}
```
-The parameters of the function are declared using the `Parameter` attribute.
-This attribute can be used alone, or it can be combined with the Alias
-attribute or with several other parameter validation attributes. For more
-information about how to declare parameters (including dynamic parameters that
-are added at runtime), see [about_Functions_Advanced_Parameters][02].
-
-The actual work of the previous function is performed in the `process` block,
-which is equivalent to the **ProcessingRecord** method that's used by compiled
-cmdlets to process the data that's passed to the cmdlet. This block, along with
-the `begin` and `end` blocks, is described in the
-[about_Functions_Advanced_Methods][01] topic.
+This function performs the work in the `process` block, which is equivalent to
+the **ProcessingRecord** method used in compiled cmdlets. The `process` block
+and the other named blocks are described in
+[about_Functions_Advanced_Methods][01].
Advanced functions differ from compiled cmdlets in the following ways:
- Advanced function parameter binding doesn't throw an exception when an array
of strings is bound to a **Boolean** parameter.
-- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass named
- parameters.
+- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass
+ named parameters.
- Advanced functions can't be used in transactions.
## See also
@@ -76,6 +75,7 @@ Advanced functions differ from compiled cmdlets in the following ways:
- [about_Functions_Advanced_Parameters][02]
- [about_Functions_CmdletBindingAttribute][03]
- [about_Functions_OutputTypeAttribute][04]
+- [about_Variables][06]
<!-- link references -->
[01]: about_Functions_Advanced_Methods.md
@@ -83,3 +83,4 @@ Advanced functions differ from compiled cmdlets in the following ways:
[03]: about_Functions_CmdletBindingAttribute.md
[04]: about_Functions_OutputTypeAttribute.md
[05]: about_Functions.md
+[06]: about_Variables.md
diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md
index 0111ad11cdbb..a62d8c6dab9b 100644
--- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md
+++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md
@@ -1,7 +1,7 @@
---
description: Explains how to add parameters to advanced functions.
Locale: en-US
-ms.date: 07/02/2024
+ms.date: 01/02/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Functions_Advanced_Parameters
@@ -28,6 +28,60 @@ the parameters in a command. Splatting is valid on simple and advanced
functions. For more information, see [about_Functions][14] and
[about_Splatting][17].
+## Parameter declaration
+
+Parameters are variables declared in the `param()` statement of a function or
+script block. You can use the optional `[Parameter()]` attribute alone or in
+combination with the `[Alias()]` attribute or any of the parameter validation
+attributes.
+
+Parameter names follow the rules for variable names. Parameter names consist of
+decimal digits, alphabetic characters, and underscores. For a complete list of
+naming rules, see [about_Variables][20].
+
+> [!IMPORTANT]
+> It's possible to name a parameter using only decimal digits. Using numeric
+> parameter names isn't recommended because it can lead to confusion with
+> positional parameters.
+
+Consider the following example:
+
+```powershell
+function TestFunction {
+ param (
+ [switch] $100,
+ [string] $200
+ )
+
+ "100: $100"
+ "200: $200"
+}
+```
+
+If you try to use the parameters, PowerShell interprets them as negative
+numbers passed as positional parameter.
+
+```powershell
+PS> TestFunction -100 -200 Hello
+100: False
+200: -100
+$args: -200 Hello
+```
+
+The output shows that PowerShell has bound the value `-100` to the `$200`
+parameter variable. The remaining positional values are bound to `$args`. To
+work around the issue, you can use splatting to pass the parameter values.
+
+```powershell
+PS> $ht = @{100 = $true; 200 = 'Hello'}
+PS> TestFunction @ht
+100: True
+200: Hello
+$args:
+```
+
+For more information, see [about_Splatting][17].
+
## Type conversion of parameter values
When you supply strings as arguments to parameters that expect a different
@@ -104,6 +158,8 @@ At line:13 char:15
+ FullyQualifiedErrorId : ParameterArgumentTransformationError,Get-Date_Func
```
+For more information, see [about_Type_Conversion](about_Type_Conversion.md).
+
## Static parameters
Static parameters are parameters that are always available in the function.
@@ -1177,7 +1233,7 @@ True
- [about_Functions_OutputTypeAttribute][13]
<!-- link references -->
-[01]: ./about_comment_based_help.md
+[01]: about_comment_based_help.md
[02]: /dotnet/api/system.management.automation.runtimedefinedparameter
[05]: about_Automatic_Variables.md
[06]: about_CommonParameters.md
@@ -1192,3 +1248,4 @@ True
[17]: about_Splatting.md
[18]: about_Tab_Expansion.md
[19]: about_Wildcards.md
+[20]: about_Variables.md
diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Variables.md
index 215daaac44f5..800311d7c31f 100644
--- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Variables.md
+++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Variables.md
@@ -1,7 +1,7 @@
---
description: Describes how variables store values that can be used in PowerShell.
Locale: en-US
-ms.date: 03/07/2024
+ms.date: 01/02/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_variables?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Variables
@@ -321,15 +321,16 @@ Alphanumeric variable names can contain these characters:
- Underscore (`_`) character.
- Question mark (`?`) character.
-The following list contains the Unicode category descriptions. For more
-information, see [UnicodeCategory][17].
+The following list contains the .NET names of the Unicode categories with a
+description. For more information, see [UnicodeCategory][17].
-- **Lu** - UppercaseLetter
-- **Ll** - LowercaseLetter
-- **Lt** - TitlecaseLetter
-- **Lm** - ModifierLetter
-- **Lo** - OtherLetter
-- **Nd** - DecimalDigitNumber
+- **Lu** - UppercaseLetter - an uppercase letter
+- **Ll** - LowercaseLetter - a lowercase letter
+- **Lt** - TitlecaseLetter - a digraph encoded as a single character with the
+ first part uppercase
+- **Lm** - ModifierLetter - a modifier letter
+- **Lo** - OtherLetter - other letters, including syllables and ideographs
+- **Nd** - DecimalDigitNumber - a decimal digit
To create or display a variable name that includes spaces or special
characters, enclose the variable name with the curly braces (`{}`) characters.
diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md
index eb7edd7fe86b..8f249b18b170 100644
--- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md
+++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md
@@ -1,7 +1,7 @@
---
description: Introduces advanced functions that are a way to create cmdlets using scripts.
Locale: en-US
-ms.date: 01/20/2023
+ms.date: 01/02/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Functions_Advanced
@@ -14,8 +14,8 @@ Introduces advanced functions that are a way to create cmdlets using scripts.
## Long description
A cmdlet is a single command that participates in the pipeline semantics of
-PowerShell. This includes binary cmdlets, advanced script functions, CDXML, and
-Workflows.
+PowerShell. This includes binary cmdlets, PowerShell advanced functions, and
+CDXML cmdlets.
Advanced functions allow you create cmdlets that are written as a PowerShell
function. Advanced functions make it easier to create cmdlets without having to
@@ -28,6 +28,12 @@ the Cmdlet attribute that's used in compiled cmdlet classes to identify the
class as a cmdlet. For more information about this attribute, see
[about_Functions_CmdletBindingAttribute][03].
+The parameters of the function are variables declared in the `param()`
+statement. You can use the optional `[Parameter()]` attribute alone or in
+combination with the `[Alias()]` attribute or any of the parameter validation
+attributes. For more information about how to declare parameters, see
+[about_Functions_Advanced_Parameters][02].
+
The following example shows a function that accepts a name and then prints a
greeting using the supplied name. Also notice that this function defines a name
that includes a verb (Send) and noun (Greeting) pair like the verb-noun pair of
@@ -37,36 +43,29 @@ a compiled cmdlet. However, functions aren't required to have a verb-noun name.
function Send-Greeting
{
[CmdletBinding()]
- Param(
+ param(
[Parameter(Mandatory=$true)]
[string] $Name
)
- Process
+ process
{
Write-Host ("Hello " + $Name + "!")
}
}
```
-The parameters of the function are declared using the `Parameter` attribute.
-This attribute can be used alone, or it can be combined with the Alias
-attribute or with several other parameter validation attributes. For more
-information about how to declare parameters (including dynamic parameters that
-are added at runtime), see [about_Functions_Advanced_Parameters][02].
-
-The actual work of the previous function is performed in the `process` block,
-which is equivalent to the **ProcessingRecord** method that's used by compiled
-cmdlets to process the data that's passed to the cmdlet. This block, along with
-the `begin` and `end` blocks, is described in the
-[about_Functions_Advanced_Methods][01] topic.
+This function performs the work in the `process` block, which is equivalent to
+the **ProcessingRecord** method used in compiled cmdlets. The `process` block
+and the other named blocks are described in
+[about_Functions_Advanced_Methods][01].
Advanced functions differ from compiled cmdlets in the following ways:
- Advanced function parameter binding doesn't throw an exception when an array
of strings is bound to a **Boolean** parameter.
-- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass named
- parameters.
+- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass
+ named parameters.
- Advanced functions can't be used in transactions.
## See also
@@ -76,6 +75,7 @@ Advanced functions differ from compiled cmdlets in the following ways:
- [about_Functions_Advanced_Parameters][02]
- [about_Functions_CmdletBindingAttribute][03]
- [about_Functions_OutputTypeAttribute][04]
+- [about_Variables][06]
<!-- link references -->
[01]: about_Functions_Advanced_Methods.md
@@ -83,3 +83,4 @@ Advanced functions differ from compiled cmdlets in the following ways:
[03]: about_Functions_CmdletBindingAttribute.md
[04]: about_Functions_OutputTypeAttribute.md
[05]: about_Functions.md
+[06]: about_Variables.md
diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md
index d6c3752aead1..1c20e32347b7 100644
--- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md
+++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md
@@ -1,7 +1,7 @@
---
description: Explains how to add parameters to advanced functions.
Locale: en-US
-ms.date: 07/02/2024
+ms.date: 01/02/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Functions_Advanced_Parameters
@@ -28,6 +28,60 @@ the parameters in a command. Splatting is valid on simple and advanced
functions. For more information, see [about_Functions][14] and
[about_Splatting][17].
+## Parameter declaration
+
+Parameters are variables declared in the `param()` statement of a function or
+script block. You can use the optional `[Parameter()]` attribute alone or in
+combination with the `[Alias()]` attribute or any of the parameter validation
+attributes.
+
+Parameter names follow the rules for variable names. Parameter names consist of
+decimal digits, alphabetic characters, and underscores. For a complete list of
+naming rules, see [about_Variables][20].
+
+> [!IMPORTANT]
+> It's possible to name a parameter using only decimal digits. Using numeric
+> parameter names isn't recommended because it can lead to confusion with
+> positional parameters.
+
+Consider the following example:
+
+```powershell
+function TestFunction {
+ param (
+ [switch] $100,
+ [string] $200
+ )
+
+ "100: $100"
+ "200: $200"
+}
+```
+
+If you try to use the parameters, PowerShell interprets them as negative
+numbers passed as positional parameter.
+
+```powershell
+PS> TestFunction -100 -200 Hello
+100: False
+200: -100
+$args: -200 Hello
+```
+
+The output shows that PowerShell has bound the value `-100` to the `$200`
+parameter variable. The remaining positional values are bound to `$args`. To
+work around the issue, you can use splatting to pass the parameter values.
+
+```powershell
+PS> $ht = @{100 = $true; 200 = 'Hello'}
+PS> TestFunction @ht
+100: True
+200: Hello
+$args:
+```
+
+For more information, see [about_Splatting][17].
+
## Type conversion of parameter values
When you supply strings as arguments to parameters that expect a different
@@ -99,6 +153,8 @@ Cannot convert value "19-06-2018" to type "System.DateTime". Error:
"String '19-06-2018' was not recognized as a valid DateTime."
```
+For more information, see [about_Type_Conversion](about_Type_Conversion.md).
+
## Static parameters
Static parameters are parameters that are always available in the function.
@@ -1258,10 +1314,10 @@ True
### ValidateTrustedData validation attribute
-This attribute was added in PowerShell 6.1.1.
+This attribute is used internally by PowerShell itself and isn't intended for
+external usage.
-At this time, the attribute is used internally by PowerShell itself and isn't
-intended for external usage.
+This attribute was added in PowerShell 6.1.1.
## See also
@@ -1292,3 +1348,4 @@ intended for external usage.
[17]: about_Splatting.md
[18]: about_Tab_Expansion.md
[19]: about_Wildcards.md
+[20]: about_Variables.md
diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Variables.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Variables.md
index 5b0fffe75ab2..d773c2f08341 100644
--- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Variables.md
+++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Variables.md
@@ -1,7 +1,7 @@
---
description: Describes how variables store values that can be used in PowerShell.
Locale: en-US
-ms.date: 03/07/2024
+ms.date: 01/02/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_variables?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Variables
@@ -321,15 +321,16 @@ Alphanumeric variable names can contain these characters:
- Underscore (`_`) character.
- Question mark (`?`) character.
-The following list contains the Unicode category descriptions. For more
-information, see [UnicodeCategory][17].
+The following list contains the .NET names of the Unicode categories with a
+description. For more information, see [UnicodeCategory][17].
-- **Lu** - UppercaseLetter
-- **Ll** - LowercaseLetter
-- **Lt** - TitlecaseLetter
-- **Lm** - ModifierLetter
-- **Lo** - OtherLetter
-- **Nd** - DecimalDigitNumber
+- **Lu** - UppercaseLetter - an uppercase letter
+- **Ll** - LowercaseLetter - a lowercase letter
+- **Lt** - TitlecaseLetter - a digraph encoded as a single character with the
+ first part uppercase
+- **Lm** - ModifierLetter - a modifier letter
+- **Lo** - OtherLetter - other letters, including syllables and ideographs
+- **Nd** - DecimalDigitNumber - a decimal digit
To create or display a variable name that includes spaces or special
characters, enclose the variable name with the curly braces (`{}`) characters.
diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md
index fc7ee859fe77..6e3bd6324339 100644
--- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md
+++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md
@@ -1,7 +1,7 @@
---
description: Introduces advanced functions that are a way to create cmdlets using scripts.
Locale: en-US
-ms.date: 01/20/2023
+ms.date: 01/02/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced?view=powershell-7.5&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Functions_Advanced
@@ -9,14 +9,13 @@ title: about_Functions_Advanced
# about_Functions_Advanced
## Short description
-
Introduces advanced functions that are a way to create cmdlets using scripts.
## Long description
A cmdlet is a single command that participates in the pipeline semantics of
-PowerShell. This includes binary cmdlets, advanced script functions, CDXML, and
-Workflows.
+PowerShell. This includes binary cmdlets, PowerShell advanced functions, and
+CDXML cmdlets.
Advanced functions allow you create cmdlets that are written as a PowerShell
function. Advanced functions make it easier to create cmdlets without having to
@@ -29,6 +28,12 @@ the Cmdlet attribute that's used in compiled cmdlet classes to identify the
class as a cmdlet. For more information about this attribute, see
[about_Functions_CmdletBindingAttribute][03].
+The parameters of the function are variables declared in the `param()`
+statement. You can use the optional `[Parameter()]` attribute alone or in
+combination with the `[Alias()]` attribute or any of the parameter validation
+attributes. For more information about how to declare parameters, see
+[about_Functions_Advanced_Parameters][02].
+
The following example shows a function that accepts a name and then prints a
greeting using the supplied name. Also notice that this function defines a name
that includes a verb (Send) and noun (Greeting) pair like the verb-noun pair of
@@ -38,36 +43,29 @@ a compiled cmdlet. However, functions aren't required to have a verb-noun name.
function Send-Greeting
{
[CmdletBinding()]
- Param(
+ param(
[Parameter(Mandatory=$true)]
[string] $Name
)
- Process
+ process
{
Write-Host ("Hello " + $Name + "!")
}
}
```
-The parameters of the function are declared using the `Parameter` attribute.
-This attribute can be used alone, or it can be combined with the Alias
-attribute or with several other parameter validation attributes. For more
-information about how to declare parameters (including dynamic parameters that
-are added at runtime), see [about_Functions_Advanced_Parameters][02].
-
-The actual work of the previous function is performed in the `process` block,
-which is equivalent to the **ProcessingRecord** method that's used by compiled
-cmdlets to process the data that's passed to the cmdlet. This block, along with
-the `begin` and `end` blocks, is described in the
-[about_Functions_Advanced_Methods][01] topic.
+This function performs the work in the `process` block, which is equivalent to
+the **ProcessingRecord** method used in compiled cmdlets. The `process` block
+and the other named blocks are described in
+[about_Functions_Advanced_Methods][01].
Advanced functions differ from compiled cmdlets in the following ways:
- Advanced function parameter binding doesn't throw an exception when an array
of strings is bound to a **Boolean** parameter.
-- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass named
- parameters.
+- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass
+ named parameters.
- Advanced functions can't be used in transactions.
## See also
@@ -77,6 +75,7 @@ Advanced functions differ from compiled cmdlets in the following ways:
- [about_Functions_Advanced_Parameters][02]
- [about_Functions_CmdletBindingAttribute][03]
- [about_Functions_OutputTypeAttribute][04]
+- [about_Variables][06]
<!-- link references -->
[01]: about_Functions_Advanced_Methods.md
@@ -84,3 +83,4 @@ Advanced functions differ from compiled cmdlets in the following ways:
[03]: about_Functions_CmdletBindingAttribute.md
[04]: about_Functions_OutputTypeAttribute.md
[05]: about_Functions.md
+[06]: about_Variables.md
diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md
index 73e3dc742f4f..686ec5efe2cb 100644
--- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md
+++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md
@@ -1,7 +1,7 @@
---
description: Explains how to add parameters to advanced functions.
Locale: en-US
-ms.date: 07/02/2024
+ms.date: 01/02/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7.5&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Functions_Advanced_Parameters
@@ -28,6 +28,60 @@ the parameters in a command. Splatting is valid on simple and advanced
functions. For more information, see [about_Functions][14] and
[about_Splatting][17].
+## Parameter declaration
+
+Parameters are variables declared in the `param()` statement of a function or
+script block. You can use the optional `[Parameter()]` attribute alone or in
+combination with the `[Alias()]` attribute or any of the parameter validation
+attributes.
+
+Parameter names follow the rules for variable names. Parameter names consist of
+decimal digits, alphabetic characters, and underscores. For a complete list of
+naming rules, see [about_Variables][20].
+
+> [!IMPORTANT]
+> It's possible to name a parameter using only decimal digits. Using numeric
+> parameter names isn't recommended because it can lead to confusion with
+> positional parameters.
+
+Consider the following example:
+
+```powershell
+function TestFunction {
+ param (
+ [switch] $100,
+ [string] $200
+ )
+
+ "100: $100"
+ "200: $200"
+}
+```
+
+If you try to use the parameters, PowerShell interprets them as negative
+numbers passed as positional parameter.
+
+```powershell
+PS> TestFunction -100 -200 Hello
+100: False
+200: -100
+$args: -200 Hello
+```
+
+The output shows that PowerShell has bound the value `-100` to the `$200`
+parameter variable. The remaining positional values are bound to `$args`. To
+work around the issue, you can use splatting to pass the parameter values.
+
+```powershell
+PS> $ht = @{100 = $true; 200 = 'Hello'}
+PS> TestFunction @ht
+100: True
+200: Hello
+$args:
+```
+
+For more information, see [about_Splatting][17].
+
## Type conversion of parameter values
When you supply strings as arguments to parameters that expect a different
@@ -99,6 +153,8 @@ Cannot convert value "19-06-2018" to type "System.DateTime". Error:
"String '19-06-2018' was not recognized as a valid DateTime."
```
+For more information, see [about_Type_Conversion](about_Type_Conversion.md).
+
## Static parameters
Static parameters are parameters that are always available in the function.
@@ -1258,10 +1314,10 @@ True
### ValidateTrustedData validation attribute
-This attribute was added in PowerShell 6.1.1.
+This attribute is used internally by PowerShell itself and isn't intended for
+external usage.
-At this time, the attribute is used internally by PowerShell itself and isn't
-intended for external usage.
+This attribute was added in PowerShell 6.1.1.
## See also
@@ -1292,3 +1348,4 @@ intended for external usage.
[17]: about_Splatting.md
[18]: about_Tab_Expansion.md
[19]: about_Wildcards.md
+[20]: about_Variables.md
diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Variables.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Variables.md
index 626542cab678..9ca751a89003 100644
--- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Variables.md
+++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Variables.md
@@ -1,7 +1,7 @@
---
description: Describes how variables store values that can be used in PowerShell.
Locale: en-US
-ms.date: 03/07/2024
+ms.date: 01/02/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_variables?view=powershell-7.5&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Variables
@@ -321,15 +321,16 @@ Alphanumeric variable names can contain these characters:
- Underscore (`_`) character.
- Question mark (`?`) character.
-The following list contains the Unicode category descriptions. For more
-information, see [UnicodeCategory][17].
+The following list contains the .NET names of the Unicode categories with a
+description. For more information, see [UnicodeCategory][17].
-- **Lu** - UppercaseLetter
-- **Ll** - LowercaseLetter
-- **Lt** - TitlecaseLetter
-- **Lm** - ModifierLetter
-- **Lo** - OtherLetter
-- **Nd** - DecimalDigitNumber
+- **Lu** - UppercaseLetter - an uppercase letter
+- **Ll** - LowercaseLetter - a lowercase letter
+- **Lt** - TitlecaseLetter - a digraph encoded as a single character with the
+ first part uppercase
+- **Lm** - ModifierLetter - a modifier letter
+- **Lo** - OtherLetter - other letters, including syllables and ideographs
+- **Nd** - DecimalDigitNumber - a decimal digit
To create or display a variable name that includes spaces or special
characters, enclose the variable name with the curly braces (`{}`) characters.
From 98f251849d1f57b72e184c0d1eac161a6dd747f8 Mon Sep 17 00:00:00 2001
From: Sean Wheeler <sean.wheeler@microsoft.com>
Date: Fri, 3 Jan 2025 10:13:41 -0600
Subject: [PATCH 2/4] Update repository's meta files (#11624)
* Update repository's meta files
* Update contributor guide to list meta files policy
* more edits
---
.github/ISSUE_TEMPLATE/01-article.yml | 3 +-
CODE_OF_CONDUCT.md | 46 ++++++++++++++++---
CONTRIBUTING.md | 2 +-
README.md | 33 ++++++-------
.../contributing/get-started-writing.md | 41 +++++++++++++++--
5 files changed, 92 insertions(+), 33 deletions(-)
diff --git a/.github/ISSUE_TEMPLATE/01-article.yml b/.github/ISSUE_TEMPLATE/01-article.yml
index 7e8f264b2501..8d2fdf659937 100644
--- a/.github/ISSUE_TEMPLATE/01-article.yml
+++ b/.github/ISSUE_TEMPLATE/01-article.yml
@@ -33,9 +33,8 @@ body:
multiple: true
options:
- "5.1"
- - "7.2"
- - "7.3"
- "7.4"
+ - "7.5"
- type: textarea
id: summary
validations:
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 686e5e7a090b..db5367ad0ae2 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -1,10 +1,44 @@
# Microsoft Open Source Code of Conduct
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+This project has adopted the [Microsoft Open Source Code of Conduct][02].
-Resources:
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and
+healthy community.
-- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
-- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
-- Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns
-- Employees can reach out at [aka.ms/opensource/moderation-support](https://aka.ms/opensource/moderation-support)
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the
+ experience
+- Focusing on what's best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- Disruptive behavior
+ - Submitting spam comments, issues, or pull requests
+ - Defacing or vandalizing the project, repository, content, or documentation
+ - Intentionally introducing security vulnerabilities
+- Disrespectful behavior
+ - Trolling, insulting or derogatory comments, and personal or political attacks
+ - Public or private harassment
+ - Publishing others' private information, such as a physical or email address, without their
+ explicit permission
+ - The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Other conduct that could reasonably be considered inappropriate in a professional setting
+
+## Resources
+
+- [Microsoft Open Source Code of Conduct][02]
+- [Microsoft Code of Conduct FAQ][03]
+- Contact [opencode@microsoft.com][04] with questions or concerns
+- Employees can reach out at [aka.ms/opensource/moderation-support][01]
+
+<!-- link references -->
+[01]: https://aka.ms/opensource/moderation-support
+[02]: https://opensource.microsoft.com/codeofconduct/
+[03]: https://opensource.microsoft.com/codeofconduct/faq/
+[04]: mailto:opencode@microsoft.com
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bc570ba2c7c2..88fc0a1d6e73 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,4 +3,4 @@
Thank you for your interest in contributing to quality documentations.
As an open source project, we welcome input and updates from the community.
-Please see our Contributor's Guide at https://aka.ms/PSDocsContributor.
+Please see our Contributor's Guide at <https://aka.ms/PSDocsContributor>
diff --git a/README.md b/README.md
index 7ec7fb2c8871..4773a72a1a0d 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
---
-ms.date: 11/02/2024
+ms.date: 01/03/2025
---
# PowerShell Documentation
@@ -9,15 +9,6 @@ Welcome to the PowerShell-Docs repository, the home of the official PowerShell d
This project has adopted the [Microsoft Open Source Code of Conduct][04].
-## Build Status
-
-[live-badge]: https://powershell.visualstudio.com/PowerShell-Docs/_apis/build/status/PowerShell-Docs-CI?branchName=live
-[main-badge]: https://powershell.visualstudio.com/PowerShell-Docs/_apis/build/status/PowerShell-Docs-CI?branchName=main
-
-| live branch | main branch |
-| :---------------------------- | :---------------------------- |
-| [![live-badge][]][live-badge] | [![main-badge][]][main-badge] |
-
## PowerShell Updatable Help (CabGen) CI Build Status
[![Build Status][cabgen-status]][cabgen-log]
@@ -29,14 +20,13 @@ This project has adopted the [Microsoft Open Source Code of Conduct][04].
The following list describes the main folders in this repository.
+- `.devcontainer` - configuration files for the VS Code Remote - Containers extension
- `.github` - contains configuration settings used by GitHub for this repository
-- `.vscode` - contains configuration settings and recommended extensions for Visual Studio Code (VS
- Code)
+- `.vscode` - contains configuration settings and recommended extensions for VS Code
- `assets` - contains downloadable files linked in the documentation
- `redir` - contain redirection mapping files
-- `reference` - contains the documentation published to
- [learn.microsoft.com][01]. This includes both
- reference and conceptual content.
+- `reference` - contains the documentation published to [learn.microsoft.com][01]. This includes
+ both reference and conceptual content.
- `5.1` - contains the cmdlet reference and about topics for PowerShell 5.1
- `7.4` - contains the cmdlet reference and about topics for PowerShell 7.4
- `7.5` - contains the cmdlet reference and about topics for PowerShell 7.5
@@ -52,9 +42,10 @@ The following list describes the main folders in this repository.
- `tests` - contains the Pester tests used by the build system
- `tools` - contains other tools used by the build system
-> NOTE: The reference content (in the numbered folders) is used to create the webpages on the Docs
-> site as well as the updateable help used by PowerShell. The articles in the `docs-conceptual`
-> folder are only published to the Docs website.
+> [!NOTE]
+> The reference content (in the numbered folders) is used to create the webpages on the Docs site as
+> well as the updateable help used by PowerShell. The articles in the `docs-conceptual` folder are
+> only published to the Docs website.
## Contributing
@@ -69,11 +60,13 @@ consistent across versions.
## Licenses
-There are two license files for this project. The MIT License applies to the code contained in this
-repo. The Creative Commons license applies to the documentation.
+There are two license files for this project. The [MIT License][05] applies to the code contained in
+this repo. The [Creative Commons license][06] applies to the documentation.
<!-- link references -->
[01]: https://learn.microsoft.com/powershell/scripting/
[02]: https://aka.ms/PSDocsContributor
[03]: https://cla.microsoft.com/
[04]: CODE_OF_CONDUCT.md
+[05]: LICENSE-CODE.md
+[06]: LICENSE.md
diff --git a/reference/docs-conceptual/community/contributing/get-started-writing.md b/reference/docs-conceptual/community/contributing/get-started-writing.md
index b44d06839793..4fd2d09bbd6d 100644
--- a/reference/docs-conceptual/community/contributing/get-started-writing.md
+++ b/reference/docs-conceptual/community/contributing/get-started-writing.md
@@ -1,6 +1,6 @@
---
description: This article is an overview of how to get started as a contributor to the PowerShell documentation.
-ms.date: 07/26/2022
+ms.date: 01/03/2025
title: Get started contributing to PowerShell documentation
---
# Get started contributing to PowerShell documentation
@@ -9,13 +9,16 @@ This article is an overview of how to get started as a contributor to the PowerS
## PowerShell-Docs structure
-The [PowerShell-Docs repository][1] is divided into two groups of content: reference and
-conceptual.
+There are three categories of content in the [PowerShell-Docs][1] repository:
+
+- reference content
+- conceptual content
+- metadata and configuration files
### Reference content
The reference content is the PowerShell cmdlet reference for the cmdlets that ship in PowerShell.
-The cmdlet [reference][2] is collected in versioned folders (like 5.1, 7.0, and 7.2), which contain
+The cmdlet [reference][2] is collected in versioned folders (like 5.1, 7.4, and 7.5), which contain
reference for the modules that ship with PowerShell. This content is also used to create the help
information displayed by the `Get-Help` cmdlet.
@@ -28,6 +31,36 @@ version of PowerShell.
> Anytime a conceptual article is added, removed, or renamed, the TOC must be updated and deleted or
> renamed files must be redirected.
+### Metadata files
+
+This project contains several types of metadata files. The metadata files control the behavior of
+our build tools and the publishing system. Only PowerShell-Docs maintainers and approved
+contributors are allowed to change these files. If you think that a meta file should be changed,
+open an issue to discuss the needed changes.
+
+Meta files in the root of the repository
+
+- `.*` - configuration files in the root of the repository
+- `*.md` - Project documentation in the root of the repository
+- `*.yml` - Project documentation in the root of the repository
+- `.devcontainer/*` - devcontainer configuration files
+- `.github/**/*` - GitHub templates, actions, and other meta files
+- `.vscode/**/*` - VS Code extension configurations
+- `assets/*` - contains downloadable files linked in the documentation
+- `redir/*` - contain redirection mapping files
+- `tests/*` - test tools used by the build system
+- `tools/*` - other tools used by the build system
+
+Meta files in the documentation set
+
+- `reference/**/*.json` - docset configuration files
+- `reference/**/*.yml` - TOC and other structured content files
+- `reference/bread/*` - breadcrumb navigation configuration
+- `reference/includes/*` - markdown include files
+- `reference/mapping/*` - version mapping configuration
+- `reference/**/media/**` - image files used in documentation
+- `reference/module/*` - Module Browser page configuration
+
## Creating new articles
A GitHub issue must be created for any new document you want to contribute. Check for existing
From 059ce049a7dd73dadbd77179ab3fde679185592a Mon Sep 17 00:00:00 2001
From: Sean Wheeler <sean.wheeler@microsoft.com>
Date: Fri, 3 Jan 2025 13:46:15 -0600
Subject: [PATCH 3/4] Clarify facts about intrinsic properties Count and Length
(#11626)
---
.../About/about_Arrays.md | 38 ++++--
.../About/about_Intrinsic_Members.md | 13 +-
.../About/about_Properties.md | 113 +++++++--------
.../About/about_Arrays.md | 40 ++++--
.../About/about_Intrinsic_Members.md | 13 +-
.../About/about_Properties.md | 129 ++++++++----------
.../About/about_Arrays.md | 39 ++++--
.../About/about_Intrinsic_Members.md | 13 +-
.../About/about_Properties.md | 117 +++++++---------
9 files changed, 276 insertions(+), 239 deletions(-)
diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md
index 3229c0dc5cbd..6f67cef704f0 100644
--- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md
+++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md
@@ -1,7 +1,7 @@
---
description: Describes arrays, which are data structures designed to store collections of items.
Locale: en-US
-ms.date: 03/07/2024
+ms.date: 01/03/2025
no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple]
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
@@ -10,6 +10,7 @@ title: about_Arrays
# about_Arrays
## Short description
+
Describes arrays, which are data structures designed to store collections of
items.
@@ -341,9 +342,25 @@ while($i -lt 4) {
### Count or Length or LongLength
-To determine how many items are in an array, use the **Length** property or its
-**Count** alias. **Longlength** is useful if the array contains more than
-2,147,483,647 elements.
+In PowerShell, arrays have three properties that indicate the number of items
+contained in the array.
+
+- **Count** - This property is the most commonly used property to determine the
+ number of items in any collection, not just an array. It's an `[Int32]` type
+ value. In Windows PowerShell 5.1 (and older) **Count** alias property for
+ **Length**.
+
+- **Length** - This property is an `[Int32]` type value. This contains the same
+ value as **Count**.
+
+ > [!NOTE]
+ > While **Count** and **Length** are equivalent for arrays, **Length** can
+ > have a different meaning for other types. For example, **Length** for a
+ > string is the number of characters in the string. But the **Count**
+ > property is always `1`.
+
+- **Longlength** - This property is an `[Int64]` type value. Use this property
+ for arrays containing more than 2,147,483,647 elements.
```powershell
$a = 0..9
@@ -470,7 +487,7 @@ True
In this example, `$intA` is explicitly typed to contain integers.
```powershell
-[int[]] $intA = 1, 2, 3
+[Int[]] $intA = 1, 2, 3
$intA.Clear()
$intA
```
@@ -488,7 +505,7 @@ for each element of the array.
The `ForEach()` method has several overloads that perform different operations.
-```
+```Syntax
ForEach(scriptblock expression)
ForEach(scriptblock expression, object[] arguments)
ForEach(type convertToType)
@@ -884,10 +901,11 @@ faster, especially for large arrays.
## Arrays of zero or one
-Beginning in Windows PowerShell 3.0, a collection of zero or one object has the
-**Count** and **Length** properties. Also, you can index into an array of one
-object. This feature helps you to avoid scripting errors that occur when a
-command that expects a collection gets fewer than two items.
+Beginning in Windows PowerShell 3.0, a scalar types and collection of zero or
+one objects has the **Count** and **Length** properties. Also, you can use
+array index notation to access the value of a singleton scalar object. This
+feature helps you to avoid scripting errors that occur when a command that
+expects a collection gets fewer than two items.
> [!NOTE]
In Windows PowerShell, objects created by casting a **Hashtable** to
diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md
index 68c07f4b0a5d..41bea085e39a 100644
--- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md
+++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md
@@ -1,7 +1,7 @@
---
description: Describes automatic members in all PowerShell objects
Locale: en-US
-ms.date: 01/10/2024
+ms.date: 01/03/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Intrinsic_Members?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Intrinsic_Members
@@ -167,8 +167,15 @@ information on how to use these methods, see [about_Arrays][01].
## Properties
-The **Count** and **Length** properties are available to all PowerShell
-objects, not just collections. These are similar to each other but may work
+Not all scalar type have **Count** or **Length** properties in the base type.
+PowerShell adds the missing property as an intrinsic member for all scalar
+types.
+
+> [!NOTE]
+> Uninitialized variables are implicitly `$null`. `$null` is scalar and has an
+> intrinsic **Count** and **Length** of 0.
+
+While the **Count** and **Length** properties are similar, they may work
differently depending on the data type. For example, the **Length** of a string
is the number of characters in the string. The **Count** property is the number
of instances of the object.
diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Properties.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Properties.md
index 7498cac854df..2a8bda5c9234 100644
--- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Properties.md
+++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Properties.md
@@ -1,7 +1,7 @@
---
description: Describes how to use object properties in PowerShell.
Locale: en-US
-ms.date: 08/21/2023
+ms.date: 01/03/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_properties?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Properties
@@ -9,6 +9,7 @@ title: about_Properties
# about_Properties
## Short description
+
Describes how to use object properties in PowerShell.
## Long description
@@ -32,7 +33,7 @@ it doesn't. A **DirectoryInfo** object, which represents a file system
directory, has a **Parent** property that contains the path to the parent
directory.
-### Object properties
+## Object properties
To get the properties of an object, use the `Get-Member` cmdlet. For example,
to get the properties of a **FileInfo** object, use the `Get-ChildItem` cmdlet
@@ -117,7 +118,7 @@ $a.CreationTime
```
```Output
-Saturday, June 5, 2021 7:07:00 AM
+Wednesday, January 24, 2024 1:18:29 AM
```
You can also use the `Select-Object` and `Format-List` cmdlets to display the
@@ -144,10 +145,10 @@ Mode : -a----
VersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
InternalName: POWERSHELL
OriginalFilename: PowerShell.EXE.MUI
- FileVersion: 10.0.22000.1 (WinBuild.160101.0800)
+ FileVersion: 10.0.22621.1 (WinBuild.160101.0800)
FileDescription: Windows PowerShell
- Product: Microsoft? Windows? Operating System
- ProductVersion: 10.0.22000.1
+ Product: Microsoft® Windows® Operating System
+ ProductVersion: 10.0.22621.1
Debug: False
Patched: False
PreRelease: False
@@ -156,8 +157,8 @@ VersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0
Language: English (United States)
BaseName : powershell
-Target : {C:\Windows\WinSxS\amd64_microsoft-windows-powershell-exe_31bf3856ad364e35_10.0.22000.1_none_bf599c
- 5a06fbb6f4\powershell.exe}
+Target : {C:\Windows\WinSxS\amd64_microsoft-windows-powershell-exe_31bf3856ad364e35_10.0.22621.3085_none_492
+ e8ee57da24e0e\powershell.exe}
LinkType : HardLink
Name : powershell.exe
Length : 450560
@@ -167,20 +168,20 @@ IsReadOnly : False
Exists : True
FullName : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Extension : .exe
-CreationTime : 6/5/2021 7:07:00 AM
-CreationTimeUtc : 6/5/2021 12:07:00 PM
-LastAccessTime : 7/18/2022 12:16:17 PM
-LastAccessTimeUtc : 7/18/2022 5:16:17 PM
-LastWriteTime : 6/5/2021 7:07:00 AM
-LastWriteTimeUtc : 6/5/2021 12:07:00 PM
+CreationTime : 1/24/2024 1:18:29 AM
+CreationTimeUtc : 1/24/2024 7:18:29 AM
+LastAccessTime : 1/3/2025 1:36:20 PM
+LastAccessTimeUtc : 1/3/2025 7:36:20 PM
+LastWriteTime : 1/24/2024 1:18:29 AM
+LastWriteTimeUtc : 1/24/2024 7:18:29 AM
Attributes : Archive
```
-### Static properties
+## Static properties
You can use the static properties of .NET classes in PowerShell. Static
-properties are properties of class, unlike standard properties, which are
-properties of an object.
+properties are properties of the class, unlike standard properties, which are
+properties of an object instance.
To get the static properties of a class, use the **Static** parameter of the
`Get-Member` cmdlet. For example, the following command gets the static
@@ -218,12 +219,8 @@ property of the `System.DateTime` class.
## Member-access enumeration
Starting in PowerShell 3.0, when you use the member-access operator (`.`) to
-access a property that doesn't exist on a list collection, PowerShell
-automatically enumerates the items in the collection and returns the value of
-the property on each item. For more information, see
-[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md).
-
-### Examples
+access a property that doesn't exist, PowerShell automatically enumerates the
+items in the collection and returns the value of the property for each item.
This command returns the value of the **DisplayName** property of every service
that `Get-Service` returns.
@@ -241,8 +238,8 @@ Application Information
...
```
-All collections have a **Count** property that returns the number of objects in
-the collection.
+Most collections in PowerShell have a **Count** property that returns the
+number items in the collection.
```powershell
(Get-Service).Count
@@ -252,50 +249,40 @@ the collection.
176
```
-Starting in PowerShell 3.0, you can get the **Count** or **Length** property of
-singleton objects that aren't collections.
+If a property exists on the individual objects and on the collection, only the
+collection's property is returned.
```powershell
-(Get-Service Audiosrv).Count
-```
-
-```Output
-1
-```
+PS> $collection = @(
+ [pscustomobject]@{Length = "foo"}
+ [pscustomobject]@{Length = "bar"}
+)
-However, some objects have a **Length** property. For example, the **Length**
-of a string is the number of characters in the string. The **Count** property
-is the number of instances of the object.
+# PowerShell returns the collection's Length.
+$collection.Length
+2
-```powershell
-PS> $str = 'string'
-PS> $str.Length
-6
-PS> $str.Count
-1
+# Get the length property of each item in the collection.
+PS> $collection.GetEnumerator().Length
+foo
+bar
```
-If a property exists on the individual objects and on the collection, only the
-collection's property is returned.
-
- ```powershell
- $collection = @(
- [pscustomobject]@{length = "foo"}
- [pscustomobject]@{length = "bar"}
-)
- # PowerShell returns the collection's Length.
- $collection.length
- ```
-
- ```Output
- 2
- ```
+For more information, see [about_Member-Access_Enumeration][01].
## See also
-- [about_Objects](about_Objects.md)
-- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md)
-- [about_Methods](about_Methods.md)
-- [Format-List](xref:Microsoft.PowerShell.Utility.Format-List)
-- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member)
-- [Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object)
+- [about_Objects][03]
+- [about_Member-Access_Enumeration][01]
+- [about_Methods][02]
+- [Format-List][04]
+- [Get-Member][05]
+- [Select-Object][06]
+
+<!-- link references -->
+[01]: about_Member-Access_Enumeration.md
+[02]: about_Methods.md
+[03]: about_Objects.md
+[04]: xref:Microsoft.PowerShell.Utility.Format-List
+[05]: xref:Microsoft.PowerShell.Utility.Get-Member
+[06]: xref:Microsoft.PowerShell.Utility.Select-Object
diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Arrays.md
index 03385f12ad3c..1c58b7a48c4e 100644
--- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Arrays.md
+++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Arrays.md
@@ -1,7 +1,7 @@
---
description: Describes arrays, which are data structures designed to store collections of items.
Locale: en-US
-ms.date: 03/07/2024
+ms.date: 01/03/2025
no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple]
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
@@ -10,6 +10,7 @@ title: about_Arrays
# about_Arrays
## Short description
+
Describes arrays, which are data structures designed to store collections of
items.
@@ -67,7 +68,7 @@ values of a particular type, cast the variable as an array type, such as
variable name with an array type enclosed in brackets. For example:
```powershell
-[int32[]]$ia = 1500, 2230, 3350, 4000
+[Int32[]]$ia = 1500, 2230, 3350, 4000
```
As a result, the `$ia` array can contain only integers.
@@ -341,9 +342,25 @@ while($i -lt 4) {
### Count or Length or LongLength
-To determine how many items are in an array, use the **Length** property or its
-**Count** alias. **Longlength** is useful if the array contains more than
-2,147,483,647 elements.
+In PowerShell, arrays have three properties that indicate the number of items
+contained in the array.
+
+- **Count** - This property is the most commonly used property to determine the
+ number of items in any collection, not just an array. It's an `[Int32]` type
+ value. In Windows PowerShell 5.1 (and older) **Count** alias property for
+ **Length**.
+
+- **Length** - This property is an `[Int32]` type value. This contains the same
+ value as **Count**.
+
+ > [!NOTE]
+ > While **Count** and **Length** are equivalent for arrays, **Length** can
+ > have a different meaning for other types. For example, **Length** for a
+ > string is the number of characters in the string. But the **Count**
+ > property is always `1`.
+
+- **Longlength** - This property is an `[Int64]` type value. Use this property
+ for arrays containing more than 2,147,483,647 elements.
```powershell
$a = 0..9
@@ -470,7 +487,7 @@ True
In this example, `$intA` is explicitly typed to contain integers.
```powershell
-[int[]] $intA = 1, 2, 3
+[Int[]] $intA = 1, 2, 3
$intA.Clear()
$intA
```
@@ -488,7 +505,7 @@ for each element of the array.
The `ForEach()` method has several overloads that perform different operations.
-```
+```Syntax
ForEach(scriptblock expression)
ForEach(scriptblock expression, object[] arguments)
ForEach(type convertToType)
@@ -884,10 +901,11 @@ faster, especially for large arrays.
## Arrays of zero or one
-Beginning in Windows PowerShell 3.0, a collection of zero or one object has the
-**Count** and **Length** properties. Also, you can index into an array of one
-object. This feature helps you to avoid scripting errors that occur when a
-command that expects a collection gets fewer than two items.
+Beginning in Windows PowerShell 3.0, a scalar types and collection of zero or
+one objects has the **Count** and **Length** properties. Also, you can use
+array index notation to access the value of a singleton scalar object. This
+feature helps you to avoid scripting errors that occur when a command that
+expects a collection gets fewer than two items.
The following example shows that a variable that contains no objects has a
**Count** and **Length** of 0.
diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md
index d29b594d4143..246f7695617a 100644
--- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md
+++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md
@@ -1,7 +1,7 @@
---
description: Describes automatic members in all PowerShell objects
Locale: en-US
-ms.date: 01/10/2024
+ms.date: 01/03/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Intrinsic_Members?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Intrinsic_Members
@@ -167,8 +167,15 @@ information on how to use these methods, see [about_Arrays][01].
## Properties
-The **Count** and **Length** properties are available to all PowerShell
-objects, not just collections. These are similar to each other but may work
+Not all scalar type have **Count** or **Length** properties in the base type.
+PowerShell adds the missing property as an intrinsic member for all scalar
+types.
+
+> [!NOTE]
+> Uninitialized variables are implicitly `$null`. `$null` is scalar and has an
+> intrinsic **Count** and **Length** of 0.
+
+While the **Count** and **Length** properties are similar, they may work
differently depending on the data type. For example, the **Length** of a string
is the number of characters in the string. The **Count** property is the number
of instances of the object.
diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Properties.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Properties.md
index 4956b646e6d5..40e40e6727f6 100644
--- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Properties.md
+++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Properties.md
@@ -1,7 +1,7 @@
---
description: Describes how to use object properties in PowerShell.
Locale: en-US
-ms.date: 08/21/2023
+ms.date: 01/03/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_properties?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Properties
@@ -9,6 +9,7 @@ title: about_Properties
# about_Properties
## Short description
+
Describes how to use object properties in PowerShell.
## Long description
@@ -32,7 +33,7 @@ it doesn't. A **DirectoryInfo** object, which represents a file system
directory, has a **Parent** property that contains the path to the parent
directory.
-### Object properties
+## Object properties
To get the properties of an object, use the `Get-Member` cmdlet. For example,
to get the properties of a **FileInfo** object, use the `Get-ChildItem` cmdlet
@@ -116,7 +117,7 @@ $a.CreationTime
```
```Output
-Tuesday, June 14, 2022 5:17:14 PM
+Wednesday, October 16, 2024 4:51:56 PM
```
You can also use the `Select-Object` and `Format-List` cmdlets to display the
@@ -133,21 +134,22 @@ Get-ChildItem $PSHOME\pwsh.exe | Format-List -Property *
```
```Output
-PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Program Files\PowerShell\7-preview\pwsh.exe
-PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Program Files\PowerShell\7-preview
+PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Program Files\PowerShell\7\pwsh.exe
+PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Program Files\PowerShell\7
PSChildName : pwsh.exe
PSDrive : C
PSProvider : Microsoft.PowerShell.Core\FileSystem
PSIsContainer : False
Mode : -a---
ModeWithoutHardLink : -a---
-VersionInfo : File: C:\Program Files\PowerShell\7-preview\pwsh.exe
+VersionInfo : File: C:\Program Files\PowerShell\7\pwsh.exe
InternalName: pwsh.dll
OriginalFilename: pwsh.dll
- FileVersion: 7.3.0.5
+ FileVersion: 7.4.6.500
FileDescription: pwsh
Product: PowerShell
- ProductVersion: 7.3.0-preview.5 SHA: cfc237ac85cf24fa760923ace568201c8f3256aa
+ ProductVersion: 7.4.6 SHA:
+ d71d4f122db89c1bcfb5571b9445d600803c332b+d71d4f122db89c1bcfb5571b9445d600803c332b
Debug: False
Patched: False
PreRelease: False
@@ -156,32 +158,33 @@ VersionInfo : File: C:\Program Files\PowerShell\7-preview\pw
Language: Language Neutral
BaseName : pwsh
-ResolvedTarget : C:\Program Files\PowerShell\7-preview\pwsh.exe
+ResolvedTarget : C:\Program Files\PowerShell\7\pwsh.exe
Target :
LinkType :
-Length : 285088
-DirectoryName : C:\Program Files\PowerShell\7-preview
-Directory : C:\Program Files\PowerShell\7-preview
-IsReadOnly : False
-FullName : C:\Program Files\PowerShell\7-preview\pwsh.exe
-Extension : .exe
Name : pwsh.exe
+Length : 278048
+DirectoryName : C:\Program Files\PowerShell\7
+Directory : C:\Program Files\PowerShell\7
+IsReadOnly : False
Exists : True
-CreationTime : 6/14/2022 5:17:14 PM
-CreationTimeUtc : 6/14/2022 10:17:14 PM
-LastAccessTime : 7/18/2022 11:32:06 AM
-LastAccessTimeUtc : 7/18/2022 4:32:06 PM
-LastWriteTime : 6/14/2022 5:17:14 PM
-LastWriteTimeUtc : 6/14/2022 10:17:14 PM
+FullName : C:\Program Files\PowerShell\7\pwsh.exe
+Extension : .exe
+CreationTime : 10/16/2024 4:51:56 PM
+CreationTimeUtc : 10/16/2024 9:51:56 PM
+LastAccessTime : 1/3/2025 1:33:10 PM
+LastAccessTimeUtc : 1/3/2025 7:33:10 PM
+LastWriteTime : 10/16/2024 4:51:56 PM
+LastWriteTimeUtc : 10/16/2024 9:51:56 PM
LinkTarget :
+UnixFileMode : -1
Attributes : Archive
```
-### Static properties
+## Static properties
You can use the static properties of .NET classes in PowerShell. Static
-properties are properties of class, unlike standard properties, which are
-properties of an object.
+properties are properties of the class, unlike standard properties, which are
+properties of an object instance.
To get the static properties of a class, use the **Static** parameter of the
`Get-Member` cmdlet. For example, the following command gets the static
@@ -219,12 +222,8 @@ property of the `System.DateTime` class.
## Member-access enumeration
Starting in PowerShell 3.0, when you use the member-access operator (`.`) to
-access a property that doesn't exist on a list collection, PowerShell
-automatically enumerates the items in the collection and returns the value of
-the property on each item. For more information, see
-[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md).
-
-### Examples
+access a property that doesn't exist, PowerShell automatically enumerates the
+items in the collection and returns the value of the property for each item.
This command returns the value of the **DisplayName** property of every service
that `Get-Service` returns.
@@ -242,8 +241,8 @@ Application Information
...
```
-All collections have a **Count** property that returns the number of objects in
-the collection.
+Most collections in PowerShell have a **Count** property that returns the
+number items in the collection.
```powershell
(Get-Service).Count
@@ -253,50 +252,40 @@ the collection.
176
```
-Starting in PowerShell 3.0, you can get the **Count** or **Length** property of
-singleton objects that aren't collections.
+If a property exists on the individual objects and on the collection, only the
+collection's property is returned.
```powershell
-(Get-Service Audiosrv).Count
-```
-
-```Output
-1
-```
+PS> $collection = @(
+ [pscustomobject]@{Length = "foo"}
+ [pscustomobject]@{Length = "bar"}
+)
-However, some objects have a **Length** property. For example, the **Length**
-of a string is the number of characters in the string. The **Count** property
-is the number of instances of the object.
+# PowerShell returns the collection's Length.
+$collection.Length
+2
-```powershell
-PS> $str = 'string'
-PS> $str.Length
-6
-PS> $str.Count
-1
+# Get the length property of each item in the collection.
+PS> $collection.GetEnumerator().Length
+foo
+bar
```
-If a property exists on the individual objects and on the collection, only the
-collection's property is returned.
-
- ```powershell
- $collection = @(
- [pscustomobject]@{length = "foo"}
- [pscustomobject]@{length = "bar"}
-)
- # PowerShell returns the collection's Length.
- $collection.length
- ```
-
- ```Output
- 2
- ```
+For more information, see [about_Member-Access_Enumeration][01].
## See also
-- [about_Objects](about_Objects.md)
-- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md)
-- [about_Methods](about_Methods.md)
-- [Format-List](xref:Microsoft.PowerShell.Utility.Format-List)
-- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member)
-- [Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object)
+- [about_Objects][03]
+- [about_Member-Access_Enumeration][01]
+- [about_Methods][02]
+- [Format-List][04]
+- [Get-Member][05]
+- [Select-Object][06]
+
+<!-- link references -->
+[01]: about_Member-Access_Enumeration.md
+[02]: about_Methods.md
+[03]: about_Objects.md
+[04]: xref:Microsoft.PowerShell.Utility.Format-List
+[05]: xref:Microsoft.PowerShell.Utility.Get-Member
+[06]: xref:Microsoft.PowerShell.Utility.Select-Object
diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md
index 96a1733f4e4c..cd7cebefe88b 100644
--- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md
+++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md
@@ -1,7 +1,7 @@
---
description: Describes arrays, which are data structures designed to store collections of items.
Locale: en-US
-ms.date: 03/07/2024
+ms.date: 01/03/2025
no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple]
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7.5&WT.mc_id=ps-gethelp
schema: 2.0.0
@@ -68,7 +68,7 @@ values of a particular type, cast the variable as an array type, such as
variable name with an array type enclosed in brackets. For example:
```powershell
-[int32[]]$ia = 1500, 2230, 3350, 4000
+[Int32[]]$ia = 1500, 2230, 3350, 4000
```
As a result, the `$ia` array can contain only integers.
@@ -342,9 +342,25 @@ while($i -lt 4) {
### Count or Length or LongLength
-To determine how many items are in an array, use the **Length** property or its
-**Count** alias. **Longlength** is useful if the array contains more than
-2,147,483,647 elements.
+In PowerShell, arrays have three properties that indicate the number of items
+contained in the array.
+
+- **Count** - This property is the most commonly used property to determine the
+ number of items in any collection, not just an array. It's an `[Int32]` type
+ value. In Windows PowerShell 5.1 (and older) **Count** alias property for
+ **Length**.
+
+- **Length** - This property is an `[Int32]` type value. This contains the same
+ value as **Count**.
+
+ > [!NOTE]
+ > While **Count** and **Length** are equivalent for arrays, **Length** can
+ > have a different meaning for other types. For example, **Length** for a
+ > string is the number of characters in the string. But the **Count**
+ > property is always `1`.
+
+- **Longlength** - This property is an `[Int64]` type value. Use this property
+ for arrays containing more than 2,147,483,647 elements.
```powershell
$a = 0..9
@@ -471,7 +487,7 @@ True
In this example, `$intA` is explicitly typed to contain integers.
```powershell
-[int[]] $intA = 1, 2, 3
+[Int[]] $intA = 1, 2, 3
$intA.Clear()
$intA
```
@@ -489,7 +505,7 @@ for each element of the array.
The `ForEach()` method has several overloads that perform different operations.
-```
+```Syntax
ForEach(scriptblock expression)
ForEach(scriptblock expression, object[] arguments)
ForEach(type convertToType)
@@ -885,10 +901,11 @@ faster, especially for large arrays.
## Arrays of zero or one
-Beginning in Windows PowerShell 3.0, a collection of zero or one object has the
-**Count** and **Length** properties. Also, you can index into an array of one
-object. This feature helps you to avoid scripting errors that occur when a
-command that expects a collection gets fewer than two items.
+Beginning in Windows PowerShell 3.0, a scalar types and collection of zero or
+one objects has the **Count** and **Length** properties. Also, you can use
+array index notation to access the value of a singleton scalar object. This
+feature helps you to avoid scripting errors that occur when a command that
+expects a collection gets fewer than two items.
The following example shows that a variable that contains no objects has a
**Count** and **Length** of 0.
diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md
index 05acada77713..269825183622 100644
--- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md
+++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Intrinsic_Members.md
@@ -1,7 +1,7 @@
---
description: Describes automatic members in all PowerShell objects
Locale: en-US
-ms.date: 01/10/2024
+ms.date: 01/03/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Intrinsic_Members?view=powershell-7.5&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Intrinsic_Members
@@ -167,8 +167,15 @@ information on how to use these methods, see [about_Arrays][01].
## Properties
-The **Count** and **Length** properties are available to all PowerShell
-objects, not just collections. These are similar to each other but may work
+Not all scalar type have **Count** or **Length** properties in the base type.
+PowerShell adds the missing property as an intrinsic member for all scalar
+types.
+
+> [!NOTE]
+> Uninitialized variables are implicitly `$null`. `$null` is scalar and has an
+> intrinsic **Count** and **Length** of 0.
+
+While the **Count** and **Length** properties are similar, they may work
differently depending on the data type. For example, the **Length** of a string
is the number of characters in the string. The **Count** property is the number
of instances of the object.
diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Properties.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Properties.md
index b3b2b74fa7b8..28692aa044ac 100644
--- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Properties.md
+++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Properties.md
@@ -1,7 +1,7 @@
---
description: Describes how to use object properties in PowerShell.
Locale: en-US
-ms.date: 08/21/2023
+ms.date: 01/03/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_properties?view=powershell-7.5&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Properties
@@ -33,7 +33,7 @@ it doesn't. A **DirectoryInfo** object, which represents a file system
directory, has a **Parent** property that contains the path to the parent
directory.
-### Object properties
+## Object properties
To get the properties of an object, use the `Get-Member` cmdlet. For example,
to get the properties of a **FileInfo** object, use the `Get-ChildItem` cmdlet
@@ -117,7 +117,7 @@ $a.CreationTime
```
```Output
-Tuesday, June 14, 2022 5:17:14 PM
+Wednesday, November 13, 2024 10:12:26 PM
```
You can also use the `Select-Object` and `Format-List` cmdlets to display the
@@ -145,36 +145,37 @@ ModeWithoutHardLink : -a---
VersionInfo : File: C:\Program Files\PowerShell\7-preview\pwsh.exe
InternalName: pwsh.dll
OriginalFilename: pwsh.dll
- FileVersion: 7.3.0.5
- FileDescription: pwsh
+ FileVersion: 7.5.0.101
+ FileDescription: PowerShell 7
Product: PowerShell
- ProductVersion: 7.3.0-preview.5 SHA: cfc237ac85cf24fa760923ace568201c8f3256aa
+ ProductVersion: 7.5.0-rc.1 SHA: c0142dde17137e436e302b3c4e93e2d6dc50c5c4+c0142dde17137e436e302b3c4e93e2d6dc50c5c4
Debug: False
Patched: False
PreRelease: False
PrivateBuild: False
SpecialBuild: False
Language: Language Neutral
-
+
BaseName : pwsh
ResolvedTarget : C:\Program Files\PowerShell\7-preview\pwsh.exe
-Target :
-LinkType :
-Length : 285088
+Target :
+LinkType :
+Name : pwsh.exe
+Length : 284704
DirectoryName : C:\Program Files\PowerShell\7-preview
Directory : C:\Program Files\PowerShell\7-preview
IsReadOnly : False
+Exists : True
FullName : C:\Program Files\PowerShell\7-preview\pwsh.exe
Extension : .exe
-Name : pwsh.exe
-Exists : True
-CreationTime : 6/14/2022 5:17:14 PM
-CreationTimeUtc : 6/14/2022 10:17:14 PM
-LastAccessTime : 7/18/2022 11:32:06 AM
-LastAccessTimeUtc : 7/18/2022 4:32:06 PM
-LastWriteTime : 6/14/2022 5:17:14 PM
-LastWriteTimeUtc : 6/14/2022 10:17:14 PM
-LinkTarget :
+CreationTime : 11/13/2024 10:12:26 PM
+CreationTimeUtc : 11/14/2024 4:12:26 AM
+LastAccessTime : 1/3/2025 1:38:13 PM
+LastAccessTimeUtc : 1/3/2025 7:38:13 PM
+LastWriteTime : 11/13/2024 10:12:26 PM
+LastWriteTimeUtc : 11/14/2024 4:12:26 AM
+LinkTarget :
+UnixFileMode : -1
Attributes : Archive
```
@@ -220,12 +221,8 @@ property of the `System.DateTime` class.
## Member-access enumeration
Starting in PowerShell 3.0, when you use the member-access operator (`.`) to
-access a property that doesn't exist on a list collection, PowerShell
-automatically enumerates the items in the collection and returns the value of
-the property on each item. For more information, see
-[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md).
-
-### Examples
+access a property that doesn't exist, PowerShell automatically enumerates the
+items in the collection and returns the value of the property for each item.
This command returns the value of the **DisplayName** property of every service
that `Get-Service` returns.
@@ -243,8 +240,8 @@ Application Information
...
```
-All collections have a **Count** property that returns the number of objects in
-the collection.
+Most collections in PowerShell have a **Count** property that returns the
+number items in the collection.
```powershell
(Get-Service).Count
@@ -254,50 +251,40 @@ the collection.
176
```
-Starting in PowerShell 3.0, you can get the **Count** or **Length** property of
-singleton objects that aren't collections.
+If a property exists on the individual objects and on the collection, only the
+collection's property is returned.
```powershell
-(Get-Service Audiosrv).Count
-```
-
-```Output
-1
-```
+PS> $collection = @(
+ [pscustomobject]@{Length = "foo"}
+ [pscustomobject]@{Length = "bar"}
+)
-However, some objects have a **Length** property. For example, the **Length**
-of a string is the number of characters in the string. The **Count** property
-is the number of instances of the object.
+# PowerShell returns the collection's Length.
+$collection.Length
+2
-```powershell
-PS> $str = 'string'
-PS> $str.Length
-6
-PS> $str.Count
-1
+# Get the length property of each item in the collection.
+PS> $collection.GetEnumerator().Length
+foo
+bar
```
-If a property exists on the individual objects and on the collection, only the
-collection's property is returned.
-
- ```powershell
- $collection = @(
- [pscustomobject]@{length = "foo"}
- [pscustomobject]@{length = "bar"}
-)
- # PowerShell returns the collection's Length.
- $collection.length
- ```
-
- ```Output
- 2
- ```
+For more information, see [about_Member-Access_Enumeration][01].
## See also
-- [about_Objects](about_Objects.md)
-- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md)
-- [about_Methods](about_Methods.md)
-- [Format-List](xref:Microsoft.PowerShell.Utility.Format-List)
-- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member)
-- [Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object)
+- [about_Objects][03]
+- [about_Member-Access_Enumeration][01]
+- [about_Methods][02]
+- [Format-List][04]
+- [Get-Member][05]
+- [Select-Object][06]
+
+<!-- link references -->
+[01]: about_Member-Access_Enumeration.md
+[02]: about_Methods.md
+[03]: about_Objects.md
+[04]: xref:Microsoft.PowerShell.Utility.Format-List
+[05]: xref:Microsoft.PowerShell.Utility.Get-Member
+[06]: xref:Microsoft.PowerShell.Utility.Select-Object
From e96eaaa336fc5bcf7434fd450bfd34bd899dec7e Mon Sep 17 00:00:00 2001
From: Sean Wheeler <sean.wheeler@microsoft.com>
Date: Fri, 3 Jan 2025 16:12:38 -0600
Subject: [PATCH 4/4] Fixes #11618 - Clarify member-access enumeration behavior
and add error cases (#11627)
* Clarify member-access enumeration behavior and add error cases
* fix typo
---
.../About/about_Member-Access_Enumeration.md | 381 ++++++++++--------
.../About/about_Member-Access_Enumeration.md | 372 ++++++++++-------
.../About/about_Member-Access_Enumeration.md | 372 ++++++++++-------
3 files changed, 665 insertions(+), 460 deletions(-)
diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md
index 9047198b3948..7a26fdcba381 100644
--- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md
+++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md
@@ -1,7 +1,7 @@
---
-description: Describes the automatic enumeration of list collection items when using the member-access operator.
+description: Describes the automatic enumeration of collections when using the member-access operator.
Locale: en-US
-ms.date: 07/18/2022
+ms.date: 01/03/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_member-access_enumeration?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Member-Access_Enumeration
@@ -10,39 +10,32 @@ title: about_Member-Access_Enumeration
## Short description
-Describes the automatic enumeration of list collection items when using the
-member-access operator.
+Describes the automatic enumeration of collections when using the member-access
+operator.
## Long description
-Starting in PowerShell 3.0, the _member-access enumeration_ feature improves the
-convenience of using the member-access operator (`.`) on list collection
-objects. When you use the member-access operator to access a member that does
-not exist on a collection, PowerShell automatically enumerates the items in the
-collection and attempts to access the specified member on each item.
+PowerShell maintains a list of types that are enumerable. Starting in
+PowerShell 3.0, the _member-access enumeration_ feature improves the
+convenience of using the member-access operator (`.`) on collection objects
+that are enumerable.
Member-access enumeration helps you write simpler and shorter code. Instead of
piping a collection object to `ForEach-Object` or using the `ForEach()`
-[intrinsic method](about_Intrinsic_Members.md#methods) to access members on
-each item in the collection, you can use the member-access operator on the
-collection object.
+[intrinsic method][04] to access members on each item in the collection, you
+can use the member-access operator on the collection object.
-These commands are functionally identical with the last one demonstrating use of
-the member-access operator:
+The following examples produce the same results. The last example demonstrates
+the use of the member-access operator:
```powershell
-Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName }
-(Get-Service -Name event*).ForEach({ $_.DisplayName })
-(Get-Service -Name event*).DisplayName
-```
-
-```Output
+PS> Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName }
Windows Event Log
COM+ Event System
-
+PS> (Get-Service -Name event*).ForEach({ $_.DisplayName })
Windows Event Log
COM+ Event System
-
+PS> (Get-Service -Name event*).DisplayName
Windows Event Log
COM+ Event System
```
@@ -50,32 +43,15 @@ COM+ Event System
> [!NOTE]
> You can use the member-access operator to get the values of a property on
> items in a collection but you can't use it to set them directly. For more
-> information, see [about_Arrays](about_Arrays.md#member-access-enumeration).
-
-When you use the member-access operator on any object and the specified member
-exists on that object, the member is invoked. For property members, the operator
-returns the value of that property. For method members, the operator calls that
-method on the object.
+> information, see [about_Arrays][02]. Member-access enumeration is a
+> convenience feature. There can be subtle behavior and performance differences
+> between the various enumeration methods.
-When you use the member-access operator on a list collection object that doesn't
-have the specified member, PowerShell automatically enumerates the items in
-that collection and uses the member-access operator on each enumerated item.
-
-You can check if an object is a list collection by seeing whether its type
-implements the **IList** interface:
-
-```powershell
-$List = @('a', 'b')
-$Hash = @{ a = 'b' }
-$List.GetType().ImplementedInterfaces.Name -contains 'IList'
-$Hash.GetType().ImplementedInterfaces.Name -contains 'IList'
-```
-
-```Output
-True
-
-False
-```
+When you use the member-access operator on an object and the specified member
+exists on that object, the member is invoked. When you use the member-access
+operator on a collection object that doesn't have the specified member,
+PowerShell enumerates the items in that collection and uses the member-access
+operator on each enumerated item.
During member-access enumeration for a property, the operator returns the value
of the property for each item that has that property. If no items have the
@@ -94,76 +70,61 @@ exception.
> error. For additional safety, consider manually enumerating the items and
> explicitly handling any errors.
-The following examples detail the behavior of the member-access operator under
-all possible scenarios.
+## Access members of a non-enumerable object
-## Accessing members of a non-list object
-
-When you use the member-access operator on an object that is not a list collection
-and that has the member, the command returns the value of the property or
-output of the method for that object.
+When you use the member-access operator on an object that isn't an enumerable
+collection, PowerShell invokes the member to returns the value of the property
+or output of the method for that object.
```powershell
-$MyString = 'abc'
-$MyString.Length
-$MyString.ToUpper()
-```
-
-```Output
+PS> $MyString = 'abc'
+PS> $MyString.Length
3
-
+PS> $MyString.ToUpper()
ABC
```
-When you use the member-access operator on a non-list object that does not have
-the member, the command returns `$null` if you specify a property or a
-**MethodNotFound** error if you specify a method.
+When you use the member-access operator on a non-enumerable object that doesn't
+have the member, PowerShell returns `$null` for the missing property or a
+**MethodNotFound** error for the missing method.
```powershell
-$MyString = 'abc'
-$null -eq $MyString.DoesNotExist
-$MyString.DoesNotExist()
-```
-
-```Output
+PS> $MyString = 'abc'
+PS> $null -eq $MyString.DoesNotExist
True
-
-Method invocation failed because [System.String] does not contain a method
-named 'DoesNotExist'.
+PS> $MyString.DoesNotExist()
+Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.
At line:1 char:1
+ $MyString.DoesNotExist()
-+ ~~~~~~~~~~~~~~~~~~~~~~
++ ~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: (:) [], RuntimeException
+ FullyQualifiedErrorId : MethodNotFound
+
```
-## Accessing members of a list collection object
+## Access members of a collection object
When you use the member-access operator on a collection object that has the
member, it always returns the property value or method result for the
collection object.
-### Accessing members that exist on the collection but not its items
+### Access members that exist on the collection but not its items
In this example, the specified members exist on the collection but not the
items in it.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b')
-$Collection.IsReadOnly
-$Collection.Add('c')
-$Collection
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b')
+PS> $Collection.IsReadOnly
False
-
+PS> $Collection.Add('c')
+PS> $Collection
a
b
c
```
-### Accessing members that exist on the collection and its items
+### Access members that exist on the collection and its items
For this example, the specified members exist on both the collection and the
items in it. Compare the results of the commands using the member-access
@@ -173,22 +134,16 @@ returns the property value or method result for the collection object and not
the items in it.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
-$Collection.Count
-$Collection | ForEach-Object -Process { $_.Count }
-$Collection.ToString()
-$Collection | ForEach-Object -Process { $_.ToString() }
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
+PS> $Collection.Count
3
-
+PS> $Collection | ForEach-Object -Process { $_.Count }
1
1
1
-
+PS> $Collection.ToString()
System.Collections.Generic.List`1[System.String]
-
+PS> $Collection | ForEach-Object -Process { $_.ToString() }
a
b
c
@@ -202,119 +157,229 @@ c
> property's.
>
> You can access the dictionary object's property value with the **psbase**
-> [intrinsic member](about_Intrinsic_Members.md). For example, if the key name
-> is `keys` and you want to return the collection of the **HashTable** keys, use
-> this syntax:
+> [intrinsic member][03]. For example, if the key name is `keys` and you want
+> to return the collection of the **HashTable** keys, use this syntax:
>
> ```powershell
-> $hashtable.PSBase.Keys
+> $hashtable.psbase.Keys
> ```
-### Accessing members that exist on all items in a collection but not itself
+### Access members that exist on all items in a collection but not itself
-When you use the member-access operator on a collection object that does not
+When you use the member-access operator on a collection object that doesn't
have the member but the items in it do, PowerShell enumerates the items in the
collection and returns the property value or method result for each item.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
-$Collection.Length
-$Collection.ToUpper()
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
+PS> $Collection.Length
1
1
1
-
+PS> $Collection.ToUpper()
A
B
C
```
-### Accessing members that exist on neither the collection nor its items
+### Access members that don't exist on collection or its items
-When you use the member-access operator on a collection object that does not
+When you use the member-access operator on a collection object that doesn't
have the member and neither do the items in it, the command returns `$null` if
you specify a property or a `MethodNotFound` error if you specify a method.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
-$null -eq $Collection.DoesNotExist
-$Collection.DoesNotExist()
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
+PS> $null -eq $Collection.DoesNotExist
True
-
-Method invocation failed because [System.String] does not contain a method
-named 'DoesNotExist'.
-At line:1 char:1
-+ $Collection.DoesNotExist()
-+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
- + CategoryInfo : InvalidOperation: (:) [], RuntimeException
- + FullyQualifiedErrorId : MethodNotFound
+PS> $Collection.DoesNotExist()
+InvalidOperation: Method invocation failed because [System.String] does not
+contain a method named 'DoesNotExist'.
```
-Because the collection object does not have the member, PowerShell enumerated
+Because the collection object doesn't have the member, PowerShell enumerated
the items in the collection. Notice that the **MethodNotFound** error specifies
-that **System.String** does not contain the method instead of
+that **System.String** doesn't contain the method instead of
**System.Collections.Generic.List**.
-### Accessing methods that exist only on some items in a collection
+### Access methods that exist only on some items in a collection
When you use the member-access operator to access a method on a collection
-object that does not have the method and only some of the items in the
-collection have it, the command returns a `MethodNotFound` error for the first
-item in the collection that does not have the method. Even though the method
-gets called on some items, the command only returns the error.
+object that doesn't have the method and only some items in the collection have
+it, the command returns a `MethodNotFound` error for the first item in the
+collection that doesn't have the method. Even though the method gets called on
+some items, the command only returns the error.
```powershell
-@('a', 1, 'c').ToUpper()
-```
-
-```Output
-Method invocation failed because [System.Int32] does not contain a method
-named 'ToUpper'.
-At line:1 char:1
-+ @('a', 1, 'c').ToUpper()
-+ ~~~~~~~~~~~~~~~~~~~~~~~~
- + CategoryInfo : InvalidOperation: (:) [], RuntimeException
- + FullyQualifiedErrorId : MethodNotFound
+PS> @('a', 1, 'c').ToUpper()
+InvalidOperation: Method invocation failed because [System.Int32] does not
+contain a method named 'ToUpper'.
```
-### Accessing properties that exist only on some items in a collection
+### Access properties that exist only on some items in a collection
When you use the member-access operator to access a property on a collection
-object that does not have the property and only some of the items in the
-collection have it, the command returns the property value for each item in the
-collection that has the property.
+object that doesn't have the property and only some items in the collection
+have it, the command returns the property value for each item in the collection
+that has the property.
```powershell
-$CapitalizedProperty = @{
+PS> $CapitalizedProperty = @{
MemberType = 'ScriptProperty'
Name = 'Capitalized'
Value = { $this.ToUpper() }
PassThru = $true
}
-[System.Collections.Generic.List[object]]$MixedCollection = @(
+PS> [System.Collections.Generic.List[object]]$MixedCollection = @(
'a'
('b' | Add-Member @CapitalizedProperty)
('c' | Add-Member @CapitalizedProperty)
'd'
)
-$MixedCollection.Capitalized
-```
-
-```Output
+PS> $MixedCollection.Capitalized
B
C
```
+### Access members of a nested collection
+
+When an enumerable collection contains a nested collection, member-access
+enumeration is applied to each nested collection.
+
+For example, `$a` is an array containing two elements: a nested array of
+strings and a single string.
+
+```powershell
+# Get the count of items in the array.
+PS> $a.Count
+2
+# Get the count of items in each nested item.
+PS> $a.GetEnumerator().Count
+2
+1
+# Call the ToUpper() method on all items in the nested array.
+PS> $a = @(, ('bar', 'baz'), 'foo')
+PS> $a.ToUpper()
+BAR
+BAZ
+FOO
+```
+
+When you use the member-access operator, PowerShell enumerates the items in
+`$a` and calls the `ToUpper()` method on all items.
+
+## Notes
+
+As previously stated, there can be subtle behavior and performance differences
+between the various enumeration methods.
+
+### Errors result in lost output
+
+When member-access enumeration is terminated by an error, output from prior
+successful method calls isn't returned. Terminating error conditions include:
+
+- the enumerated object lacks the accessed method
+- the accessed method raises a terminating error
+
+Consider the following example:
+
+```powershell
+class Class1 { [object] Foo() { return 'Bar' } }
+class Class2 { [void] Foo() { throw 'Error' } }
+class Class3 {}
+
+$example1 = ([Class1]::new(), [Class1]::new())
+$example2 = ([Class1]::new(), [Class2]::new())
+$example3 = ([Class1]::new(), [Class3]::new())
+```
+
+Both items in `$example1` have the `Foo()` method, so the method call succeeds.
+
+```powershell
+PS> $example1.Foo()
+Bar
+Bar
+```
+
+The `Foo()` method on second item in `$example2` throws an error, so the
+enumeration fails.
+
+```powershell
+PS> $example2.Foo()
+Exception:
+Line |
+ 2 | class Class2 { [void] Foo() { throw 'Error' } }
+ | ~~~~~~~~~~~~~
+ | Error
+```
+
+The second item in `$example2` doesn't have the `Foo()` method, so the
+enumeration fails.
+
+```powershell
+PS> $example3.Foo()
+InvalidOperation: Method invocation failed because [Class3] does not contain
+a method named 'Foo'.
+```
+
+Compare this to enumeration using `ForEach-Object`
+
+```powershell
+PS> $example2 | ForEach-Object -MemberName Foo
+Bar
+ForEach-Object: Exception calling "Foo" with "0" argument(s): "Error"
+PS> $example3 | ForEach-Object -MemberName Foo
+Bar
+```
+
+Notice that the output show the successful call to `Foo()` on the first item
+in the array.
+
+### Collections containing PSCustomObject instances
+
+If the collection of objects contains instances of **PSCustomObject** items,
+PowerShell unexpectedly retruns `$null` values when the accessed property is
+missing.
+
+In the following examples at least one object has the referenced property.
+
+```powershell
+PS> $foo = [pscustomobject]@{ Foo = 'Foo' }
+PS> $bar = [pscustomobject]@{ Bar = 'Bar' }
+PS> $baz = [pscustomobject]@{ Baz = 'Baz' }
+PS> ConvertTo-Json ($foo, $bar, $baz).Foo
+[
+ "Foo",
+ null,
+ null
+]
+PS> ConvertTo-Json ((Get-Process -Id $PID), $foo).Name
+[
+ "pwsh",
+ null
+]
+```
+
+You would expect PowerShell to return a single object for the item that has the
+property specified. Instead, PowerShell also returns a `$null` value for each
+item that doesn't have the property.
+
+For more information on this behavior, see PowerShell Issue [#13752][13752].
+
## See Also
-- [about_Arrays](about_Arrays.md)
-- [about_Intrinsic_Members](about_Intrinsic_Members.md)
-- [about_Methods](about_Methods.md)
-- [about_Operators](about_Operators.md)
-- [about_Properties](about_Properties.md)
+- [about_Arrays][01]
+- [about_Intrinsic_Members][03]
+- [about_Methods][05]
+- [about_Operators][06]
+- [about_Properties][07]
+
+<!-- link references -->
+[01]: about_Arrays.md
+[02]: about_Arrays.md#member-access-enumeration
+[03]: about_Intrinsic_Members.md
+[04]: about_Intrinsic_Members.md#methods
+[05]: about_Methods.md
+[06]: about_Operators.md
+[07]: about_Properties.md
+[13752]: https://github.com/PowerShell/PowerShell/issues/13752
diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md
index 6b4657970d65..feb4702fe8b1 100644
--- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md
+++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md
@@ -1,7 +1,7 @@
---
-description: Describes the automatic enumeration of list collection items when using the member-access operator.
+description: Describes the automatic enumeration of collections when using the member-access operator.
Locale: en-US
-ms.date: 07/18/2022
+ms.date: 01/03/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_member-access_enumeration?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Member-Access_Enumeration
@@ -10,39 +10,32 @@ title: about_Member-Access_Enumeration
## Short description
-Describes the automatic enumeration of list collection items when using the
-member-access operator.
+Describes the automatic enumeration of collections when using the member-access
+operator.
## Long description
-Starting in PowerShell 3.0, the _member-access enumeration_ feature improves the
-convenience of using the member-access operator (`.`) on list collection
-objects. When you use the member-access operator to access a member that does
-not exist on a collection, PowerShell automatically enumerates the items in the
-collection and attempts to access the specified member on each item.
+PowerShell maintains a list of types that are enumerable. Starting in
+PowerShell 3.0, the _member-access enumeration_ feature improves the
+convenience of using the member-access operator (`.`) on collection objects
+that are enumerable.
Member-access enumeration helps you write simpler and shorter code. Instead of
piping a collection object to `ForEach-Object` or using the `ForEach()`
-[intrinsic method](about_Intrinsic_Members.md#methods) to access members on
-each item in the collection, you can use the member-access operator on the
-collection object.
+[intrinsic method][04] to access members on each item in the collection, you
+can use the member-access operator on the collection object.
-These commands are functionally identical with the last one demonstrating use of
-the member-access operator:
+The following examples produce the same results. The last example demonstrates
+the use of the member-access operator:
```powershell
-Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName }
-(Get-Service -Name event*).ForEach({ $_.DisplayName })
-(Get-Service -Name event*).DisplayName
-```
-
-```Output
+PS> Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName }
Windows Event Log
COM+ Event System
-
+PS> (Get-Service -Name event*).ForEach({ $_.DisplayName })
Windows Event Log
COM+ Event System
-
+PS> (Get-Service -Name event*).DisplayName
Windows Event Log
COM+ Event System
```
@@ -50,32 +43,15 @@ COM+ Event System
> [!NOTE]
> You can use the member-access operator to get the values of a property on
> items in a collection but you can't use it to set them directly. For more
-> information, see [about_Arrays](about_Arrays.md#member-access-enumeration).
-
-When you use the member-access operator on any object and the specified member
-exists on that object, the member is invoked. For property members, the operator
-returns the value of that property. For method members, the operator calls that
-method on the object.
-
-When you use the member-access operator on a list collection object that doesn't
-have the specified member, PowerShell automatically enumerates the items in
-that collection and uses the member-access operator on each enumerated item.
-
-You can check if an object is a list collection by seeing whether its type
-implements the **IList** interface:
-
-```powershell
-$List = @('a', 'b')
-$Hash = @{ a = 'b' }
-$List.GetType().ImplementedInterfaces.Name -contains 'IList'
-$Hash.GetType().ImplementedInterfaces.Name -contains 'IList'
-```
+> information, see [about_Arrays][02]. Member-access enumeration is a
+> convenience feature. There can be subtle behavior and performance differences
+> between the various enumeration methods.
-```Output
-True
-
-False
-```
+When you use the member-access operator on an object and the specified member
+exists on that object, the member is invoked. When you use the member-access
+operator on a collection object that doesn't have the specified member,
+PowerShell enumerates the items in that collection and uses the member-access
+operator on each enumerated item.
During member-access enumeration for a property, the operator returns the value
of the property for each item that has that property. If no items have the
@@ -94,74 +70,56 @@ exception.
> error. For additional safety, consider manually enumerating the items and
> explicitly handling any errors.
-The following examples detail the behavior of the member-access operator under
-all possible scenarios.
-
-## Accessing members of a non-list object
+## Access members of a non-enumerable object
-When you use the member-access operator on an object that is not a list collection
-and that has the member, the command returns the value of the property or
-output of the method for that object.
+When you use the member-access operator on an object that isn't an enumerable
+collection, PowerShell invokes the member to returns the value of the property
+or output of the method for that object.
```powershell
-$MyString = 'abc'
-$MyString.Length
-$MyString.ToUpper()
-```
-
-```Output
+PS> $MyString = 'abc'
+PS> $MyString.Length
3
-
+PS> $MyString.ToUpper()
ABC
```
-When you use the member-access operator on a non-list object that does not have
-the member, the command returns `$null` if you specify a property or a
-**MethodNotFound** error if you specify a method.
+When you use the member-access operator on a non-enumerable object that doesn't
+have the member, PowerShell returns `$null` for the missing property or a
+**MethodNotFound** error for the missing method.
```powershell
-$MyString = 'abc'
-$null -eq $MyString.DoesNotExist
-$MyString.DoesNotExist()
-```
-
-```Output
+PS> $MyString = 'abc'
+PS> $null -eq $MyString.DoesNotExist
True
+PS> $MyString.DoesNotExist()
+InvalidOperation: Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.
-InvalidOperation:
-Line |
- 3 | $MyString.DoesNotExist()
- | ~~~~~~~~~~~~~~~~~~~~~~~~
- | Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.
```
-## Accessing members of a list collection object
+## Access members of a collection object
When you use the member-access operator on a collection object that has the
member, it always returns the property value or method result for the
collection object.
-### Accessing members that exist on the collection but not its items
+### Access members that exist on the collection but not its items
In this example, the specified members exist on the collection but not the
items in it.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b')
-$Collection.IsReadOnly
-$Collection.Add('c')
-$Collection
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b')
+PS> $Collection.IsReadOnly
False
-
+PS> $Collection.Add('c')
+PS> $Collection
a
b
c
```
-### Accessing members that exist on the collection and its items
+### Access members that exist on the collection and its items
For this example, the specified members exist on both the collection and the
items in it. Compare the results of the commands using the member-access
@@ -171,22 +129,16 @@ returns the property value or method result for the collection object and not
the items in it.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
-$Collection.Count
-$Collection | ForEach-Object -Process { $_.Count }
-$Collection.ToString()
-$Collection | ForEach-Object -Process { $_.ToString() }
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
+PS> $Collection.Count
3
-
+PS> $Collection | ForEach-Object -Process { $_.Count }
1
1
1
-
+PS> $Collection.ToString()
System.Collections.Generic.List`1[System.String]
-
+PS> $Collection | ForEach-Object -Process { $_.ToString() }
a
b
c
@@ -200,111 +152,229 @@ c
> property's.
>
> You can access the dictionary object's property value with the **psbase**
-> [intrinsic member](about_Intrinsic_Members.md). For example, if the key name
-> is `keys` and you want to return the collection of the **HashTable** keys, use
-> this syntax:
+> [intrinsic member][03]. For example, if the key name is `keys` and you want
+> to return the collection of the **HashTable** keys, use this syntax:
>
> ```powershell
-> $hashtable.PSBase.Keys
+> $hashtable.psbase.Keys
> ```
-### Accessing members that exist on all items in a collection but not itself
+### Access members that exist on all items in a collection but not itself
-When you use the member-access operator on a collection object that does not
+When you use the member-access operator on a collection object that doesn't
have the member but the items in it do, PowerShell enumerates the items in the
collection and returns the property value or method result for each item.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
-$Collection.Length
-$Collection.ToUpper()
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
+PS> $Collection.Length
1
1
1
-
+PS> $Collection.ToUpper()
A
B
C
```
-### Accessing members that exist on neither the collection nor its items
+### Access members that don't exist on collection or its items
-When you use the member-access operator on a collection object that does not
+When you use the member-access operator on a collection object that doesn't
have the member and neither do the items in it, the command returns `$null` if
you specify a property or a `MethodNotFound` error if you specify a method.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
-$null -eq $Collection.DoesNotExist
-$Collection.DoesNotExist()
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
+PS> $null -eq $Collection.DoesNotExist
True
-
-InvalidOperation:
-Line |
- 3 | $Collection.DoesNotExist()
- | ~~~~~~~~~~~~~~~~~~~~~~~~~~
- | Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.
+PS> $Collection.DoesNotExist()
+InvalidOperation: Method invocation failed because [System.String] does not
+contain a method named 'DoesNotExist'.
```
-Because the collection object does not have the member, PowerShell enumerated
+Because the collection object doesn't have the member, PowerShell enumerated
the items in the collection. Notice that the **MethodNotFound** error specifies
-that **System.String** does not contain the method instead of
+that **System.String** doesn't contain the method instead of
**System.Collections.Generic.List**.
-### Accessing methods that exist only on some items in a collection
+### Access methods that exist only on some items in a collection
When you use the member-access operator to access a method on a collection
-object that does not have the method and only some of the items in the
-collection have it, the command returns a `MethodNotFound` error for the first
-item in the collection that does not have the method. Even though the method
-gets called on some items, the command only returns the error.
+object that doesn't have the method and only some items in the collection have
+it, the command returns a `MethodNotFound` error for the first item in the
+collection that doesn't have the method. Even though the method gets called on
+some items, the command only returns the error.
```powershell
-@('a', 1, 'c').ToUpper()
-```
-
-```Output
-InvalidOperation: Method invocation failed because [System.Int32] does not contain a method named 'ToUpper'.
+PS> @('a', 1, 'c').ToUpper()
+InvalidOperation: Method invocation failed because [System.Int32] does not
+contain a method named 'ToUpper'.
```
-### Accessing properties that exist only on some items in a collection
+### Access properties that exist only on some items in a collection
When you use the member-access operator to access a property on a collection
-object that does not have the property and only some of the items in the
-collection have it, the command returns the property value for each item in the
-collection that has the property.
+object that doesn't have the property and only some items in the collection
+have it, the command returns the property value for each item in the collection
+that has the property.
```powershell
-$CapitalizedProperty = @{
+PS> $CapitalizedProperty = @{
MemberType = 'ScriptProperty'
Name = 'Capitalized'
Value = { $this.ToUpper() }
PassThru = $true
}
-[System.Collections.Generic.List[object]]$MixedCollection = @(
+PS> [System.Collections.Generic.List[object]]$MixedCollection = @(
'a'
('b' | Add-Member @CapitalizedProperty)
('c' | Add-Member @CapitalizedProperty)
'd'
)
-$MixedCollection.Capitalized
-```
-
-```Output
+PS> $MixedCollection.Capitalized
B
C
```
+### Access members of a nested collection
+
+When an enumerable collection contains a nested collection, member-access
+enumeration is applied to each nested collection.
+
+For example, `$a` is an array containing two elements: a nested array of
+strings and a single string.
+
+```powershell
+# Get the count of items in the array.
+PS> $a.Count
+2
+# Get the count of items in each nested item.
+PS> $a.GetEnumerator().Count
+2
+1
+# Call the ToUpper() method on all items in the nested array.
+PS> $a = @(, ('bar', 'baz'), 'foo')
+PS> $a.ToUpper()
+BAR
+BAZ
+FOO
+```
+
+When you use the member-access operator, PowerShell enumerates the items in
+`$a` and calls the `ToUpper()` method on all items.
+
+## Notes
+
+As previously stated, there can be subtle behavior and performance differences
+between the various enumeration methods.
+
+### Errors result in lost output
+
+When member-access enumeration is terminated by an error, output from prior
+successful method calls isn't returned. Terminating error conditions include:
+
+- the enumerated object lacks the accessed method
+- the accessed method raises a terminating error
+
+Consider the following example:
+
+```powershell
+class Class1 { [object] Foo() { return 'Bar' } }
+class Class2 { [void] Foo() { throw 'Error' } }
+class Class3 {}
+
+$example1 = ([Class1]::new(), [Class1]::new())
+$example2 = ([Class1]::new(), [Class2]::new())
+$example3 = ([Class1]::new(), [Class3]::new())
+```
+
+Both items in `$example1` have the `Foo()` method, so the method call succeeds.
+
+```powershell
+PS> $example1.Foo()
+Bar
+Bar
+```
+
+The `Foo()` method on second item in `$example2` throws an error, so the
+enumeration fails.
+
+```powershell
+PS> $example2.Foo()
+Exception:
+Line |
+ 2 | class Class2 { [void] Foo() { throw 'Error' } }
+ | ~~~~~~~~~~~~~
+ | Error
+```
+
+The second item in `$example2` doesn't have the `Foo()` method, so the
+enumeration fails.
+
+```powershell
+PS> $example3.Foo()
+InvalidOperation: Method invocation failed because [Class3] does not contain
+a method named 'Foo'.
+```
+
+Compare this to enumeration using `ForEach-Object`
+
+```powershell
+PS> $example2 | ForEach-Object -MemberName Foo
+Bar
+ForEach-Object: Exception calling "Foo" with "0" argument(s): "Error"
+PS> $example3 | ForEach-Object -MemberName Foo
+Bar
+```
+
+Notice that the output show the successful call to `Foo()` on the first item
+in the array.
+
+### Collections containing PSCustomObject instances
+
+If the collection of objects contains instances of **PSCustomObject** items,
+PowerShell unexpectedly retruns `$null` values when the accessed property is
+missing.
+
+In the following examples at least one object has the referenced property.
+
+```powershell
+PS> $foo = [pscustomobject]@{ Foo = 'Foo' }
+PS> $bar = [pscustomobject]@{ Bar = 'Bar' }
+PS> $baz = [pscustomobject]@{ Baz = 'Baz' }
+PS> ConvertTo-Json ($foo, $bar, $baz).Foo
+[
+ "Foo",
+ null,
+ null
+]
+PS> ConvertTo-Json ((Get-Process -Id $PID), $foo).Name
+[
+ "pwsh",
+ null
+]
+```
+
+You would expect PowerShell to return a single object for the item that has the
+property specified. Instead, PowerShell also returns a `$null` value for each
+item that doesn't have the property.
+
+For more information on this behavior, see PowerShell Issue [#13752][13752].
+
## See Also
-- [about_Arrays](about_Arrays.md)
-- [about_Intrinsic_Members](about_Intrinsic_Members.md)
-- [about_Methods](about_Methods.md)
-- [about_Operators](about_Operators.md)
-- [about_Properties](about_Properties.md)
+- [about_Arrays][01]
+- [about_Intrinsic_Members][03]
+- [about_Methods][05]
+- [about_Operators][06]
+- [about_Properties][07]
+
+<!-- link references -->
+[01]: about_Arrays.md
+[02]: about_Arrays.md#member-access-enumeration
+[03]: about_Intrinsic_Members.md
+[04]: about_Intrinsic_Members.md#methods
+[05]: about_Methods.md
+[06]: about_Operators.md
+[07]: about_Properties.md
+[13752]: https://github.com/PowerShell/PowerShell/issues/13752
diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md
index 8a8c38e053d2..189aeda791e7 100644
--- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md
+++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md
@@ -1,7 +1,7 @@
---
-description: Describes the automatic enumeration of list collection items when using the member-access operator.
+description: Describes the automatic enumeration of collections when using the member-access operator.
Locale: en-US
-ms.date: 07/18/2022
+ms.date: 01/03/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_member-access_enumeration?view=powershell-7.5&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Member-Access_Enumeration
@@ -10,39 +10,32 @@ title: about_Member-Access_Enumeration
## Short description
-Describes the automatic enumeration of list collection items when using the
-member-access operator.
+Describes the automatic enumeration of collections when using the member-access
+operator.
## Long description
-Starting in PowerShell 3.0, the _member-access enumeration_ feature improves the
-convenience of using the member-access operator (`.`) on list collection
-objects. When you use the member-access operator to access a member that does
-not exist on a collection, PowerShell automatically enumerates the items in the
-collection and attempts to access the specified member on each item.
+PowerShell maintains a list of types that are enumerable. Starting in
+PowerShell 3.0, the _member-access enumeration_ feature improves the
+convenience of using the member-access operator (`.`) on collection objects
+that are enumerable.
Member-access enumeration helps you write simpler and shorter code. Instead of
piping a collection object to `ForEach-Object` or using the `ForEach()`
-[intrinsic method](about_Intrinsic_Members.md#methods) to access members on
-each item in the collection, you can use the member-access operator on the
-collection object.
+[intrinsic method][04] to access members on each item in the collection, you
+can use the member-access operator on the collection object.
-These commands are functionally identical with the last one demonstrating use of
-the member-access operator:
+The following examples produce the same results. The last example demonstrates
+the use of the member-access operator:
```powershell
-Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName }
-(Get-Service -Name event*).ForEach({ $_.DisplayName })
-(Get-Service -Name event*).DisplayName
-```
-
-```Output
+PS> Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName }
Windows Event Log
COM+ Event System
-
+PS> (Get-Service -Name event*).ForEach({ $_.DisplayName })
Windows Event Log
COM+ Event System
-
+PS> (Get-Service -Name event*).DisplayName
Windows Event Log
COM+ Event System
```
@@ -50,32 +43,15 @@ COM+ Event System
> [!NOTE]
> You can use the member-access operator to get the values of a property on
> items in a collection but you can't use it to set them directly. For more
-> information, see [about_Arrays](about_Arrays.md#member-access-enumeration).
-
-When you use the member-access operator on any object and the specified member
-exists on that object, the member is invoked. For property members, the operator
-returns the value of that property. For method members, the operator calls that
-method on the object.
-
-When you use the member-access operator on a list collection object that doesn't
-have the specified member, PowerShell automatically enumerates the items in
-that collection and uses the member-access operator on each enumerated item.
-
-You can check if an object is a list collection by seeing whether its type
-implements the **IList** interface:
-
-```powershell
-$List = @('a', 'b')
-$Hash = @{ a = 'b' }
-$List.GetType().ImplementedInterfaces.Name -contains 'IList'
-$Hash.GetType().ImplementedInterfaces.Name -contains 'IList'
-```
+> information, see [about_Arrays][02]. Member-access enumeration is a
+> convenience feature. There can be subtle behavior and performance differences
+> between the various enumeration methods.
-```Output
-True
-
-False
-```
+When you use the member-access operator on an object and the specified member
+exists on that object, the member is invoked. When you use the member-access
+operator on a collection object that doesn't have the specified member,
+PowerShell enumerates the items in that collection and uses the member-access
+operator on each enumerated item.
During member-access enumeration for a property, the operator returns the value
of the property for each item that has that property. If no items have the
@@ -94,74 +70,56 @@ exception.
> error. For additional safety, consider manually enumerating the items and
> explicitly handling any errors.
-The following examples detail the behavior of the member-access operator under
-all possible scenarios.
-
-## Accessing members of a non-list object
+## Access members of a non-enumerable object
-When you use the member-access operator on an object that is not a list collection
-and that has the member, the command returns the value of the property or
-output of the method for that object.
+When you use the member-access operator on an object that isn't an enumerable
+collection, PowerShell invokes the member to returns the value of the property
+or output of the method for that object.
```powershell
-$MyString = 'abc'
-$MyString.Length
-$MyString.ToUpper()
-```
-
-```Output
+PS> $MyString = 'abc'
+PS> $MyString.Length
3
-
+PS> $MyString.ToUpper()
ABC
```
-When you use the member-access operator on a non-list object that does not have
-the member, the command returns `$null` if you specify a property or a
-**MethodNotFound** error if you specify a method.
+When you use the member-access operator on a non-enumerable object that doesn't
+have the member, PowerShell returns `$null` for the missing property or a
+**MethodNotFound** error for the missing method.
```powershell
-$MyString = 'abc'
-$null -eq $MyString.DoesNotExist
-$MyString.DoesNotExist()
-```
-
-```Output
+PS> $MyString = 'abc'
+PS> $null -eq $MyString.DoesNotExist
True
+PS> $MyString.DoesNotExist()
+InvalidOperation: Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.
-InvalidOperation:
-Line |
- 3 | $MyString.DoesNotExist()
- | ~~~~~~~~~~~~~~~~~~~~~~~~
- | Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.
```
-## Accessing members of a list collection object
+## Access members of a collection object
When you use the member-access operator on a collection object that has the
member, it always returns the property value or method result for the
collection object.
-### Accessing members that exist on the collection but not its items
+### Access members that exist on the collection but not its items
In this example, the specified members exist on the collection but not the
items in it.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b')
-$Collection.IsReadOnly
-$Collection.Add('c')
-$Collection
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b')
+PS> $Collection.IsReadOnly
False
-
+PS> $Collection.Add('c')
+PS> $Collection
a
b
c
```
-### Accessing members that exist on the collection and its items
+### Access members that exist on the collection and its items
For this example, the specified members exist on both the collection and the
items in it. Compare the results of the commands using the member-access
@@ -171,22 +129,16 @@ returns the property value or method result for the collection object and not
the items in it.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
-$Collection.Count
-$Collection | ForEach-Object -Process { $_.Count }
-$Collection.ToString()
-$Collection | ForEach-Object -Process { $_.ToString() }
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
+PS> $Collection.Count
3
-
+PS> $Collection | ForEach-Object -Process { $_.Count }
1
1
1
-
+PS> $Collection.ToString()
System.Collections.Generic.List`1[System.String]
-
+PS> $Collection | ForEach-Object -Process { $_.ToString() }
a
b
c
@@ -200,111 +152,229 @@ c
> property's.
>
> You can access the dictionary object's property value with the **psbase**
-> [intrinsic member](about_Intrinsic_Members.md). For example, if the key name
-> is `keys` and you want to return the collection of the **HashTable** keys, use
-> this syntax:
+> [intrinsic member][03]. For example, if the key name is `keys` and you want
+> to return the collection of the **HashTable** keys, use this syntax:
>
> ```powershell
-> $hashtable.PSBase.Keys
+> $hashtable.psbase.Keys
> ```
-### Accessing members that exist on all items in a collection but not itself
+### Access members that exist on all items in a collection but not itself
-When you use the member-access operator on a collection object that does not
+When you use the member-access operator on a collection object that doesn't
have the member but the items in it do, PowerShell enumerates the items in the
collection and returns the property value or method result for each item.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
-$Collection.Length
-$Collection.ToUpper()
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
+PS> $Collection.Length
1
1
1
-
+PS> $Collection.ToUpper()
A
B
C
```
-### Accessing members that exist on neither the collection nor its items
+### Access members that don't exist on collection or its items
-When you use the member-access operator on a collection object that does not
+When you use the member-access operator on a collection object that doesn't
have the member and neither do the items in it, the command returns `$null` if
you specify a property or a `MethodNotFound` error if you specify a method.
```powershell
-[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
-$null -eq $Collection.DoesNotExist
-$Collection.DoesNotExist()
-```
-
-```Output
+PS> [System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
+PS> $null -eq $Collection.DoesNotExist
True
-
-InvalidOperation:
-Line |
- 3 | $Collection.DoesNotExist()
- | ~~~~~~~~~~~~~~~~~~~~~~~~~~
- | Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.
+PS> $Collection.DoesNotExist()
+InvalidOperation: Method invocation failed because [System.String] does not
+contain a method named 'DoesNotExist'.
```
-Because the collection object does not have the member, PowerShell enumerated
+Because the collection object doesn't have the member, PowerShell enumerated
the items in the collection. Notice that the **MethodNotFound** error specifies
-that **System.String** does not contain the method instead of
+that **System.String** doesn't contain the method instead of
**System.Collections.Generic.List**.
-### Accessing methods that exist only on some items in a collection
+### Access methods that exist only on some items in a collection
When you use the member-access operator to access a method on a collection
-object that does not have the method and only some of the items in the
-collection have it, the command returns a `MethodNotFound` error for the first
-item in the collection that does not have the method. Even though the method
-gets called on some items, the command only returns the error.
+object that doesn't have the method and only some items in the collection have
+it, the command returns a `MethodNotFound` error for the first item in the
+collection that doesn't have the method. Even though the method gets called on
+some items, the command only returns the error.
```powershell
-@('a', 1, 'c').ToUpper()
-```
-
-```Output
-InvalidOperation: Method invocation failed because [System.Int32] does not contain a method named 'ToUpper'.
+PS> @('a', 1, 'c').ToUpper()
+InvalidOperation: Method invocation failed because [System.Int32] does not
+contain a method named 'ToUpper'.
```
-### Accessing properties that exist only on some items in a collection
+### Access properties that exist only on some items in a collection
When you use the member-access operator to access a property on a collection
-object that does not have the property and only some of the items in the
-collection have it, the command returns the property value for each item in the
-collection that has the property.
+object that doesn't have the property and only some items in the collection
+have it, the command returns the property value for each item in the collection
+that has the property.
```powershell
-$CapitalizedProperty = @{
+PS> $CapitalizedProperty = @{
MemberType = 'ScriptProperty'
Name = 'Capitalized'
Value = { $this.ToUpper() }
PassThru = $true
}
-[System.Collections.Generic.List[object]]$MixedCollection = @(
+PS> [System.Collections.Generic.List[object]]$MixedCollection = @(
'a'
('b' | Add-Member @CapitalizedProperty)
('c' | Add-Member @CapitalizedProperty)
'd'
)
-$MixedCollection.Capitalized
-```
-
-```Output
+PS> $MixedCollection.Capitalized
B
C
```
+### Access members of a nested collection
+
+When an enumerable collection contains a nested collection, member-access
+enumeration is applied to each nested collection.
+
+For example, `$a` is an array containing two elements: a nested array of
+strings and a single string.
+
+```powershell
+# Get the count of items in the array.
+PS> $a.Count
+2
+# Get the count of items in each nested item.
+PS> $a.GetEnumerator().Count
+2
+1
+# Call the ToUpper() method on all items in the nested array.
+PS> $a = @(, ('bar', 'baz'), 'foo')
+PS> $a.ToUpper()
+BAR
+BAZ
+FOO
+```
+
+When you use the member-access operator, PowerShell enumerates the items in
+`$a` and calls the `ToUpper()` method on all items.
+
+## Notes
+
+As previously stated, there can be subtle behavior and performance differences
+between the various enumeration methods.
+
+### Errors result in lost output
+
+When member-access enumeration is terminated by an error, output from prior
+successful method calls isn't returned. Terminating error conditions include:
+
+- the enumerated object lacks the accessed method
+- the accessed method raises a terminating error
+
+Consider the following example:
+
+```powershell
+class Class1 { [object] Foo() { return 'Bar' } }
+class Class2 { [void] Foo() { throw 'Error' } }
+class Class3 {}
+
+$example1 = ([Class1]::new(), [Class1]::new())
+$example2 = ([Class1]::new(), [Class2]::new())
+$example3 = ([Class1]::new(), [Class3]::new())
+```
+
+Both items in `$example1` have the `Foo()` method, so the method call succeeds.
+
+```powershell
+PS> $example1.Foo()
+Bar
+Bar
+```
+
+The `Foo()` method on second item in `$example2` throws an error, so the
+enumeration fails.
+
+```powershell
+PS> $example2.Foo()
+Exception:
+Line |
+ 2 | class Class2 { [void] Foo() { throw 'Error' } }
+ | ~~~~~~~~~~~~~
+ | Error
+```
+
+The second item in `$example2` doesn't have the `Foo()` method, so the
+enumeration fails.
+
+```powershell
+PS> $example3.Foo()
+InvalidOperation: Method invocation failed because [Class3] does not contain
+a method named 'Foo'.
+```
+
+Compare this to enumeration using `ForEach-Object`
+
+```powershell
+PS> $example2 | ForEach-Object -MemberName Foo
+Bar
+ForEach-Object: Exception calling "Foo" with "0" argument(s): "Error"
+PS> $example3 | ForEach-Object -MemberName Foo
+Bar
+```
+
+Notice that the output show the successful call to `Foo()` on the first item
+in the array.
+
+### Collections containing PSCustomObject instances
+
+If the collection of objects contains instances of **PSCustomObject** items,
+PowerShell unexpectedly retruns `$null` values when the accessed property is
+missing.
+
+In the following examples at least one object has the referenced property.
+
+```powershell
+PS> $foo = [pscustomobject]@{ Foo = 'Foo' }
+PS> $bar = [pscustomobject]@{ Bar = 'Bar' }
+PS> $baz = [pscustomobject]@{ Baz = 'Baz' }
+PS> ConvertTo-Json ($foo, $bar, $baz).Foo
+[
+ "Foo",
+ null,
+ null
+]
+PS> ConvertTo-Json ((Get-Process -Id $PID), $foo).Name
+[
+ "pwsh",
+ null
+]
+```
+
+You would expect PowerShell to return a single object for the item that has the
+property specified. Instead, PowerShell also returns a `$null` value for each
+item that doesn't have the property.
+
+For more information on this behavior, see PowerShell Issue [#13752][13752].
+
## See Also
-- [about_Arrays](about_Arrays.md)
-- [about_Intrinsic_Members](about_Intrinsic_Members.md)
-- [about_Methods](about_Methods.md)
-- [about_Operators](about_Operators.md)
-- [about_Properties](about_Properties.md)
+- [about_Arrays][01]
+- [about_Intrinsic_Members][03]
+- [about_Methods][05]
+- [about_Operators][06]
+- [about_Properties][07]
+
+<!-- link references -->
+[01]: about_Arrays.md
+[02]: about_Arrays.md#member-access-enumeration
+[03]: about_Intrinsic_Members.md
+[04]: about_Intrinsic_Members.md#methods
+[05]: about_Methods.md
+[06]: about_Operators.md
+[07]: about_Properties.md
+[13752]: https://github.com/PowerShell/PowerShell/issues/13752