Updates from: 07/10/2021 03:12:54
Service Microsoft Docs article Related commit history on GitHub Change details
Microsoft.PowerShell.Core About Automatic Variables (5.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md
--- description: Describes variables that store state information for PowerShell. These variables are created and maintained by PowerShell. Locale: en-US Previously updated : 05/13/2021 Last updated : 07/06/2021 no-loc: [Reset, Current] online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0
Contains the last token in the last line received by the session.
### $?
-Contains the execution status of the last command. It contains **True** if
-the last command succeeded and **False** if it failed.
+Contains the execution status of the last command. It contains **True** if the
+last command succeeded and **False** if it failed.
For cmdlets and advanced functions that are run at multiple stages in a pipeline, for example in both `process` and `end` blocks, calling
Contains the first token in the last line received by the session.
### $_
-Same as `$PSItem`. Contains the current object in the pipeline object. You
-can use this variable in commands that perform an action on every object or
-on selected objects in a pipeline.
+Same as `$PSItem`. Contains the current object in the pipeline object. You can
+use this variable in commands that perform an action on every object or on
+selected objects in a pipeline.
### $args
of parameters in parentheses after the function name.
In an event action, the `$Args` variable contains objects that represent the event arguments of the event that is being processed. This variable is
-populated only within the `Action` block of an event registration command.
-The value of this variable can also be found in the **SourceArgs** property of
-the **PSEventArgs** object that `Get-Event` returns.
+populated only within the `Action` block of an event registration command. The
+value of this variable can also be found in the **SourceArgs** property of the
+**PSEventArgs** object that `Get-Event` returns.
### $ConsoleFileName
-Contains the path of the console file (`.psc1`) that was most recently used
-in the session. This variable is populated when you start PowerShell with
-the **PSConsoleFile** parameter or when you use the `Export-Console` cmdlet to
+Contains the path of the console file (`.psc1`) that was most recently used in
+the session. This variable is populated when you start PowerShell with the
+**PSConsoleFile** parameter or when you use the `Export-Console` cmdlet to
export snap-in names to a console file. When you use the `Export-Console` cmdlet without parameters, it automatically
-updates the console file that was most recently used in the session. You
-can use this automatic variable to determine which file will be updated.
+updates the console file that was most recently used in the session. You can
+use this automatic variable to determine which file will be updated.
### $Error
-Contains an array of error objects that represent the most recent errors.
-The most recent error is the first error object in the array `$Error[0]`.
+Contains an array of error objects that represent the most recent errors. The
+most recent error is the first error object in the array `$Error[0]`.
To prevent an error from being added to the `$Error` array, use the **ErrorAction** common parameter with a value of **Ignore**. For more
information, see [about_CommonParameters](about_CommonParameters.md).
Contains a **PSEventArgs** object that represents the event that is being processed. This variable is populated only within the `Action` block of an event registration command, such as `Register-ObjectEvent`. The value of this
-variable is the same object that the `Get-Event` cmdlet returns. Therefore,
-you can use the properties of the `Event` variable, such as
-`$Event.TimeGenerated`, in an `Action` script block.
+variable is the same object that the `Get-Event` cmdlet returns. Therefore, you
+can use the properties of the `Event` variable, such as `$Event.TimeGenerated`,
+in an `Action` script block.
### $EventArgs
-Contains an object that represents the first event argument that derives
-from **EventArgs** of the event that is being processed. This variable is
-populated only within the `Action` block of an event registration command.
-The value of this variable can also be found in the **SourceEventArgs**
-property of the **PSEventArgs** object that `Get-Event` returns.
+Contains an object that represents the first event argument that derives from
+**EventArgs** of the event that is being processed. This variable is populated
+only within the `Action` block of an event registration command. The value of
+this variable can also be found in the **SourceEventArgs** property of the
+**PSEventArgs** object that `Get-Event` returns.
### $EventSubscriber Contains a **PSEventSubscriber** object that represents the event subscriber of
-the event that is being processed. This variable is populated only within
-the `Action` block of an event registration command. The value of this
-variable is the same object that the `Get-EventSubscriber` cmdlet returns.
+the event that is being processed. This variable is populated only within the
+`Action` block of an event registration command. The value of this variable is
+the same object that the `Get-EventSubscriber` cmdlet returns.
### $ExecutionContext Contains an **EngineIntrinsics** object that represents the execution context
-of the PowerShell host. You can use this variable to find the execution
-objects that are available to cmdlets.
+of the PowerShell host. You can use this variable to find the execution objects
+that are available to cmdlets.
### $false
non-zero integer.
### $foreach
-Contains the enumerator (not the resulting values) of a
-[ForEach](about_ForEach.md) loop. The `$ForEach` variable exists only while
-the `ForEach` loop is running; it's deleted after the loop is completed.
+Contains the enumerator (not the resulting values) of a [ForEach](about_ForEach.md)
+loop. The `$ForEach` variable exists only while the `ForEach` loop is running;
+it's deleted after the loop is completed.
Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
### $HOME Contains the full path of the user's home directory. This variable is the
-equivalent of the `"$env:homedrive$env:homepath"` Windows environment variables,
-typically `C:\Users\<UserName>`.
+equivalent of the `"$env:homedrive$env:homepath"` Windows environment
+variables, typically `C:\Users\<UserName>`.
### $Host
-Contains an object that represents the current host application for
-PowerShell. You can use this variable to represent the current host in
-commands or to display or change the properties of the host, such as
-`$Host.version` or `$Host.CurrentCulture`, or
-`$host.ui.rawui.setbackgroundcolor("Red")`.
+Contains an object that represents the current host application for PowerShell.
+You can use this variable to represent the current host in commands or to
+display or change the properties of the host, such as `$Host.version` or
+`$Host.CurrentCulture`, or `$host.ui.rawui.setbackgroundcolor("Red")`.
### $input
-Contains an enumerator that enumerates all input that is passed to a
-function. The `$input` variable is available only to functions and script
-blocks (which are unnamed functions).
+Contains an enumerator that enumerates all input that is passed to a function.
+The `$input` variable is available only to functions and script blocks (which
+are unnamed functions).
- In a function without a `Begin`, `Process`, or `End` block, the `$input` variable enumerates the collection of all input to the function. - In the `Begin` block, the `$input` variable contains no data. -- In the `Process` block, the `$input` variable contains the
- object that is currently in the pipeline.
+- In the `Process` block, the `$input` variable contains the object that is
+ currently in the pipeline.
- In the `End` block, the `$input` variable enumerates the collection of all input to the function.
blocks (which are unnamed functions).
> End block in the same function or script block. Since `$input` is an enumerator, accessing any of it's properties causes
-`$input` to no longer be available. You can store `$input` in another variable to
-reuse the `$input` properties.
+`$input` to no longer be available. You can store `$input` in another variable
+to reuse the `$input` properties.
Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
The `$input` variable is also available to the command specified by the `-Command` parameter of `pwsh` when invoked from the command line. The
Contains the exit code of the last Windows-based program that was run.
### $Matches
-The `$Matches` variable works with the `-match` and `-notmatch` operators.
-When you submit scalar input to the `-match` or `-notmatch` operator, and
-either one detects a match, they return a Boolean value and populate the
-`$Matches` automatic variable with a hash table of any string values that
-were matched. The `$Matches` hash table can also be populated with captures
-when you use regular expressions with the `-match` operator.
+The `$Matches` variable works with the `-match` and `-notmatch` operators. When
+you submit scalar input to the `-match` or `-notmatch` operator, and either one
+detects a match, they return a Boolean value and populate the `$Matches`
+automatic variable with a hash table of any string values that were matched.
+The `$Matches` hash table can also be populated with captures when you use
+regular expressions with the `-match` operator.
For more information about the `-match` operator, see [about_Comparison_Operators](about_comparison_operators.md). For more
The `$Matches` variable also works in a `switch` statement with the `-Regex`
parameter. It's populated the same way as the `-match` and `-notmatch` operators. For more information about the `switch` statement, see [about_Switch](about_Switch.md).
+> [!NOTE]
+> When `$Matches` is populated in a session, it retains the matched value until
+> it's overwritten by another match. If `-match` is used again and no match is
+> found, it doesn't reset `$Matches` to `$null`. The previously matched value is
+> kept in `$Matches` until another match is found.
+ ### $MyInvocation Contains information about the current command, such as the name, parameters,
file name of the script (`$MyInvocation.MyCommand.Path`) or the name of a
function (`$MyInvocation.MyCommand.Name`) to identify the current command. This is particularly useful for finding the name of the current script.
-Beginning in PowerShell 3.0, `MyInvocation` has the following new
-properties.
+Beginning in PowerShell 3.0, `MyInvocation` has the following new properties.
- **PSScriptRoot** - Contains the full path to the script that invoked the current command. The value of this property is populated only when the caller
the current script.
### $NestedPromptLevel
-Contains the current prompt level. A value of 0 indicates the original
-prompt level. The value is incremented when you enter a nested level and
-decremented when you exit it.
+Contains the current prompt level. A value of 0 indicates the original prompt
+level. The value is incremented when you enter a nested level and decremented
+when you exit it.
For example, PowerShell presents a nested command prompt when you use the `$Host.EnterNestedPrompt` method. PowerShell also presents a nested command prompt when you reach a breakpoint in the PowerShell debugger.
-When you enter a nested prompt, PowerShell pauses the current command,
-saves the execution context, and increments the value of the
-`$NestedPromptLevel` variable. To create additional nested command prompts
-(up to 128 levels) or to return to the original command prompt, complete
-the command, or type `exit`.
+When you enter a nested prompt, PowerShell pauses the current command, saves
+the execution context, and increments the value of the `$NestedPromptLevel`
+variable. To create additional nested command prompts (up to 128 levels) or to
+return to the original command prompt, complete the command, or type `exit`.
The `$NestedPromptLevel` variable helps you track the prompt level. You can create an alternative PowerShell command prompt that includes this value so
can use this variable to represent an absent or undefined value in commands and
scripts. PowerShell treats `$null` as an object with a value, that is, as an explicit
-placeholder, so you can use `$null` to represent an empty value in a series
-of values.
+placeholder, so you can use `$null` to represent an empty value in a series of
+values.
For example, when `$null` is included in a collection, it's counted as one of the objects.
current PowerShell session.
### $PROFILE
-Contains the full path of the PowerShell profile for the current user and
-the current host application. You can use this variable to represent the
-profile in commands. For example, you can use it in a command to determine
-whether a profile has been created:
+Contains the full path of the PowerShell profile for the current user and the
+current host application. You can use this variable to represent the profile in
+commands. For example, you can use it in a command to determine whether a
+profile has been created:
```powershell Test-Path $PROFILE
notepad.exe $PROFILE
### $PSBoundParameters
-Contains a dictionary of the parameters that are passed to a script or
-function and their current values. This variable has a value only in a
-scope where parameters are declared, such as a script or function. You can
-use it to display or change the current values of parameters or to pass
-parameter values to another script or function.
+Contains a dictionary of the parameters that are passed to a script or function
+and their current values. This variable has a value only in a scope where
+parameters are declared, such as a script or function. You can use it to
+display or change the current values of parameters or to pass parameter values
+to another script or function.
In this example, the **Test2** function passes the `$PSBoundParameters` to the **Test1** function. The `$PSBoundParameters` are displayed in the format of
b Shell
### $PSCmdlet
-Contains an object that represents the cmdlet or advanced function that's
-being run.
+Contains an object that represents the cmdlet or advanced function that's being
+run.
-You can use the properties and methods of the object in your cmdlet or
-function code to respond to the conditions of use. For example, the
-**ParameterSetName** property contains the name of the parameter set that's
-being used, and the **ShouldProcess** method adds the **WhatIf** and
-**Confirm** parameters to the cmdlet dynamically.
+You can use the properties and methods of the object in your cmdlet or function
+code to respond to the conditions of use. For example, the **ParameterSetName**
+property contains the name of the parameter set that's being used, and the
+**ShouldProcess** method adds the **WhatIf** and **Confirm** parameters to the
+cmdlet dynamically.
-For more information about the `$PSCmdlet` automatic variable, see
-[about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md)
+For more information about the `$PSCmdlet` automatic variable, see [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md)
and [about_Functions_Advanced](about_Functions_Advanced.md). ### $PSCommandPath
path of the script that is being debugged.
### $PSHOME
-Contains the full path of the installation directory for PowerShell,
-typically, `$env:windir\System32\PowerShell\v1.0` in Windows systems. You can
-use this variable in the paths of PowerShell files. For example, the
-following command searches the conceptual Help topics for the word
-**variable**:
+Contains the full path of the installation directory for PowerShell, typically,
+`$env:windir\System32\PowerShell\v1.0` in Windows systems. You can use this
+variable in the paths of PowerShell files. For example, the following command
+searches the conceptual Help topics for the word **variable**:
```powershell Select-String -Pattern Variable -Path $pshome\*.txt
Select-String -Pattern Variable -Path $pshome\*.txt
### $PSItem Same as `$_`. Contains the current object in the pipeline object. You can use
-this variable in commands that perform an action on every object or on
-selected objects in a pipeline.
+this variable in commands that perform an action on every object or on selected
+objects in a pipeline.
### $PSScriptRoot
Beginning in PowerShell 3.0, it's valid in all scripts.
### $PSSenderInfo
-Contains information about the user who started the PSSession, including
-the user identity and the time zone of the originating computer. This
-variable is available only in PSSessions.
+Contains information about the user who started the PSSession, including the
+user identity and the time zone of the originating computer. This variable is
+available only in PSSessions.
The `$PSSenderInfo` variable includes a user-configurable property, **ApplicationArguments**, that by default, contains only the `$PSVersionTable`
property, use the **ApplicationArguments** parameter of the
### $PSUICulture
-Contains the name of the user interface (UI) culture that's currently in use
-in the operating system. The UI culture determines which text strings are used
-for user interface elements, such as menus and messages. This is the value of
-the **System.Globalization.CultureInfo.CurrentUICulture.Name** property of the
+Contains the name of the user interface (UI) culture that's currently in use in
+the operating system. The UI culture determines which text strings are used for
+user interface elements, such as menus and messages. This is the value of the
+**System.Globalization.CultureInfo.CurrentUICulture.Name** property of the
system. To get the **System.Globalization.CultureInfo** object for the system, use the `Get-UICulture` cmdlet.
location for the current PowerShell runspace.
### $Sender
-Contains the object that generated this event. This variable is populated
-only within the Action block of an event registration command. The value of
-this variable can also be found in the Sender property of the **PSEventArgs**
-object that `Get-Event` returns.
+Contains the object that generated this event. This variable is populated only
+within the Action block of an event registration command. The value of this
+variable can also be found in the Sender property of the **PSEventArgs** object
+that `Get-Event` returns.
### $ShellId
deleted when the `switch` statement completes execution. For more information,
see [about_Switch](about_Switch.md). Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
### $this
-In a script block that defines a script property or script method, the
-`$this` variable refers to the object that is being extended.
+In a script block that defines a script property or script method, the `$this`
+variable refers to the object that is being extended.
In a custom class, the `$this` variable refers to the class object itself allowing access to properties and methods defined in the class.
and scripts.
## Using Enumerators
-The `$input`, `$foreach`, and `$switch` variables are all enumerators used
-to iterate through the values processed by their containing code block.
+The `$input`, `$foreach`, and `$switch` variables are all enumerators used to
+iterate through the values processed by their containing code block.
An enumerator contains properties and methods you can use to advance or reset iteration, or retrieve iteration values. Directly manipulating enumerators isn't considered best practice. -- Within loops, flow control keywords [break](about_Break.md) and
- [continue](about_Continue.md) should be preferred.
+- Within loops, flow control keywords [break](about_Break.md) and [continue](about_Continue.md)
+ should be preferred.
- Within functions that accept pipeline input, it's best practice to use parameters with the **ValueFromPipeline** or **ValueFromPipelineByPropertyName** attributes.
enumerator has passed the end of the collection.
### Reset
-The [Reset](/dotnet/api/system.collections.ienumerator.reset) method sets
-the enumerator to its initial position, which is **before** the first element
-in the collection.
+The [Reset](/dotnet/api/system.collections.ienumerator.reset) method sets the
+enumerator to its initial position, which is **before** the first element in
+the collection.
### Current
-The [Current](/dotnet/api/system.collections.ienumerator.current) property
-gets the element in the collection, or pipeline, at the current position of
-the enumerator.
+The [Current](/dotnet/api/system.collections.ienumerator.current) property gets
+the element in the collection, or pipeline, at the current position of the
+enumerator.
The **Current** property continues to return the same property until **MoveNext** is called.
Iteration: 1
### Example 4: Using the $foreach variable Unlike the `$input` variable, the `$foreach` variable always represents all
-items in the collection when accessed directly. Use the **Current** property
-to access the current collection element, and the **Reset** and **MoveNext**
+items in the collection when accessed directly. Use the **Current** property to
+access the current collection element, and the **Reset** and **MoveNext**
methods to change its value. > [!NOTE]
methods to change its value.
> method. The following loop only executes twice. In the second iteration, the collection
-is moved to the third element before the iteration is complete. After the second
-iteration, there are now no more values to iterate, and the loop terminates.
+is moved to the third element before the iteration is complete. After the
+second iteration, there are now no more values to iterate, and the loop
+terminates.
The **MoveNext** property doesn't affect the variable chosen to iterate through the collection (`$Num`).
Num has not changed: two
Using the **Reset** method resets the current element in the collection. The following example loops through the first two elements _twice_ because the
-**Reset** method is called. After the first two loops, the `if` statement
-fails and the loop iterates through all three elements normally.
+**Reset** method is called. After the first two loops, the `if` statement fails
+and the loop iterates through all three elements normally.
> [!IMPORTANT] > This could result in an infinite loop.
Reset Loop: 0
### Example 5: Using the $switch variable
-The `$switch` variable has the exact same rules as the `$foreach` variable.
-The following example demonstrates all the enumerator concepts.
+The `$switch` variable has the exact same rules as the `$foreach` variable. The
+following example demonstrates all the enumerator concepts.
> [!NOTE] > Note how the **NotEvaluated** case is never executed, even though there's
Microsoft.PowerShell.Core About Comparison Operators (5.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md
--- description: Describes the operators that compare values in PowerShell. Locale: en-US Previously updated : 06/21/2021 Last updated : 07/06/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Comparison Operators
There are a few exceptions:
When the left-hand side is scalar, `-eq` returns **True** if the right-hand side is an exact match, otherwise, `-eq` returns **False**. `-ne` does the opposite; it returns **False** when both sides match; otherwise, `-ne` returns
-True.
+**True**.
Example:
equality test result is **False** because they are different objects. To create
comparable classes, you need to implement [System.IEquatable\<T>][2] in your class. The following example demonstrates the partial implementation of a **MyFileInfoSet** class that implements [System.IEquatable\<T>][2] and has two
-properties, **File** and **Size**. The `Equals()` method returns True if the
+properties, **File** and **Size**. The `Equals()` method returns **True** if the
File and Size properties of two **MyFileInfoSet** objects are the same. ```powershell
they return **True** or **False** depending on how the two sides compare:
| -lt | The left-hand side is smaller | | -le | The left-hand side is smaller or equal |
-In the following examples, all statements return True.
+In the following examples, all statements return **True**.
```powershell 8 -gt 6 # Output: True
User name:
jsmith ```
-For details, see [about_Regular_Expressions](about_Regular_Expressions.md).
+For details, see [about_Regular_Expressions](about_Regular_Expressions.md) and
+[about_Automatic_Variables](about_Automatic_Variables.md).
## Replacement operator
Syntax:
### -contains and -notcontains These operators tell whether a set includes a certain element. `-contains`
-returns True when the right-hand side (test object) matches one of the elements
+returns **True** when the right-hand side (test object) matches one of the elements
in the set. `-notcontains` returns False instead. When the test object is a collection, these operators use reference equality, i.e. they check whether one of the set's elements is the same instance of the test object.
Microsoft.PowerShell.Core About Automatic Variables (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md
--- description: Describes variables that store state information for PowerShell. These variables are created and maintained by PowerShell. Locale: en-US Previously updated : 05/13/2021 Last updated : 07/06/2021 no-loc: [Reset, Current] online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0
Contains the last token in the last line received by the session.
### $?
-Contains the execution status of the last command. It contains **True** if
-the last command succeeded and **False** if it failed.
+Contains the execution status of the last command. It contains **True** if the
+last command succeeded and **False** if it failed.
For cmdlets and advanced functions that are run at multiple stages in a pipeline, for example in both `process` and `end` blocks, calling
Contains the first token in the last line received by the session.
### $_
-Same as `$PSItem`. Contains the current object in the pipeline object. You
-can use this variable in commands that perform an action on every object or
-on selected objects in a pipeline.
+Same as `$PSItem`. Contains the current object in the pipeline object. You can
+use this variable in commands that perform an action on every object or on
+selected objects in a pipeline.
### $args
of parameters in parentheses after the function name.
In an event action, the `$Args` variable contains objects that represent the event arguments of the event that is being processed. This variable is
-populated only within the `Action` block of an event registration command.
-The value of this variable can also be found in the **SourceArgs** property of
-the **PSEventArgs** object that `Get-Event` returns.
+populated only within the `Action` block of an event registration command. The
+value of this variable can also be found in the **SourceArgs** property of the
+**PSEventArgs** object that `Get-Event` returns.
### $ConsoleFileName
-Contains the path of the console file (`.psc1`) that was most recently used
-in the session. This variable is populated when you start PowerShell with
-the **PSConsoleFile** parameter or when you use the `Export-Console` cmdlet to
+Contains the path of the console file (`.psc1`) that was most recently used in
+the session. This variable is populated when you start PowerShell with the
+**PSConsoleFile** parameter or when you use the `Export-Console` cmdlet to
export snap-in names to a console file. When you use the `Export-Console` cmdlet without parameters, it automatically
-updates the console file that was most recently used in the session. You
-can use this automatic variable to determine which file will be updated.
+updates the console file that was most recently used in the session. You can
+use this automatic variable to determine which file will be updated.
### $Error
-Contains an array of error objects that represent the most recent errors.
-The most recent error is the first error object in the array `$Error[0]`.
+Contains an array of error objects that represent the most recent errors. The
+most recent error is the first error object in the array `$Error[0]`.
To prevent an error from being added to the `$Error` array, use the **ErrorAction** common parameter with a value of **Ignore**. For more
information, see [about_CommonParameters](about_CommonParameters.md).
Contains a **PSEventArgs** object that represents the event that is being processed. This variable is populated only within the `Action` block of an event registration command, such as `Register-ObjectEvent`. The value of this
-variable is the same object that the `Get-Event` cmdlet returns. Therefore,
-you can use the properties of the `Event` variable, such as
-`$Event.TimeGenerated`, in an `Action` script block.
+variable is the same object that the `Get-Event` cmdlet returns. Therefore, you
+can use the properties of the `Event` variable, such as `$Event.TimeGenerated`,
+in an `Action` script block.
### $EventArgs
-Contains an object that represents the first event argument that derives
-from **EventArgs** of the event that is being processed. This variable is
-populated only within the `Action` block of an event registration command.
-The value of this variable can also be found in the **SourceEventArgs**
-property of the **PSEventArgs** object that `Get-Event` returns.
+Contains an object that represents the first event argument that derives from
+**EventArgs** of the event that is being processed. This variable is populated
+only within the `Action` block of an event registration command. The value of
+this variable can also be found in the **SourceEventArgs** property of the
+**PSEventArgs** object that `Get-Event` returns.
### $EventSubscriber Contains a **PSEventSubscriber** object that represents the event subscriber of
-the event that is being processed. This variable is populated only within
-the `Action` block of an event registration command. The value of this
-variable is the same object that the `Get-EventSubscriber` cmdlet returns.
+the event that is being processed. This variable is populated only within the
+`Action` block of an event registration command. The value of this variable is
+the same object that the `Get-EventSubscriber` cmdlet returns.
### $ExecutionContext Contains an **EngineIntrinsics** object that represents the execution context
-of the PowerShell host. You can use this variable to find the execution
-objects that are available to cmdlets.
+of the PowerShell host. You can use this variable to find the execution objects
+that are available to cmdlets.
### $false
non-zero integer.
### $foreach
-Contains the enumerator (not the resulting values) of a
-[ForEach](about_ForEach.md) loop. The `$ForEach` variable exists only while
-the `ForEach` loop is running; it's deleted after the loop is completed.
+Contains the enumerator (not the resulting values) of a [ForEach](about_ForEach.md)
+loop. The `$ForEach` variable exists only while the `ForEach` loop is running;
+it's deleted after the loop is completed.
Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
### $HOME Contains the full path of the user's home directory. This variable is the
-equivalent of the `"$env:homedrive$env:homepath"` Windows environment variables,
-typically `C:\Users\<UserName>`.
+equivalent of the `"$env:homedrive$env:homepath"` Windows environment
+variables, typically `C:\Users\<UserName>`.
### $Host
-Contains an object that represents the current host application for
-PowerShell. You can use this variable to represent the current host in
-commands or to display or change the properties of the host, such as
-`$Host.version` or `$Host.CurrentCulture`, or
-`$host.ui.rawui.setbackgroundcolor("Red")`.
+Contains an object that represents the current host application for PowerShell.
+You can use this variable to represent the current host in commands or to
+display or change the properties of the host, such as `$Host.version` or
+`$Host.CurrentCulture`, or `$host.ui.rawui.setbackgroundcolor("Red")`.
### $input
-Contains an enumerator that enumerates all input that is passed to a
-function. The `$input` variable is available only to functions and script
-blocks (which are unnamed functions).
+Contains an enumerator that enumerates all input that is passed to a function.
+The `$input` variable is available only to functions and script blocks (which
+are unnamed functions).
- In a function without a `Begin`, `Process`, or `End` block, the `$input` variable enumerates the collection of all input to the function. - In the `Begin` block, the `$input` variable contains no data. -- In the `Process` block, the `$input` variable contains the
- object that is currently in the pipeline.
+- In the `Process` block, the `$input` variable contains the object that is
+ currently in the pipeline.
- In the `End` block, the `$input` variable enumerates the collection of all input to the function.
blocks (which are unnamed functions).
> End block in the same function or script block. Since `$input` is an enumerator, accessing any of it's properties causes
-`$input` to no longer be available. You can store `$input` in another variable to
-reuse the `$input` properties.
+`$input` to no longer be available. You can store `$input` in another variable
+to reuse the `$input` properties.
Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
The `$input` variable is also available to the command specified by the `-Command` parameter of `pwsh` when invoked from the command line. The
Contains the exit code of the last native program that was run.
### $Matches
-The `Matches` variable works with the `-match` and `-notmatch` operators.
-When you submit scalar input to the `-match` or `-notmatch` operator, and
-either one detects a match, they return a Boolean value and populate the
-`$Matches` automatic variable with a hash table of any string values that
-were matched. The `$Matches` hash table can also be populated with captures
-when you use regular expressions with the `-match` operator.
+The `$Matches` variable works with the `-match` and `-notmatch` operators. When
+you submit scalar input to the `-match` or `-notmatch` operator, and either one
+detects a match, they return a Boolean value and populate the `$Matches`
+automatic variable with a hash table of any string values that were matched.
+The `$Matches` hash table can also be populated with captures when you use
+regular expressions with the `-match` operator.
For more information about the `-match` operator, see [about_Comparison_Operators](about_comparison_operators.md). For more
The `$Matches` variable also works in a `switch` statement with the `-Regex`
parameter. It's populated the same way as the `-match` and `-notmatch` operators. For more information about the `switch` statement, see [about_Switch](about_Switch.md).
+> [!NOTE]
+> When `$Matches` is populated in a session, it retains the matched value until
+> it's overwritten by another match. If `-match` is used again and no match is
+> found, it doesn't reset `$Matches` to `$null`. The previously matched value is
+> kept in `$Matches` until another match is found.
+ ### $MyInvocation Contains information about the current command, such as the name, parameters,
file name of the script (`$MyInvocation.MyCommand.Path`) or the name of a
function (`$MyInvocation.MyCommand.Name`) to identify the current command. This is particularly useful for finding the name of the current script.
-Beginning in PowerShell 3.0, `MyInvocation` has the following new
-properties.
+Beginning in PowerShell 3.0, `MyInvocation` has the following new properties.
- **PSScriptRoot** - Contains the full path to the script that invoked the current command. The value of this property is populated only when the caller
the current script.
### $NestedPromptLevel
-Contains the current prompt level. A value of 0 indicates the original
-prompt level. The value is incremented when you enter a nested level and
-decremented when you exit it.
+Contains the current prompt level. A value of 0 indicates the original prompt
+level. The value is incremented when you enter a nested level and decremented
+when you exit it.
For example, PowerShell presents a nested command prompt when you use the `$Host.EnterNestedPrompt` method. PowerShell also presents a nested command prompt when you reach a breakpoint in the PowerShell debugger.
-When you enter a nested prompt, PowerShell pauses the current command,
-saves the execution context, and increments the value of the
-`$NestedPromptLevel` variable. To create additional nested command prompts
-(up to 128 levels) or to return to the original command prompt, complete
-the command, or type `exit`.
+When you enter a nested prompt, PowerShell pauses the current command, saves
+the execution context, and increments the value of the `$NestedPromptLevel`
+variable. To create additional nested command prompts (up to 128 levels) or to
+return to the original command prompt, complete the command, or type `exit`.
The `$NestedPromptLevel` variable helps you track the prompt level. You can create an alternative PowerShell command prompt that includes this value so
can use this variable to represent an absent or undefined value in commands and
scripts. PowerShell treats `$null` as an object with a value, that is, as an explicit
-placeholder, so you can use `$null` to represent an empty value in a series
-of values.
+placeholder, so you can use `$null` to represent an empty value in a series of
+values.
For example, when `$null` is included in a collection, it's counted as one of the objects.
current PowerShell session.
### $PROFILE
-Contains the full path of the PowerShell profile for the current user and
-the current host application. You can use this variable to represent the
-profile in commands. For example, you can use it in a command to determine
-whether a profile has been created:
+Contains the full path of the PowerShell profile for the current user and the
+current host application. You can use this variable to represent the profile in
+commands. For example, you can use it in a command to determine whether a
+profile has been created:
```powershell Test-Path $PROFILE
notepad.exe $PROFILE
### $PSBoundParameters
-Contains a dictionary of the parameters that are passed to a script or
-function and their current values. This variable has a value only in a
-scope where parameters are declared, such as a script or function. You can
-use it to display or change the current values of parameters or to pass
-parameter values to another script or function.
+Contains a dictionary of the parameters that are passed to a script or function
+and their current values. This variable has a value only in a scope where
+parameters are declared, such as a script or function. You can use it to
+display or change the current values of parameters or to pass parameter values
+to another script or function.
In this example, the **Test2** function passes the `$PSBoundParameters` to the **Test1** function. The `$PSBoundParameters` are displayed in the format of
b Shell
### $PSCmdlet
-Contains an object that represents the cmdlet or advanced function that's
-being run.
+Contains an object that represents the cmdlet or advanced function that's being
+run.
-You can use the properties and methods of the object in your cmdlet or
-function code to respond to the conditions of use. For example, the
-**ParameterSetName** property contains the name of the parameter set that's
-being used, and the **ShouldProcess** method adds the **WhatIf** and
-**Confirm** parameters to the cmdlet dynamically.
+You can use the properties and methods of the object in your cmdlet or function
+code to respond to the conditions of use. For example, the **ParameterSetName**
+property contains the name of the parameter set that's being used, and the
+**ShouldProcess** method adds the **WhatIf** and **Confirm** parameters to the
+cmdlet dynamically.
-For more information about the `$PSCmdlet` automatic variable, see
-[about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md)
+For more information about the `$PSCmdlet` automatic variable, see [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md)
and [about_Functions_Advanced](about_Functions_Advanced.md). ### $PSCommandPath
path of the script that is being debugged.
### $PSHOME
-Contains the full path of the installation directory for PowerShell,
-typically, `$env:windir\System32\PowerShell\v1.0` in Windows systems. You can
-use this variable in the paths of PowerShell files. For example, the
-following command searches the conceptual Help topics for the word
-**variable**:
+Contains the full path of the installation directory for PowerShell, typically,
+`$env:windir\System32\PowerShell\v1.0` in Windows systems. You can use this
+variable in the paths of PowerShell files. For example, the following command
+searches the conceptual Help topics for the word **variable**:
```powershell Select-String -Pattern Variable -Path $pshome\*.txt
Select-String -Pattern Variable -Path $pshome\*.txt
### $PSItem Same as `$_`. Contains the current object in the pipeline object. You can use
-this variable in commands that perform an action on every object or on
-selected objects in a pipeline.
+this variable in commands that perform an action on every object or on selected
+objects in a pipeline.
### $PSScriptRoot
Beginning in PowerShell 3.0, it's valid in all scripts.
### $PSSenderInfo
-Contains information about the user who started the PSSession, including
-the user identity and the time zone of the originating computer. This
-variable is available only in PSSessions.
+Contains information about the user who started the PSSession, including the
+user identity and the time zone of the originating computer. This variable is
+available only in PSSessions.
The `$PSSenderInfo` variable includes a user-configurable property, **ApplicationArguments**, that by default, contains only the `$PSVersionTable`
property, use the **ApplicationArguments** parameter of the
### $PSUICulture
-Contains the name of the user interface (UI) culture that's currently in use
-in the operating system. The UI culture determines which text strings are used
-for user interface elements, such as menus and messages. This is the value of
-the **System.Globalization.CultureInfo.CurrentUICulture.Name** property of the
+Contains the name of the user interface (UI) culture that's currently in use in
+the operating system. The UI culture determines which text strings are used for
+user interface elements, such as menus and messages. This is the value of the
+**System.Globalization.CultureInfo.CurrentUICulture.Name** property of the
system. To get the **System.Globalization.CultureInfo** object for the system, use the `Get-UICulture` cmdlet.
location for the current PowerShell runspace.
### $Sender
-Contains the object that generated this event. This variable is populated
-only within the Action block of an event registration command. The value of
-this variable can also be found in the Sender property of the **PSEventArgs**
-object that `Get-Event` returns.
+Contains the object that generated this event. This variable is populated only
+within the Action block of an event registration command. The value of this
+variable can also be found in the Sender property of the **PSEventArgs** object
+that `Get-Event` returns.
### $ShellId
deleted when the `switch` statement completes execution. For more information,
see [about_Switch](about_Switch.md). Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
### $this
-In a script block that defines a script property or script method, the
-`$this` variable refers to the object that is being extended.
+In a script block that defines a script property or script method, the `$this`
+variable refers to the object that is being extended.
In a custom class, the `$this` variable refers to the class object itself allowing access to properties and methods defined in the class.
and scripts.
## Using Enumerators
-The `$input`, `$foreach`, and `$switch` variables are all enumerators used
-to iterate through the values processed by their containing code block.
+The `$input`, `$foreach`, and `$switch` variables are all enumerators used to
+iterate through the values processed by their containing code block.
An enumerator contains properties and methods you can use to advance or reset iteration, or retrieve iteration values. Directly manipulating enumerators isn't considered best practice. -- Within loops, flow control keywords [break](about_Break.md) and
- [continue](about_Continue.md) should be preferred.
+- Within loops, flow control keywords [break](about_Break.md) and [continue](about_Continue.md)
+ should be preferred.
- Within functions that accept pipeline input, it's best practice to use parameters with the **ValueFromPipeline** or **ValueFromPipelineByPropertyName** attributes.
enumerator has passed the end of the collection.
### Reset
-The [Reset](/dotnet/api/system.collections.ienumerator.reset) method sets
-the enumerator to its initial position, which is **before** the first element
-in the collection.
+The [Reset](/dotnet/api/system.collections.ienumerator.reset) method sets the
+enumerator to its initial position, which is **before** the first element in
+the collection.
### Current
-The [Current](/dotnet/api/system.collections.ienumerator.current) property
-gets the element in the collection, or pipeline, at the current position of
-the enumerator.
+The [Current](/dotnet/api/system.collections.ienumerator.current) property gets
+the element in the collection, or pipeline, at the current position of the
+enumerator.
The **Current** property continues to return the same property until **MoveNext** is called.
Iteration: 1
### Example 4: Using the $foreach variable Unlike the `$input` variable, the `$foreach` variable always represents all
-items in the collection when accessed directly. Use the **Current** property
-to access the current collection element, and the **Reset** and **MoveNext**
+items in the collection when accessed directly. Use the **Current** property to
+access the current collection element, and the **Reset** and **MoveNext**
methods to change its value. > [!NOTE]
methods to change its value.
> method. The following loop only executes twice. In the second iteration, the collection
-is moved to the third element before the iteration is complete. After the second
-iteration, there are now no more values to iterate, and the loop terminates.
+is moved to the third element before the iteration is complete. After the
+second iteration, there are now no more values to iterate, and the loop
+terminates.
The **MoveNext** property doesn't affect the variable chosen to iterate through the collection (`$Num`).
Num has not changed: two
Using the **Reset** method resets the current element in the collection. The following example loops through the first two elements _twice_ because the
-**Reset** method is called. After the first two loops, the `if` statement
-fails and the loop iterates through all three elements normally.
+**Reset** method is called. After the first two loops, the `if` statement fails
+and the loop iterates through all three elements normally.
> [!IMPORTANT] > This could result in an infinite loop.
Reset Loop: 0
### Example 5: Using the $switch variable
-The `$switch` variable has the exact same rules as the `$foreach` variable.
-The following example demonstrates all the enumerator concepts.
+The `$switch` variable has the exact same rules as the `$foreach` variable. The
+following example demonstrates all the enumerator concepts.
> [!NOTE] > Note how the **NotEvaluated** case is never executed, even though there's
Microsoft.PowerShell.Core About Comparison Operators (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md
--- description: Describes the operators that compare values in PowerShell. Locale: en-US Previously updated : 06/21/2021 Last updated : 07/06/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Comparison Operators
There are a few exceptions:
When the left-hand side is scalar, `-eq` returns **True** if the right-hand side is an exact match, otherwise, `-eq` returns **False**. `-ne` does the opposite; it returns **False** when both sides match; otherwise, `-ne` returns
-True.
+**True**.
Example:
equality test result is **False** because they are different objects. To create
comparable classes, you need to implement [System.IEquatable\<T>][2] in your class. The following example demonstrates the partial implementation of a **MyFileInfoSet** class that implements [System.IEquatable\<T>][2] and has two
-properties, **File** and **Size**. The `Equals()` method returns True if the
+properties, **File** and **Size**. The `Equals()` method returns **True** if the
File and Size properties of two **MyFileInfoSet** objects are the same. ```powershell
they return **True** or **False** depending on how the two sides compare:
| -lt | The left-hand side is smaller | | -le | The left-hand side is smaller or equal |
-In the following examples, all statements return True.
+In the following examples, all statements return **True**.
```powershell 8 -gt 6 # Output: True
User name:
jsmith ```
-For details, see [about_Regular_Expressions](about_Regular_Expressions.md).
+For details, see [about_Regular_Expressions](about_Regular_Expressions.md) and
+[about_Automatic_Variables](about_Automatic_Variables.md).
## Replacement operator
Syntax:
### -contains and -notcontains These operators tell whether a set includes a certain element. `-contains`
-returns True when the right-hand side (test object) matches one of the elements
+returns **True** when the right-hand side (test object) matches one of the elements
in the set. `-notcontains` returns False instead. When the test object is a collection, these operators use reference equality, i.e. they check whether one of the set's elements is the same instance of the test object.
Microsoft.PowerShell.Core About Automatic Variables (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md
--- description: Describes variables that store state information for PowerShell. These variables are created and maintained by PowerShell. Locale: en-US Previously updated : 05/13/2021 Last updated : 07/06/2021 no-loc: [Reset, Current] online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0
Contains the last token in the last line received by the session.
### $?
-Contains the execution status of the last command. It contains **True** if
-the last command succeeded and **False** if it failed.
+Contains the execution status of the last command. It contains **True** if the
+last command succeeded and **False** if it failed.
For cmdlets and advanced functions that are run at multiple stages in a pipeline, for example in both `process` and `end` blocks, calling
Contains the first token in the last line received by the session.
### $_
-Same as `$PSItem`. Contains the current object in the pipeline object. You
-can use this variable in commands that perform an action on every object or
-on selected objects in a pipeline.
+Same as `$PSItem`. Contains the current object in the pipeline object. You can
+use this variable in commands that perform an action on every object or on
+selected objects in a pipeline.
### $args
of parameters in parentheses after the function name.
In an event action, the `$args` variable contains objects that represent the event arguments of the event that is being processed. This variable is
-populated only within the `Action` block of an event registration command.
-The value of this variable can also be found in the **SourceArgs** property of
-the **PSEventArgs** object that `Get-Event` returns.
+populated only within the `Action` block of an event registration command. The
+value of this variable can also be found in the **SourceArgs** property of the
+**PSEventArgs** object that `Get-Event` returns.
### $ConsoleFileName
-Contains the path of the console file (`.psc1`) that was most recently used
-in the session. This variable is populated when you start PowerShell with
-the **PSConsoleFile** parameter or when you use the `Export-Console` cmdlet to
+Contains the path of the console file (`.psc1`) that was most recently used in
+the session. This variable is populated when you start PowerShell with the
+**PSConsoleFile** parameter or when you use the `Export-Console` cmdlet to
export snap-in names to a console file. When you use the `Export-Console` cmdlet without parameters, it automatically
-updates the console file that was most recently used in the session. You
-can use this automatic variable to determine which file will be updated.
+updates the console file that was most recently used in the session. You can
+use this automatic variable to determine which file will be updated.
### $Error
-Contains an array of error objects that represent the most recent errors.
-The most recent error is the first error object in the array `$Error[0]`.
+Contains an array of error objects that represent the most recent errors. The
+most recent error is the first error object in the array `$Error[0]`.
To prevent an error from being added to the `$Error` array, use the **ErrorAction** common parameter with a value of **Ignore**. For more
information, see [about_CommonParameters](about_CommonParameters.md).
Contains a **PSEventArgs** object that represents the event that is being processed. This variable is populated only within the `Action` block of an event registration command, such as `Register-ObjectEvent`. The value of this
-variable is the same object that the `Get-Event` cmdlet returns. Therefore,
-you can use the properties of the `Event` variable, such as
-`$Event.TimeGenerated`, in an `Action` script block.
+variable is the same object that the `Get-Event` cmdlet returns. Therefore, you
+can use the properties of the `Event` variable, such as `$Event.TimeGenerated`,
+in an `Action` script block.
### $EventArgs
-Contains an object that represents the first event argument that derives
-from **EventArgs** of the event that is being processed. This variable is
-populated only within the `Action` block of an event registration command.
-The value of this variable can also be found in the **SourceEventArgs**
-property of the **PSEventArgs** object that `Get-Event` returns.
+Contains an object that represents the first event argument that derives from
+**EventArgs** of the event that is being processed. This variable is populated
+only within the `Action` block of an event registration command. The value of
+this variable can also be found in the **SourceEventArgs** property of the
+**PSEventArgs** object that `Get-Event` returns.
### $EventSubscriber Contains a **PSEventSubscriber** object that represents the event subscriber of
-the event that is being processed. This variable is populated only within
-the `Action` block of an event registration command. The value of this
-variable is the same object that the `Get-EventSubscriber` cmdlet returns.
+the event that is being processed. This variable is populated only within the
+`Action` block of an event registration command. The value of this variable is
+the same object that the `Get-EventSubscriber` cmdlet returns.
### $ExecutionContext Contains an **EngineIntrinsics** object that represents the execution context
-of the PowerShell host. You can use this variable to find the execution
-objects that are available to cmdlets.
+of the PowerShell host. You can use this variable to find the execution objects
+that are available to cmdlets.
### $false
non-zero integer.
### $foreach
-Contains the enumerator (not the resulting values) of a
-[ForEach](about_ForEach.md) loop. The `$ForEach` variable exists only while
-the `ForEach` loop is running; it's deleted after the loop is completed.
+Contains the enumerator (not the resulting values) of a [ForEach](about_ForEach.md)
+loop. The `$ForEach` variable exists only while the `ForEach` loop is running;
+it's deleted after the loop is completed.
Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
### $HOME Contains the full path of the user's home directory. This variable is the
-equivalent of the `"$env:homedrive$env:homepath"` Windows environment variables,
-typically `C:\Users\<UserName>`.
+equivalent of the `"$env:homedrive$env:homepath"` Windows environment
+variables, typically `C:\Users\<UserName>`.
### $Host
-Contains an object that represents the current host application for
-PowerShell. You can use this variable to represent the current host in
-commands or to display or change the properties of the host, such as
-`$Host.version` or `$Host.CurrentCulture`, or
-`$host.ui.rawui.setbackgroundcolor("Red")`.
+Contains an object that represents the current host application for PowerShell.
+You can use this variable to represent the current host in commands or to
+display or change the properties of the host, such as `$Host.version` or
+`$Host.CurrentCulture`, or `$host.ui.rawui.setbackgroundcolor("Red")`.
### $input
-Contains an enumerator that enumerates all input that is passed to a
-function. The `$input` variable is available only to functions and script
-blocks (which are unnamed functions).
+Contains an enumerator that enumerates all input that is passed to a function.
+The `$input` variable is available only to functions and script blocks (which
+are unnamed functions).
- In a function without a `Begin`, `Process`, or `End` block, the `$input` variable enumerates the collection of all input to the function. - In the `Begin` block, the `$input` variable contains no data. -- In the `Process` block, the `$input` variable contains the
- object that is currently in the pipeline.
+- In the `Process` block, the `$input` variable contains the object that is
+ currently in the pipeline.
- In the `End` block, the `$input` variable enumerates the collection of all input to the function.
blocks (which are unnamed functions).
> End block in the same function or script block. Since `$input` is an enumerator, accessing any of it's properties causes
-`$input` to no longer be available. You can store `$input` in another variable to
-reuse the `$input` properties.
+`$input` to no longer be available. You can store `$input` in another variable
+to reuse the `$input` properties.
Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
The `$input` variable is also available to the command specified by the `-Command` parameter of `pwsh` when invoked from the command line. The
Contains the exit code of the last native program that was run.
### $Matches
-The `Matches` variable works with the `-match` and `-notmatch` operators.
-When you submit scalar input to the `-match` or `-notmatch` operator, and
-either one detects a match, they return a Boolean value and populate the
-`$Matches` automatic variable with a hash table of any string values that
-were matched. The `$Matches` hash table can also be populated with captures
-when you use regular expressions with the `-match` operator.
+The `$Matches` variable works with the `-match` and `-notmatch` operators. When
+you submit scalar input to the `-match` or `-notmatch` operator, and either one
+detects a match, they return a Boolean value and populate the `$Matches`
+automatic variable with a hash table of any string values that were matched.
+The `$Matches` hash table can also be populated with captures when you use
+regular expressions with the `-match` operator.
For more information about the `-match` operator, see [about_Comparison_Operators](about_comparison_operators.md). For more
The `$Matches` variable also works in a `switch` statement with the `-Regex`
parameter. It's populated the same way as the `-match` and `-notmatch` operators. For more information about the `switch` statement, see [about_Switch](about_Switch.md).
+> [!NOTE]
+> When `$Matches` is populated in a session, it retains the matched value until
+> it's overwritten by another match. If `-match` is used again and no match is
+> found, it doesn't reset `$Matches` to `$null`. The previously matched value is
+> kept in `$Matches` until another match is found.
+ ### $MyInvocation Contains information about the current command, such as the name, parameters,
file name of the script (`$MyInvocation.MyCommand.Path`) or the name of a
function (`$MyInvocation.MyCommand.Name`) to identify the current command. This is particularly useful for finding the name of the current script.
-Beginning in PowerShell 3.0, `MyInvocation` has the following new
-properties.
+Beginning in PowerShell 3.0, `MyInvocation` has the following new properties.
- **PSScriptRoot** - Contains the full path to the script that invoked the current command. The value of this property is populated only when the caller
the current script.
### $NestedPromptLevel
-Contains the current prompt level. A value of 0 indicates the original
-prompt level. The value is incremented when you enter a nested level and
-decremented when you exit it.
+Contains the current prompt level. A value of 0 indicates the original prompt
+level. The value is incremented when you enter a nested level and decremented
+when you exit it.
For example, PowerShell presents a nested command prompt when you use the `$Host.EnterNestedPrompt` method. PowerShell also presents a nested command prompt when you reach a breakpoint in the PowerShell debugger.
-When you enter a nested prompt, PowerShell pauses the current command,
-saves the execution context, and increments the value of the
-`$NestedPromptLevel` variable. To create additional nested command prompts
-(up to 128 levels) or to return to the original command prompt, complete
-the command, or type `exit`.
+When you enter a nested prompt, PowerShell pauses the current command, saves
+the execution context, and increments the value of the `$NestedPromptLevel`
+variable. To create additional nested command prompts (up to 128 levels) or to
+return to the original command prompt, complete the command, or type `exit`.
The `$NestedPromptLevel` variable helps you track the prompt level. You can create an alternative PowerShell command prompt that includes this value so
can use this variable to represent an absent or undefined value in commands and
scripts. PowerShell treats `$null` as an object with a value, that is, as an explicit
-placeholder, so you can use `$null` to represent an empty value in a series
-of values.
+placeholder, so you can use `$null` to represent an empty value in a series of
+values.
For example, when `$null` is included in a collection, it's counted as one of the objects.
current PowerShell session.
### $PROFILE
-Contains the full path of the PowerShell profile for the current user and
-the current host application. You can use this variable to represent the
-profile in commands. For example, you can use it in a command to determine
-whether a profile has been created:
+Contains the full path of the PowerShell profile for the current user and the
+current host application. You can use this variable to represent the profile in
+commands. For example, you can use it in a command to determine whether a
+profile has been created:
```powershell Test-Path $PROFILE
notepad.exe $PROFILE
### $PSBoundParameters
-Contains a dictionary of the parameters that are passed to a script or
-function and their current values. This variable has a value only in a
-scope where parameters are declared, such as a script or function. You can
-use it to display or change the current values of parameters or to pass
-parameter values to another script or function.
+Contains a dictionary of the parameters that are passed to a script or function
+and their current values. This variable has a value only in a scope where
+parameters are declared, such as a script or function. You can use it to
+display or change the current values of parameters or to pass parameter values
+to another script or function.
In this example, the **Test2** function passes the `$PSBoundParameters` to the **Test1** function. The `$PSBoundParameters` are displayed in the format of
b Shell
### $PSCmdlet
-Contains an object that represents the cmdlet or advanced function that's
-being run.
+Contains an object that represents the cmdlet or advanced function that's being
+run.
-You can use the properties and methods of the object in your cmdlet or
-function code to respond to the conditions of use. For example, the
-**ParameterSetName** property contains the name of the parameter set that's
-being used, and the **ShouldProcess** method adds the **WhatIf** and
-**Confirm** parameters to the cmdlet dynamically.
+You can use the properties and methods of the object in your cmdlet or function
+code to respond to the conditions of use. For example, the **ParameterSetName**
+property contains the name of the parameter set that's being used, and the
+**ShouldProcess** method adds the **WhatIf** and **Confirm** parameters to the
+cmdlet dynamically.
-For more information about the `$PSCmdlet` automatic variable, see
-[about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md)
+For more information about the `$PSCmdlet` automatic variable, see [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md)
and [about_Functions_Advanced](about_Functions_Advanced.md). ### $PSCommandPath
path of the script that is being debugged.
### $PSHOME
-Contains the full path of the installation directory for PowerShell,
-typically, `$env:windir\System32\PowerShell\v1.0` in Windows systems. You can
-use this variable in the paths of PowerShell files. For example, the
-following command searches the conceptual Help topics for the word
-**variable**:
+Contains the full path of the installation directory for PowerShell, typically,
+`$env:windir\System32\PowerShell\v1.0` in Windows systems. You can use this
+variable in the paths of PowerShell files. For example, the following command
+searches the conceptual Help topics for the word **variable**:
```powershell Select-String -Pattern Variable -Path $pshome\*.txt
Select-String -Pattern Variable -Path $pshome\*.txt
### $PSItem Same as `$_`. Contains the current object in the pipeline object. You can use
-this variable in commands that perform an action on every object or on
-selected objects in a pipeline.
+this variable in commands that perform an action on every object or on selected
+objects in a pipeline.
### $PSScriptRoot
Beginning in PowerShell 3.0, it's valid in all scripts.
### $PSSenderInfo
-Contains information about the user who started the PSSession, including
-the user identity and the time zone of the originating computer. This
-variable is available only in PSSessions.
+Contains information about the user who started the PSSession, including the
+user identity and the time zone of the originating computer. This variable is
+available only in PSSessions.
The `$PSSenderInfo` variable includes a user-configurable property, **ApplicationArguments**, that by default, contains only the `$PSVersionTable`
property, use the **ApplicationArguments** parameter of the
### $PSUICulture
-Contains the name of the user interface (UI) culture that's currently in use
-in the operating system. The UI culture determines which text strings are used
-for user interface elements, such as menus and messages. This is the value of
-the **System.Globalization.CultureInfo.CurrentUICulture.Name** property of the
+Contains the name of the user interface (UI) culture that's currently in use in
+the operating system. The UI culture determines which text strings are used for
+user interface elements, such as menus and messages. This is the value of the
+**System.Globalization.CultureInfo.CurrentUICulture.Name** property of the
system. To get the **System.Globalization.CultureInfo** object for the system, use the `Get-UICulture` cmdlet.
location for the current PowerShell runspace.
### $Sender
-Contains the object that generated this event. This variable is populated
-only within the Action block of an event registration command. The value of
-this variable can also be found in the Sender property of the **PSEventArgs**
-object that `Get-Event` returns.
+Contains the object that generated this event. This variable is populated only
+within the Action block of an event registration command. The value of this
+variable can also be found in the Sender property of the **PSEventArgs** object
+that `Get-Event` returns.
### $ShellId
deleted when the `switch` statement completes execution. For more information,
see [about_Switch](about_Switch.md). Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
### $this
-In a script block that defines a script property or script method, the
-`$this` variable refers to the object that is being extended.
+In a script block that defines a script property or script method, the `$this`
+variable refers to the object that is being extended.
In a custom class, the `$this` variable refers to the class object itself allowing access to properties and methods defined in the class.
and scripts.
## Using Enumerators
-The `$input`, `$foreach`, and `$switch` variables are all enumerators used
-to iterate through the values processed by their containing code block.
+The `$input`, `$foreach`, and `$switch` variables are all enumerators used to
+iterate through the values processed by their containing code block.
An enumerator contains properties and methods you can use to advance or reset iteration, or retrieve iteration values. Directly manipulating enumerators isn't considered best practice. -- Within loops, flow control keywords [break](about_Break.md) and
- [continue](about_Continue.md) should be preferred.
+- Within loops, flow control keywords [break](about_Break.md) and [continue](about_Continue.md)
+ should be preferred.
- Within functions that accept pipeline input, it's best practice to use parameters with the **ValueFromPipeline** or **ValueFromPipelineByPropertyName** attributes.
enumerator has passed the end of the collection.
### Reset
-The [Reset](/dotnet/api/system.collections.ienumerator.reset) method sets
-the enumerator to its initial position, which is **before** the first element
-in the collection.
+The [Reset](/dotnet/api/system.collections.ienumerator.reset) method sets the
+enumerator to its initial position, which is **before** the first element in
+the collection.
### Current
-The [Current](/dotnet/api/system.collections.ienumerator.current) property
-gets the element in the collection, or pipeline, at the current position of
-the enumerator.
+The [Current](/dotnet/api/system.collections.ienumerator.current) property gets
+the element in the collection, or pipeline, at the current position of the
+enumerator.
The **Current** property continues to return the same property until **MoveNext** is called.
Iteration: 1
### Example 4: Using the $foreach variable Unlike the `$input` variable, the `$foreach` variable always represents all
-items in the collection when accessed directly. Use the **Current** property
-to access the current collection element, and the **Reset** and **MoveNext**
+items in the collection when accessed directly. Use the **Current** property to
+access the current collection element, and the **Reset** and **MoveNext**
methods to change its value. > [!NOTE]
methods to change its value.
> method. The following loop only executes twice. In the second iteration, the collection
-is moved to the third element before the iteration is complete. After the second
-iteration, there are now no more values to iterate, and the loop terminates.
+is moved to the third element before the iteration is complete. After the
+second iteration, there are now no more values to iterate, and the loop
+terminates.
The **MoveNext** property doesn't affect the variable chosen to iterate through the collection (`$Num`).
Num has not changed: two
Using the **Reset** method resets the current element in the collection. The following example loops through the first two elements _twice_ because the
-**Reset** method is called. After the first two loops, the `if` statement
-fails and the loop iterates through all three elements normally.
+**Reset** method is called. After the first two loops, the `if` statement fails
+and the loop iterates through all three elements normally.
> [!IMPORTANT] > This could result in an infinite loop.
Reset Loop: 0
### Example 5: Using the $switch variable
-The `$switch` variable has the exact same rules as the `$foreach` variable.
-The following example demonstrates all the enumerator concepts.
+The `$switch` variable has the exact same rules as the `$foreach` variable. The
+following example demonstrates all the enumerator concepts.
> [!NOTE] > Note how the **NotEvaluated** case is never executed, even though there's
Microsoft.PowerShell.Core About Comparison Operators (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md
--- description: Describes the operators that compare values in PowerShell. Locale: en-US Previously updated : 06/21/2021 Last updated : 07/06/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Comparison Operators
There are a few exceptions:
When the left-hand side is scalar, `-eq` returns **True** if the right-hand side is an exact match, otherwise, `-eq` returns **False**. `-ne` does the opposite; it returns **False** when both sides match; otherwise, `-ne` returns
-True.
+**True**.
Example:
equality test result is **False** because they are different objects. To create
comparable classes, you need to implement [System.IEquatable\<T>][2] in your class. The following example demonstrates the partial implementation of a **MyFileInfoSet** class that implements [System.IEquatable\<T>][2] and has two
-properties, **File** and **Size**. The `Equals()` method returns True if the
+properties, **File** and **Size**. The `Equals()` method returns **True** if the
File and Size properties of two **MyFileInfoSet** objects are the same. ```powershell
they return **True** or **False** depending on how the two sides compare:
| -lt | The left-hand side is smaller | | -le | The left-hand side is smaller or equal |
-In the following examples, all statements return True.
+In the following examples, all statements return **True**.
```powershell 8 -gt 6 # Output: True
User name:
jsmith ```
-For details, see [about_Regular_Expressions](about_Regular_Expressions.md).
+For details, see [about_Regular_Expressions](about_Regular_Expressions.md) and
+[about_Automatic_Variables](about_Automatic_Variables.md).
## Replacement operator
Syntax:
### -contains and -notcontains These operators tell whether a set includes a certain element. `-contains`
-returns True when the right-hand side (test object) matches one of the elements
+returns **True** when the right-hand side (test object) matches one of the elements
in the set. `-notcontains` returns False instead. When the test object is a collection, these operators use reference equality, i.e. they check whether one of the set's elements is the same instance of the test object.
Microsoft.PowerShell.Core About Automatic Variables (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md
--- description: Describes variables that store state information for PowerShell. These variables are created and maintained by PowerShell. Locale: en-US Previously updated : 05/13/2021 Last updated : 07/06/2021 no-loc: [Reset, Current, Background, Blink, Bold, Foreground, Formatting, Hidden, Italic, Reset, Reverse, Underline] online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0
Contains the last token in the last line received by the session.
### $?
-Contains the execution status of the last command. It contains **True** if
-the last command succeeded and **False** if it failed.
+Contains the execution status of the last command. It contains **True** if the
+last command succeeded and **False** if it failed.
For cmdlets and advanced functions that are run at multiple stages in a pipeline, for example in both `process` and `end` blocks, calling
Contains the first token in the last line received by the session.
### $_
-Same as `$PSItem`. Contains the current object in the pipeline object. You
-can use this variable in commands that perform an action on every object or
-on selected objects in a pipeline.
+Same as `$PSItem`. Contains the current object in the pipeline object. You can
+use this variable in commands that perform an action on every object or on
+selected objects in a pipeline.
### $args
of parameters in parentheses after the function name.
In an event action, the `$Args` variable contains objects that represent the event arguments of the event that is being processed. This variable is
-populated only within the `Action` block of an event registration command.
-The value of this variable can also be found in the **SourceArgs** property of
-the **PSEventArgs** object that `Get-Event` returns.
+populated only within the `Action` block of an event registration command. The
+value of this variable can also be found in the **SourceArgs** property of the
+**PSEventArgs** object that `Get-Event` returns.
### $ConsoleFileName
-Contains the path of the console file (`.psc1`) that was most recently used
-in the session. This variable is populated when you start PowerShell with
-the **PSConsoleFile** parameter or when you use the `Export-Console` cmdlet to
+Contains the path of the console file (`.psc1`) that was most recently used in
+the session. This variable is populated when you start PowerShell with the
+**PSConsoleFile** parameter or when you use the `Export-Console` cmdlet to
export snap-in names to a console file. When you use the `Export-Console` cmdlet without parameters, it automatically
-updates the console file that was most recently used in the session. You
-can use this automatic variable to determine which file will be updated.
+updates the console file that was most recently used in the session. You can
+use this automatic variable to determine which file will be updated.
### $Error
-Contains an array of error objects that represent the most recent errors.
-The most recent error is the first error object in the array `$Error[0]`.
+Contains an array of error objects that represent the most recent errors. The
+most recent error is the first error object in the array `$Error[0]`.
To prevent an error from being added to the `$Error` array, use the **ErrorAction** common parameter with a value of **Ignore**. For more
information, see [about_CommonParameters](about_CommonParameters.md).
Contains a **PSEventArgs** object that represents the event that is being processed. This variable is populated only within the `Action` block of an event registration command, such as `Register-ObjectEvent`. The value of this
-variable is the same object that the `Get-Event` cmdlet returns. Therefore,
-you can use the properties of the `Event` variable, such as
-`$Event.TimeGenerated`, in an `Action` script block.
+variable is the same object that the `Get-Event` cmdlet returns. Therefore, you
+can use the properties of the `Event` variable, such as `$Event.TimeGenerated`,
+in an `Action` script block.
### $EventArgs
-Contains an object that represents the first event argument that derives
-from **EventArgs** of the event that is being processed. This variable is
-populated only within the `Action` block of an event registration command.
-The value of this variable can also be found in the **SourceEventArgs**
-property of the **PSEventArgs** object that `Get-Event` returns.
+Contains an object that represents the first event argument that derives from
+**EventArgs** of the event that is being processed. This variable is populated
+only within the `Action` block of an event registration command. The value of
+this variable can also be found in the **SourceEventArgs** property of the
+**PSEventArgs** object that `Get-Event` returns.
### $EventSubscriber Contains a **PSEventSubscriber** object that represents the event subscriber of
-the event that is being processed. This variable is populated only within
-the `Action` block of an event registration command. The value of this
-variable is the same object that the `Get-EventSubscriber` cmdlet returns.
+the event that is being processed. This variable is populated only within the
+`Action` block of an event registration command. The value of this variable is
+the same object that the `Get-EventSubscriber` cmdlet returns.
### $ExecutionContext Contains an **EngineIntrinsics** object that represents the execution context
-of the PowerShell host. You can use this variable to find the execution
-objects that are available to cmdlets.
+of the PowerShell host. You can use this variable to find the execution objects
+that are available to cmdlets.
### $false
non-zero integer.
### $foreach
-Contains the enumerator (not the resulting values) of a
-[ForEach](about_ForEach.md) loop. The `$ForEach` variable exists only while
-the `ForEach` loop is running; it's deleted after the loop is completed.
+Contains the enumerator (not the resulting values) of a [ForEach](about_ForEach.md)
+loop. The `$ForEach` variable exists only while the `ForEach` loop is running;
+it's deleted after the loop is completed.
Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
### $HOME Contains the full path of the user's home directory. This variable is the
-equivalent of the `"$env:homedrive$env:homepath"` Windows environment variables,
-typically `C:\Users\<UserName>`.
+equivalent of the `"$env:homedrive$env:homepath"` Windows environment
+variables, typically `C:\Users\<UserName>`.
### $Host
-Contains an object that represents the current host application for
-PowerShell. You can use this variable to represent the current host in
-commands or to display or change the properties of the host, such as
-`$Host.version` or `$Host.CurrentCulture`, or
-`$host.ui.rawui.setbackgroundcolor("Red")`.
+Contains an object that represents the current host application for PowerShell.
+You can use this variable to represent the current host in commands or to
+display or change the properties of the host, such as `$Host.version` or
+`$Host.CurrentCulture`, or `$host.ui.rawui.setbackgroundcolor("Red")`.
### $input
-Contains an enumerator that enumerates all input that is passed to a
-function. The `$input` variable is available only to functions and script
-blocks (which are unnamed functions).
+Contains an enumerator that enumerates all input that is passed to a function.
+The `$input` variable is available only to functions and script blocks (which
+are unnamed functions).
- In a function without a `Begin`, `Process`, or `End` block, the `$input` variable enumerates the collection of all input to the function. - In the `Begin` block, the `$input` variable contains no data. -- In the `Process` block, the `$input` variable contains the
- object that is currently in the pipeline.
+- In the `Process` block, the `$input` variable contains the object that is
+ currently in the pipeline.
- In the `End` block, the `$input` variable enumerates the collection of all input to the function.
blocks (which are unnamed functions).
> End block in the same function or script block. Since `$input` is an enumerator, accessing any of it's properties causes
-`$input` to no longer be available. You can store `$input` in another variable to
-reuse the `$input` properties.
+`$input` to no longer be available. You can store `$input` in another variable
+to reuse the `$input` properties.
Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
The `$input` variable is also available to the command specified by the `-Command` parameter of `pwsh` when invoked from the command line. The
Contains the exit code of the last native program that was run.
### $Matches
-The `Matches` variable works with the `-match` and `-notmatch` operators.
-When you submit scalar input to the `-match` or `-notmatch` operator, and
-either one detects a match, they return a Boolean value and populate the
-`$Matches` automatic variable with a hash table of any string values that
-were matched. The `$Matches` hash table can also be populated with captures
-when you use regular expressions with the `-match` operator.
+The `$Matches` variable works with the `-match` and `-notmatch` operators. When
+you submit scalar input to the `-match` or `-notmatch` operator, and either one
+detects a match, they return a Boolean value and populate the `$Matches`
+automatic variable with a hash table of any string values that were matched.
+The `$Matches` hash table can also be populated with captures when you use
+regular expressions with the `-match` operator.
For more information about the `-match` operator, see [about_Comparison_Operators](about_comparison_operators.md). For more
-information on regular expressions, see
-[about_Regular_Expressions](about_Regular_Expressions.md).
+information on regular expressions, see [about_Regular_Expressions](about_Regular_Expressions.md).
The `$Matches` variable also works in a `switch` statement with the `-Regex`
-parameter. It's populated the same way as the `-match` and `-notmatch`
-operators. For more information about the `switch` statement, see
-[about_Switch](about_Switch.md).
+parameter. It's populated the same way as the `-match` and `-notmatch` operators.
+For more information about the `switch` statement, see [about_Switch](about_Switch.md).
+
+> [!NOTE]
+> When `$Matches` is populated in a session, it retains the matched value until
+> it's overwritten by another match. If `-match` is used again and no match is
+> found, it doesn't reset `$Matches` to `$null`. The previously matched value is
+> kept in `$Matches` until another match is found.
### $MyInvocation
file name of the script (`$MyInvocation.MyCommand.Path`) or the name of a
function (`$MyInvocation.MyCommand.Name`) to identify the current command. This is particularly useful for finding the name of the current script.
-Beginning in PowerShell 3.0, `MyInvocation` has the following new
-properties.
+Beginning in PowerShell 3.0, `MyInvocation` has the following new properties.
- **PSScriptRoot** - Contains the full path to the script that invoked the current command. The value of this property is populated only when the caller
the current script.
### $NestedPromptLevel
-Contains the current prompt level. A value of 0 indicates the original
-prompt level. The value is incremented when you enter a nested level and
-decremented when you exit it.
+Contains the current prompt level. A value of 0 indicates the original prompt
+level. The value is incremented when you enter a nested level and decremented
+when you exit it.
For example, PowerShell presents a nested command prompt when you use the `$Host.EnterNestedPrompt` method. PowerShell also presents a nested command prompt when you reach a breakpoint in the PowerShell debugger.
-When you enter a nested prompt, PowerShell pauses the current command,
-saves the execution context, and increments the value of the
-`$NestedPromptLevel` variable. To create additional nested command prompts
-(up to 128 levels) or to return to the original command prompt, complete
-the command, or type `exit`.
+When you enter a nested prompt, PowerShell pauses the current command, saves
+the execution context, and increments the value of the `$NestedPromptLevel`
+variable. To create additional nested command prompts (up to 128 levels) or to
+return to the original command prompt, complete the command, or type `exit`.
The `$NestedPromptLevel` variable helps you track the prompt level. You can create an alternative PowerShell command prompt that includes this value so
can use this variable to represent an absent or undefined value in commands and
scripts. PowerShell treats `$null` as an object with a value, that is, as an explicit
-placeholder, so you can use `$null` to represent an empty value in a series
-of values.
+placeholder, so you can use `$null` to represent an empty value in a series of
+values.
For example, when `$null` is included in a collection, it's counted as one of the objects.
current PowerShell session.
### $PROFILE
-Contains the full path of the PowerShell profile for the current user and
-the current host application. You can use this variable to represent the
-profile in commands. For example, you can use it in a command to determine
-whether a profile has been created:
+Contains the full path of the PowerShell profile for the current user and the
+current host application. You can use this variable to represent the profile in
+commands. For example, you can use it in a command to determine whether a
+profile has been created:
```powershell Test-Path $PROFILE
notepad.exe $PROFILE
### $PSBoundParameters
-Contains a dictionary of the parameters that are passed to a script or
-function and their current values. This variable has a value only in a
-scope where parameters are declared, such as a script or function. You can
-use it to display or change the current values of parameters or to pass
-parameter values to another script or function.
+Contains a dictionary of the parameters that are passed to a script or function
+and their current values. This variable has a value only in a scope where
+parameters are declared, such as a script or function. You can use it to
+display or change the current values of parameters or to pass parameter values
+to another script or function.
In this example, the **Test2** function passes the `$PSBoundParameters` to the **Test1** function. The `$PSBoundParameters` are displayed in the format of
b Shell
### $PSCmdlet
-Contains an object that represents the cmdlet or advanced function that's
-being run.
+Contains an object that represents the cmdlet or advanced function that's being
+run.
-You can use the properties and methods of the object in your cmdlet or
-function code to respond to the conditions of use. For example, the
-**ParameterSetName** property contains the name of the parameter set that's
-being used, and the **ShouldProcess** method adds the **WhatIf** and
-**Confirm** parameters to the cmdlet dynamically.
+You can use the properties and methods of the object in your cmdlet or function
+code to respond to the conditions of use. For example, the **ParameterSetName**
+property contains the name of the parameter set that's being used, and the
+**ShouldProcess** method adds the **WhatIf** and **Confirm** parameters to the
+cmdlet dynamically.
-For more information about the `$PSCmdlet` automatic variable, see
-[about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md)
+For more information about the `$PSCmdlet` automatic variable, see [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md)
and [about_Functions_Advanced](about_Functions_Advanced.md). ### $PSCommandPath
path of the script that is being debugged.
### $PSHOME
-Contains the full path of the installation directory for PowerShell,
-typically, `$env:windir\System32\PowerShell\v1.0` in Windows systems. You can
-use this variable in the paths of PowerShell files. For example, the
-following command searches the conceptual Help topics for the word
-**variable**:
+Contains the full path of the installation directory for PowerShell, typically,
+`$env:windir\System32\PowerShell\v1.0` in Windows systems. You can use this
+variable in the paths of PowerShell files. For example, the following command
+searches the conceptual Help topics for the word **variable**:
```powershell Select-String -Pattern Variable -Path $pshome\*.txt
Select-String -Pattern Variable -Path $pshome\*.txt
### $PSItem Same as `$_`. Contains the current object in the pipeline object. You can use
-this variable in commands that perform an action on every object or on
-selected objects in a pipeline.
+this variable in commands that perform an action on every object or on selected
+objects in a pipeline.
### $PSScriptRoot
Beginning in PowerShell 3.0, it's valid in all scripts.
### $PSSenderInfo
-Contains information about the user who started the PSSession, including
-the user identity and the time zone of the originating computer. This
-variable is available only in PSSessions.
+Contains information about the user who started the PSSession, including the
+user identity and the time zone of the originating computer. This variable is
+available only in PSSessions.
The `$PSSenderInfo` variable includes a user-configurable property, **ApplicationArguments**, that by default, contains only the `$PSVersionTable`
enum with the values:
### $PSUICulture
-Contains the name of the user interface (UI) culture that's currently in use
-in the operating system. The UI culture determines which text strings are used
-for user interface elements, such as menus and messages. This is the value of
-the **System.Globalization.CultureInfo.CurrentUICulture.Name** property of the
+Contains the name of the user interface (UI) culture that's currently in use in
+the operating system. The UI culture determines which text strings are used for
+user interface elements, such as menus and messages. This is the value of the
+**System.Globalization.CultureInfo.CurrentUICulture.Name** property of the
system. To get the **System.Globalization.CultureInfo** object for the system, use the `Get-UICulture` cmdlet.
location for the current PowerShell runspace.
### $Sender
-Contains the object that generated this event. This variable is populated
-only within the Action block of an event registration command. The value of
-this variable can also be found in the Sender property of the **PSEventArgs**
-object that `Get-Event` returns.
+Contains the object that generated this event. This variable is populated only
+within the Action block of an event registration command. The value of this
+variable can also be found in the Sender property of the **PSEventArgs** object
+that `Get-Event` returns.
### $ShellId
deleted when the `switch` statement completes execution. For more information,
see [about_Switch](about_Switch.md). Enumerators contain properties and methods you can use to retrieve loop values
-and change the current loop iteration. For more information, see
-[Using Enumerators](#using-enumerators).
+and change the current loop iteration. For more information, see [Using Enumerators](#using-enumerators).
### $this
-In a script block that defines a script property or script method, the
-`$this` variable refers to the object that is being extended.
+In a script block that defines a script property or script method, the `$this`
+variable refers to the object that is being extended.
In a custom class, the `$this` variable refers to the class object itself allowing access to properties and methods defined in the class.
and scripts.
## Using Enumerators
-The `$input`, `$foreach`, and `$switch` variables are all enumerators used
-to iterate through the values processed by their containing code block.
+The `$input`, `$foreach`, and `$switch` variables are all enumerators used to
+iterate through the values processed by their containing code block.
An enumerator contains properties and methods you can use to advance or reset iteration, or retrieve iteration values. Directly manipulating enumerators isn't considered best practice. -- Within loops, flow control keywords [break](about_Break.md) and
- [continue](about_Continue.md) should be preferred.
+- Within loops, flow control keywords [break](about_Break.md) and [continue](about_Continue.md)
+ should be preferred.
- Within functions that accept pipeline input, it's best practice to use parameters with the **ValueFromPipeline** or **ValueFromPipelineByPropertyName** attributes.
enumerator has passed the end of the collection.
### Reset
-The [Reset](/dotnet/api/system.collections.ienumerator.reset) method sets
-the enumerator to its initial position, which is **before** the first element
-in the collection.
+The [Reset](/dotnet/api/system.collections.ienumerator.reset) method sets the
+enumerator to its initial position, which is **before** the first element in
+the collection.
### Current
-The [Current](/dotnet/api/system.collections.ienumerator.current) property
-gets the element in the collection, or pipeline, at the current position of
-the enumerator.
+The [Current](/dotnet/api/system.collections.ienumerator.current) property gets
+the element in the collection, or pipeline, at the current position of the
+enumerator.
The **Current** property continues to return the same property until **MoveNext** is called.
Iteration: 1
### Example 4: Using the $foreach variable Unlike the `$input` variable, the `$foreach` variable always represents all
-items in the collection when accessed directly. Use the **Current** property
-to access the current collection element, and the **Reset** and **MoveNext**
+items in the collection when accessed directly. Use the **Current** property to
+access the current collection element, and the **Reset** and **MoveNext**
methods to change its value. > [!NOTE]
methods to change its value.
> method. The following loop only executes twice. In the second iteration, the collection
-is moved to the third element before the iteration is complete. After the second
-iteration, there are now no more values to iterate, and the loop terminates.
+is moved to the third element before the iteration is complete. After the
+second iteration, there are now no more values to iterate, and the loop
+terminates.
The **MoveNext** property doesn't affect the variable chosen to iterate through the collection (`$Num`).
Num has not changed: two
Using the **Reset** method resets the current element in the collection. The following example loops through the first two elements _twice_ because the
-**Reset** method is called. After the first two loops, the `if` statement
-fails and the loop iterates through all three elements normally.
+**Reset** method is called. After the first two loops, the `if` statement fails
+and the loop iterates through all three elements normally.
> [!IMPORTANT] > This could result in an infinite loop.
Reset Loop: 0
### Example 5: Using the $switch variable
-The `$switch` variable has the exact same rules as the `$foreach` variable.
-The following example demonstrates all the enumerator concepts.
+The `$switch` variable has the exact same rules as the `$foreach` variable. The
+following example demonstrates all the enumerator concepts.
> [!NOTE] > Note how the **NotEvaluated** case is never executed, even though there's
Microsoft.PowerShell.Core About Comparison Operators (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md
--- description: Describes the operators that compare values in PowerShell. Locale: en-US Previously updated : 06/21/2021 Last updated : 07/06/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Comparison Operators
There are a few exceptions:
When the left-hand side is scalar, `-eq` returns **True** if the right-hand side is an exact match, otherwise, `-eq` returns **False**. `-ne` does the opposite; it returns **False** when both sides match; otherwise, `-ne` returns
-True.
+**True**.
Example:
equality test result is **False** because they are different objects. To create
comparable classes, you need to implement [System.IEquatable\<T>][2] in your class. The following example demonstrates the partial implementation of a **MyFileInfoSet** class that implements [System.IEquatable\<T>][2] and has two
-properties, **File** and **Size**. The `Equals()` method returns True if the
+properties, **File** and **Size**. The `Equals()` method returns **True** if the
File and Size properties of two **MyFileInfoSet** objects are the same. ```powershell
they return **True** or **False** depending on how the two sides compare:
| -lt | The left-hand side is smaller | | -le | The left-hand side is smaller or equal |
-In the following examples, all statements return True.
+In the following examples, all statements return **True**.
```powershell 8 -gt 6 # Output: True
User name:
jsmith ```
-For details, see [about_Regular_Expressions](about_Regular_Expressions.md).
+For details, see [about_Regular_Expressions](about_Regular_Expressions.md) and
+[about_Automatic_Variables](about_Automatic_Variables.md).
## Replacement operator
Syntax:
### -contains and -notcontains These operators tell whether a set includes a certain element. `-contains`
-returns True when the right-hand side (test object) matches one of the elements
+returns **True** when the right-hand side (test object) matches one of the elements
in the set. `-notcontains` returns False instead. When the test object is a collection, these operators use reference equality, i.e. they check whether one of the set's elements is the same instance of the test object.