about_ForEach discusses the foreach statement and ForEach-Object cmdlet without clear distinction

[mklement0]

The lack of distinction between the foreach statement and the ForEach-Object cmdlet has been a longstanding source of confusion.

Unfortunately, the current form of the about_ForEach topic actively contributes to that confusion.

The current topic talks about a "language statement" and then discusses both the statement and the cmdlet without clear distinction.

There are important differences between the statement and the cmdlet and they have distinct uses case, and these aspects are missing.

I think the topic should be rewritten to:

• focus on the foreach statement only
• contrasting it with the ForEach-Object cmdlet (warning of potential confusion, especially because of the foreach alias, performance vs. memory, expression vs. pipeline, support for $_, support for common parameters), and pointing to the latter's help topic as needed.

A few examples of the current confusion:

Terminology: "command" and "statement" are used in confusing ways.
To clarify: foreach in an expression context, is a statement. foreach, in an argument (command) context, is a command (that happens to be an alias of the ForEach-Object cmdlet).

syntax with language keywords such as Where and ForEach was simplified.

Where and ForEach, in this context, are aliases of cmdlets. (foreach is a language keyword, but not in the context of a pipeline.)

Arguably, the "Simplified Syntax" section shouldn't be there at all - the operation statement should only be explained in the ForEach-Object cmdlet's help topic, because it has nothing to do with the foreach statement.

The Foreach statement outside a command pipeline

This is confusing, because the foreach statement can only be used outside a pipeline; in the context of a pipeline, foreach is the alias of the ForEach-Object cmdlet.

The Foreach Statement Inside a Command Pipeline

See above.

The mitigating factor here is that the subsequent text does explain that foreach is an alias for ForEach-Object.

As in the "Simplified Syntax" section, the discussion of ForEach-Object specifics such as its 3 script blocks needn't be repeated here.

Version(s) of document impacted

• Impacts 6 document
• Impacts 5.1 document
• Impacts 5.0 document
• Impacts 4.0 document
• Impacts 3.0 document

[sdwheeler]

Fixed in PR #1897