diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 766837ee27f..4fb2ef1072b 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,3 +1,3 @@ # https://help.github.com/articles/about-codeowners/ -* @sdwheeler @michaeltlombardi +* @sdwheeler diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index f83cee332a5..1ceb0adb73c 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that compare values in PowerShell. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.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 @@ -60,12 +60,12 @@ case-sensitive operator. To make a comparison operator case-sensitive, add a To make the case-insensitivity explicit, add an `i` after `-`. For example, `-ieq` is the explicitly case-insensitive version of `-eq`. -String comparisons use the [InvariantCulture][01] for both case-sensitive and +String comparisons use the [InvariantCulture][15] for both case-sensitive and case-insensitive comparisons. The comparisons are between unicode code points and don't use culture-specific collation ordering. The results are the same regardless of the current culture. -When the left-hand value in the comparison expression is a [scalar][15] value, +When the left-hand value in the comparison expression is a [scalar][03] value, the operator returns a **Boolean** value. When the left-hand value in the expression is a collection, the operator returns the elements of the collection that match the right-hand value of the expression. Right-hand values are always @@ -176,9 +176,9 @@ False In this example, we created two objects with identical properties. Yet, the equality test result is **False** because they're different objects. To create -comparable classes, you need to implement [System.IEquatable\][03] in your +comparable classes, you need to implement [System.IEquatable\][17] in your class. The following example demonstrates the partial implementation of a -**MyFileInfoSet** class that implements [System.IEquatable\][03] and has two +**MyFileInfoSet** class that implements [System.IEquatable\][17] and has two properties, **File** and **Size**. The `Equals()` method returns **True** if the File and Size properties of two **MyFileInfoSet** objects are the same. @@ -259,7 +259,7 @@ In the following examples, all statements return **True**. > [!NOTE] > In most programming languages the greater-than operator is `>`. In > PowerShell, this character is used for redirection. For details, see -> [about_Redirection][09]. +> [about_Redirection][08]. When the left-hand side is a collection, these operators compare each member of the collection with the right-hand side. Depending on their logic, they either @@ -313,7 +313,7 @@ Members smaller than or equal to 7 7 ``` -These operators work with any class that implements [System.IComparable][02]. +These operators work with any class that implements [System.IComparable][16]. Examples: @@ -372,7 +372,7 @@ used for the comparison and is obtained by casting the member to a string. ### -like and -notlike `-like` and `-notlike` behave similarly to `-eq` and `-ne`, but the right-hand -side could be a string containing [wildcards][11]. +side could be a string containing [wildcards][10]. Example: @@ -421,7 +421,12 @@ False `-match` and `-notmatch` use regular expressions to search for pattern in the left-hand side values. Regular expressions can match complex patterns like email addresses, UNC paths, or formatted phone numbers. The right-hand side -string must adhere to the [regular expressions][10] rules. +string must adhere to the [regular expressions][09] rules. + +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> [Regular expression safety][04] section of this article. Scalar examples: @@ -510,17 +515,22 @@ if ('1.0.0' -match '(.*?)') { } ``` -For details, see [about_Regular_Expressions][10] and -[about_Automatic_Variables][06]. +For details, see [about_Regular_Expressions][09] and +[about_Automatic_Variables][05]. ## Replacement operator -### Replacement with regular expressions - Like `-match`, the `-replace` operator uses regular expressions to find the specified pattern. But unlike `-match`, it replaces the matches with another specified value. +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> [Regular expression safety][04] section of this article. + +### Replacement with regular expressions + Syntax: ``` @@ -605,8 +615,8 @@ include a literal `$` in the resulting replacement. For example: '5.72' -replace '(.+)', '$$1' # Output: $1 ``` -To learn more, see [about_Regular_Expressions][10] and -[Substitutions in Regular Expressions][05]. +To learn more, see [about_Regular_Expressions][09] and +[Substitutions in Regular Expressions][02]. ### Substituting in a collection @@ -754,30 +764,79 @@ $b -isnot [int] # Output: True $a -isnot $b.GetType() # Output: True ``` +## Regular expression safety + +The number of comparison operations required to match a regular expression +pattern can increase exponentially if the pattern includes a large number of +alternation constructs, espcecially when it includes nested optional +quantifiers. For example, the regular expression pattern `^(a+)+$` is designed +to match a complete string that contains one or more "a" characters. The +regular expression engine must use the regular expression to follow all +possible paths through the data before it can conclude that the match is +unsuccessful, and the nested parentheses create many additional paths through +the data. + +> [!WARNING] +> A malicious user can provide input to regular expressions causing a +> [Denial-of-Service attack][11], also known as a ReDoS attack. + +To defend against ReDoS scenarios, create `[regex]` objects that specify a +timeout. The regex engine terminates the search for a match when it exceeds the +time limit. For example, the following code creates a regex object with a +2-second timeout: + +```powershell +$pattern = '^(a+)+$' +$regexOptions = 'None' +$matchTimeout = [timespan]::FromSeconds(2) +$regex = [regex]::new($pattern, $regexOptions, $matchTimeout) +$regex.IsMatch('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaX') +``` + +After 2 seconds, the regex engine terminates the search and returns the +following error: + +```Output +MethodInvocationException: Exception calling "IsMatch" with "1" argument(s): +"The Regex engine has timed out while trying to match a pattern to an input +string. This can occur for many reasons, including very large inputs or +excessive backtracking caused by nested quantifiers, back-references and other +factors." +``` + +For more information about the `[regex]` class and regex performance, see the +following articles: + +- [System.Text.RegularExpressions.Regex][19] +- [Backtracking in .NET regular expressions][01] + ## See also -- [about_Booleans][07] -- [about_Operators][08] -- [about_Regular_Expressions][10] -- [about_Wildcards][11] +- [about_Booleans][06] +- [about_Operators][07] +- [about_Regular_Expressions][09] +- [about_Wildcards][10] - [Compare-Object][14] - [ForEach-Object][12] - [Where-Object][13] -[01]: /dotnet/api/system.globalization.cultureinfo.invariantculture -[02]: /dotnet/api/system.icomparable -[03]: /dotnet/api/system.iequatable-1 -[04]: /dotnet/api/system.text.regularexpressions.match -[05]: /dotnet/standard/base-types/substitutions-in-regular-expressions -[06]: about_Automatic_Variables.md -[07]: about_Booleans.md -[08]: about_Operators.md -[09]: about_Redirection.md#potential-confusion-with-comparison-operators -[10]: about_Regular_Expressions.md -[11]: about_Wildcards.md +[01]: /dotnet/standard/base-types/backtracking-in-regular-expressions +[02]: /dotnet/standard/base-types/substitutions-in-regular-expressions +[03]: /powershell/scripting/learn/glossary#scalar-value +[04]: #regular-expression-safety +[05]: about_Automatic_Variables.md +[06]: about_Booleans.md +[07]: about_Operators.md +[08]: about_Redirection.md#potential-confusion-with-comparison-operators +[09]: about_Regular_Expressions.md +[10]: about_Wildcards.md +[11]: https://www.cisa.gov/news-events/news/understanding-denial-service-attacks [12]: xref:Microsoft.PowerShell.Core.ForEach-Object [13]: xref:Microsoft.PowerShell.Core.Where-Object [14]: xref:Microsoft.PowerShell.Utility.Compare-Object -[15]: /powershell/scripting/learn/glossary#scalar-value - +[15]: xref:System.Globalization.CultureInfo.InvariantCulture%2A +[16]: xref:System.IComparable +[17]: xref:System.IEquatable%601 +[18]: xref:System.Text.RegularExpressions.Match +[19]: xref:System.Text.RegularExpressions.Regex diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Error_Handling.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Error_Handling.md index 9b661eec41d..55128538024 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Error_Handling.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Error_Handling.md @@ -1,7 +1,7 @@ --- description: Describes the types of errors in PowerShell and the mechanisms for handling them. Locale: en-US -ms.date: 06/02/2026 +ms.date: 07/02/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_error_handling?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Error_Handling @@ -254,19 +254,19 @@ The scope of the escalated error depends on context: & { param() $ErrorActionPreference = 'Stop' - Get-Item 'NoSuchPath' + 1/0 # Divide by zero error } 2>$null 'after' ``` -- ADVANCED: script-terminating ('after' does NOT print) +- ADVANCED: statement-terminating ('after' DOES print) ```powershell & { [CmdletBinding()] param() $ErrorActionPreference = 'Stop' - Get-Item 'NoSuchPath' + 1/0 # Divide by zero error } 2>$null 'after' ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md index 65123e7ac4f..8bd30238c9d 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Split operator to split one or more strings into substrings. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_split?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Split @@ -28,9 +28,14 @@ change the following elements of the Split operation: - Options that specify the conditions under which the delimiter is matched, such as SimpleMatch and Multiline. +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> _Regular expression safety_ section of [about_Comparison_Operators][01]. + ## Syntax -The following diagram shows the syntax for the -split operator. +The following diagram shows the syntax for the `-split` operator. The parameter names do not appear in the command. Include only the parameter values. The values must appear in the order specified in the syntax diagram. @@ -506,7 +511,14 @@ LastName, FirstName ## See also -- [Split-Path](xref:Microsoft.PowerShell.Management.Split-Path) -- [about_Operators](about_Operators.md) -- [about_Comparison_Operators](about_Comparison_Operators.md) -- [about_Join](about_Join.md) +- [Split-Path][05] +- [about_Operators][04] +- [about_Comparison_Operators][02] +- [about_Join][03] + + +[01]: about_Comparison_Operators.md#regular-expression-safety +[02]: about_Comparison_Operators.md +[03]: about_Join.md +[04]: about_Operators.md +[05]: xref:Microsoft.PowerShell.Management.Split-Path diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md index b8639968e9c..df32138b3df 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -47,7 +47,7 @@ if ("$()") -eq ("$()") {} Expressions include literal values (strings or numbers), variables, and scriptblocks that return a boolean value. The `switch` statement converts all values to strings before comparison. For an example, see -[Impact of string conversion][02] later in this article. +[Impact of string conversion][01] later in this article. The `` is evaluated in expression mode. If the expression returns more than one value, such as an array or other enumerable type, the @@ -110,7 +110,7 @@ conditions. It's equivalent to an `else` clause in an `if` statement. Only one default, the comparison is case-insensitive. The **File** parameter only supports one file. If multiple **File** parameters are included, only the last one is used. For more information see the - [**File** parameter examples][01]. + [**File** parameter examples][02]. - **Regex** - Performs regular expression matching of the value to the condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$Matches` automatic variable is @@ -392,6 +392,11 @@ switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { } ``` +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the _Regular expression +> safety_ section of [about_Comparison_Operators][05]. + ### Read the content of a file with `switch` Using the `switch` statement with the **File** parameter is an efficient way to @@ -443,15 +448,16 @@ switch -File $fileEscaped { foo { 'Foo' } } ## See also - [about_Break][04] -- [about_Continue][05] -- [about_If][06] -- [about_Script_Blocks][07] +- [about_Continue][06] +- [about_If][07] +- [about_Script_Blocks][08] -[01]: #read-the-content-of-a-file-with-switch -[02]: #impact-of-string-conversion +[01]: #impact-of-string-conversion +[02]: #read-the-content-of-a-file-with-switch [03]: about_Automatic_Variables.md [04]: about_break.md -[05]: about_Continue.md -[06]: about_If.md -[07]: about_Script_Blocks.md +[05]: about_Comparison_Operators.md#regular-expression-safety +[06]: about_Continue.md +[07]: about_If.md +[08]: about_Script_Blocks.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md index 08df65320cb..eb8e122b44f 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md @@ -1,7 +1,7 @@ --- description: Describes the features of PowerShell that use ANSI escape sequences and the terminal hosts that support them. Locale: en-US -ms.date: 12/09/2025 +ms.date: 07/02/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_ansi_terminals?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_ANSI_Terminals @@ -89,7 +89,9 @@ The following members control how or when ANSI formatting is used: - `PlainText`: ANSI escape sequences are always stripped so that it's only plain text. In remote sessions, if the remote host is set to `PlainText`, the output is stripped of ANSI escape sequences before sending it back to - the local client. + the local client. This mode removes text formatting and rendering + sequences. It's not intended to be a comprehensive terminal-control + sanitization mechanism. - `Host`: This is the default behavior. The ANSI escape sequences are removed from redirected or piped output. For more information, see [Redirecting output][02]. diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index 1cded9aef19..4a572c4484b 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,8 +1,8 @@ --- description: Describes the operators that compare values in PowerShell. Locale: en-US -ms.date: 01/18/2026 -online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-5.1&WT.mc_id=ps-gethelp +ms.date: 07/01/2026 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Comparison_Operators --- @@ -60,12 +60,12 @@ case-sensitive operator. To make a comparison operator case-sensitive, add a To make the case-insensitivity explicit, add an `i` after `-`. For example, `-ieq` is the explicitly case-insensitive version of `-eq`. -String comparisons use the [InvariantCulture][01] for both case-sensitive and +String comparisons use the [InvariantCulture][15] for both case-sensitive and case-insensitive comparisons. The comparisons are between unicode code points and don't use culture-specific collation ordering. The results are the same regardless of the current culture. -When the left-hand value in the comparison expression is a [scalar][15] value, +When the left-hand value in the comparison expression is a [scalar][03] value, the operator returns a **Boolean** value. When the left-hand value in the expression is a collection, the operator returns the elements of the collection that match the right-hand value of the expression. Right-hand values are always @@ -176,9 +176,9 @@ False In this example, we created two objects with identical properties. Yet, the equality test result is **False** because they're different objects. To create -comparable classes, you need to implement [System.IEquatable\][03] in your +comparable classes, you need to implement [System.IEquatable\][17] in your class. The following example demonstrates the partial implementation of a -**MyFileInfoSet** class that implements [System.IEquatable\][03] and has two +**MyFileInfoSet** class that implements [System.IEquatable\][17] and has two properties, **File** and **Size**. The `Equals()` method returns **True** if the File and Size properties of two **MyFileInfoSet** objects are the same. @@ -259,7 +259,7 @@ In the following examples, all statements return **True**. > [!NOTE] > In most programming languages the greater-than operator is `>`. In > PowerShell, this character is used for redirection. For details, see -> [about_Redirection][09]. +> [about_Redirection][08]. When the left-hand side is a collection, these operators compare each member of the collection with the right-hand side. Depending on their logic, they either @@ -313,7 +313,7 @@ Members smaller than or equal to 7 7 ``` -These operators work with any class that implements [System.IComparable][02]. +These operators work with any class that implements [System.IComparable][16]. Examples: @@ -372,7 +372,7 @@ used for the comparison and is obtained by casting the member to a string. ### -like and -notlike `-like` and `-notlike` behave similarly to `-eq` and `-ne`, but the right-hand -side could be a string containing [wildcards][11]. +side could be a string containing [wildcards][10]. Example: @@ -421,7 +421,12 @@ False `-match` and `-notmatch` use regular expressions to search for pattern in the left-hand side values. Regular expressions can match complex patterns like email addresses, UNC paths, or formatted phone numbers. The right-hand side -string must adhere to the [regular expressions][10] rules. +string must adhere to the [regular expressions][09] rules. + +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> [Regular expression safety][04] section of this article. Scalar examples: @@ -510,17 +515,22 @@ if ('1.0.0' -match '(.*?)') { } ``` -For details, see [about_Regular_Expressions][10] and -[about_Automatic_Variables][06]. +For details, see [about_Regular_Expressions][09] and +[about_Automatic_Variables][05]. ## Replacement operator -### Replacement with regular expressions - Like `-match`, the `-replace` operator uses regular expressions to find the specified pattern. But unlike `-match`, it replaces the matches with another specified value. +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> [Regular expression safety][04] section of this article. + +### Replacement with regular expressions + Syntax: ``` @@ -628,8 +638,8 @@ include a literal `$` in the resulting replacement. For example: '5.72' -replace '(.+)', '$$1' # Output: $1 ``` -To learn more, see [about_Regular_Expressions][10] and -[Substitutions in Regular Expressions][05]. +To learn more, see [about_Regular_Expressions][09] and +[Substitutions in Regular Expressions][02]. ### Substituting in a collection @@ -658,7 +668,7 @@ Syntax: Within the scriptblock, use the `$_` automatic variable to access the input text being replaced and other useful information. This variable's class type is -[System.Text.RegularExpressions.Match][04]. +[System.Text.RegularExpressions.Match][18]. The following example replaces each sequence of three digits with the character equivalents. The scriptblock runs for each set of three digits that needs to @@ -804,32 +814,79 @@ $b -isnot [int] # Output: True $a -isnot $b.GetType() # Output: True ``` +## Regular expression safety + +The number of comparison operations required to match a regular expression +pattern can increase exponentially if the pattern includes a large number of +alternation constructs, espcecially when it includes nested optional +quantifiers. For example, the regular expression pattern `^(a+)+$` is designed +to match a complete string that contains one or more "a" characters. The +regular expression engine must use the regular expression to follow all +possible paths through the data before it can conclude that the match is +unsuccessful, and the nested parentheses create many additional paths through +the data. + +> [!WARNING] +> A malicious user can provide input to regular expressions causing a +> [Denial-of-Service attack][11], also known as a ReDoS attack. + +To defend against ReDoS scenarios, create `[regex]` objects that specify a +timeout. The regex engine terminates the search for a match when it exceeds the +time limit. For example, the following code creates a regex object with a +2-second timeout: + +```powershell +$pattern = '^(a+)+$' +$regexOptions = 'None' +$matchTimeout = [timespan]::FromSeconds(2) +$regex = [regex]::new($pattern, $regexOptions, $matchTimeout) +$regex.IsMatch('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaX') +``` + +After 2 seconds, the regex engine terminates the search and returns the +following error: + +```Output +MethodInvocationException: Exception calling "IsMatch" with "1" argument(s): +"The Regex engine has timed out while trying to match a pattern to an input +string. This can occur for many reasons, including very large inputs or +excessive backtracking caused by nested quantifiers, back-references and other +factors." +``` + +For more information about the `[regex]` class and regex performance, see the +following articles: + +- [System.Text.RegularExpressions.Regex][19] +- [Backtracking in .NET regular expressions][01] + ## See also -- [about_Booleans][07] -- [about_Operators][08] -- [about_Regular_Expressions][10] -- [about_Wildcards][11] +- [about_Booleans][06] +- [about_Operators][07] +- [about_Regular_Expressions][09] +- [about_Wildcards][10] - [Compare-Object][14] - [ForEach-Object][12] - [Where-Object][13] -[01]: /dotnet/api/system.globalization.cultureinfo.invariantculture -[02]: /dotnet/api/system.icomparable -[03]: /dotnet/api/system.iequatable-1 -[04]: /dotnet/api/system.text.regularexpressions.match -[05]: /dotnet/standard/base-types/substitutions-in-regular-expressions -[06]: about_Automatic_Variables.md -[07]: about_Booleans.md -[08]: about_Operators.md -[09]: about_Redirection.md#potential-confusion-with-comparison-operators -[10]: about_Regular_Expressions.md -[11]: about_Wildcards.md +[01]: /dotnet/standard/base-types/backtracking-in-regular-expressions +[02]: /dotnet/standard/base-types/substitutions-in-regular-expressions +[03]: /powershell/scripting/learn/glossary#scalar-value +[04]: #regular-expression-safety +[05]: about_Automatic_Variables.md +[06]: about_Booleans.md +[07]: about_Operators.md +[08]: about_Redirection.md#potential-confusion-with-comparison-operators +[09]: about_Regular_Expressions.md +[10]: about_Wildcards.md +[11]: https://www.cisa.gov/news-events/news/understanding-denial-service-attacks [12]: xref:Microsoft.PowerShell.Core.ForEach-Object [13]: xref:Microsoft.PowerShell.Core.Where-Object [14]: xref:Microsoft.PowerShell.Utility.Compare-Object -[15]: /powershell/scripting/learn/glossary#scalar-value - - - +[15]: xref:System.Globalization.CultureInfo.InvariantCulture%2A +[16]: xref:System.IComparable +[17]: xref:System.IEquatable%601 +[18]: xref:System.Text.RegularExpressions.Match +[19]: xref:System.Text.RegularExpressions.Regex diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Error_Handling.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Error_Handling.md index 0acfe240a0e..a73f7e535d9 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Error_Handling.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Error_Handling.md @@ -1,7 +1,7 @@ --- description: Describes the types of errors in PowerShell and the mechanisms for handling them. Locale: en-US -ms.date: 06/02/2026 +ms.date: 07/02/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_error_handling?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Error_Handling @@ -254,19 +254,19 @@ The scope of the escalated error depends on context: & { param() $ErrorActionPreference = 'Stop' - Get-Item 'NoSuchPath' + 1/0 # Divide by zero error } 2>$null 'after' ``` -- ADVANCED: script-terminating ('after' does NOT print) +- ADVANCED: statement-terminating ('after' DOES print) ```powershell & { [CmdletBinding()] param() $ErrorActionPreference = 'Stop' - Get-Item 'NoSuchPath' + 1/0 # Divide by zero error } 2>$null 'after' ``` diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md index 0f3e8f1e006..036ffed07ea 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Split operator to split one or more strings into substrings. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_split?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Split @@ -28,9 +28,14 @@ change the following elements of the Split operation: - Options that specify the conditions under which the delimiter is matched, such as SimpleMatch and Multiline. +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> _Regular expression safety_ section of [about_Comparison_Operators][01]. + ## Syntax -The following diagram shows the syntax for the -split operator. +The following diagram shows the syntax for the `-split` operator. The parameter names do not appear in the command. Include only the parameter values. The values must appear in the order specified in the syntax diagram. @@ -506,7 +511,14 @@ LastName, FirstName ## See also -- [Split-Path](xref:Microsoft.PowerShell.Management.Split-Path) -- [about_Operators](about_Operators.md) -- [about_Comparison_Operators](about_Comparison_Operators.md) -- [about_Join](about_Join.md) +- [Split-Path][05] +- [about_Operators][04] +- [about_Comparison_Operators][02] +- [about_Join][03] + + +[01]: about_Comparison_Operators.md#regular-expression-safety +[02]: about_Comparison_Operators.md +[03]: about_Join.md +[04]: about_Operators.md +[05]: xref:Microsoft.PowerShell.Management.Split-Path diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md index 90ef4baeaee..fb700b8d10a 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -47,7 +47,7 @@ if ("$()") -eq ("$()") {} Expressions include literal values (strings or numbers), variables, and scriptblocks that return a boolean value. The `switch` statement converts all values to strings before comparison. For an example, see -[Impact of string conversion][02] later in this article. +[Impact of string conversion][01] later in this article. The `` is evaluated in expression mode. If the expression returns more than one value, such as an array or other enumerable type, the @@ -110,7 +110,7 @@ conditions. It's equivalent to an `else` clause in an `if` statement. Only one default, the comparison is case-insensitive. The **File** parameter only supports one file. If multiple **File** parameters are included, only the last one is used. For more information see the - [**File** parameter examples][01]. + [**File** parameter examples][02]. - **Regex** - Performs regular expression matching of the value to the condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$Matches` automatic variable is @@ -392,6 +392,11 @@ switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { } ``` +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the _Regular expression +> safety_ section of [about_Comparison_Operators][05]. + ### Read the content of a file with `switch` Using the `switch` statement with the **File** parameter is an efficient way to @@ -443,15 +448,16 @@ switch -File $fileEscaped { foo { 'Foo' } } ## See also - [about_Break][04] -- [about_Continue][05] -- [about_If][06] -- [about_Script_Blocks][07] +- [about_Continue][06] +- [about_If][07] +- [about_Script_Blocks][08] -[01]: #read-the-content-of-a-file-with-switch -[02]: #impact-of-string-conversion +[01]: #impact-of-string-conversion +[02]: #read-the-content-of-a-file-with-switch [03]: about_Automatic_Variables.md [04]: about_break.md -[05]: about_Continue.md -[06]: about_If.md -[07]: about_Script_Blocks.md \ No newline at end of file +[05]: about_Comparison_Operators.md#regular-expression-safety +[06]: about_Continue.md +[07]: about_If.md +[08]: about_Script_Blocks.md diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Select-String.md b/reference/7.4/Microsoft.PowerShell.Utility/Select-String.md index f11ce26e7ec..669fd5dd6a2 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Select-String.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Select-String.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 05/02/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/select-string?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 aliases: @@ -90,6 +90,11 @@ You can also specify that `Select-String` should expect a particular character e when you're searching files of Unicode text. `Select-String` uses the byte-order-mark (BOM) to detect the encoding format of the file. If the file has no BOM, it assumes the encoding is UTF8. +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial of service +> conditions. For more information, see the _Regular expression safety_ section of +> [about_Comparison_Operators](/powershell/module/microsoft.powershell.core/about/about_comparison_operators#regular-expression-safety). + ## EXAMPLES ### Example 1: Find a case-sensitive match diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md index 340b72d8d64..f4c486c1e46 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md @@ -1,7 +1,7 @@ --- description: Describes the features of PowerShell that use ANSI escape sequences and the terminal hosts that support them. Locale: en-US -ms.date: 12/09/2025 +ms.date: 07/02/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_ansi_terminals?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_ANSI_Terminals @@ -89,7 +89,9 @@ The following members control how or when ANSI formatting is used: - `PlainText`: ANSI escape sequences are always stripped so that it's only plain text. In remote sessions, if the remote host is set to `PlainText`, the output is stripped of ANSI escape sequences before sending it back to - the local client. + the local client. This mode removes text formatting and rendering + sequences. It's not intended to be a comprehensive terminal-control + sanitization mechanism. - `Host`: This is the default behavior. The ANSI escape sequences are removed from redirected or piped output. For more information, see [Redirecting output][02]. diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index 03588e0355b..3af31940d14 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that compare values in PowerShell. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Comparison_Operators @@ -60,12 +60,12 @@ case-sensitive operator. To make a comparison operator case-sensitive, add a To make the case-insensitivity explicit, add an `i` after `-`. For example, `-ieq` is the explicitly case-insensitive version of `-eq`. -String comparisons use the [InvariantCulture][01] for both case-sensitive and +String comparisons use the [InvariantCulture][15] for both case-sensitive and case-insensitive comparisons. The comparisons are between unicode code points and don't use culture-specific collation ordering. The results are the same regardless of the current culture. -When the left-hand value in the comparison expression is a [scalar][15] value, +When the left-hand value in the comparison expression is a [scalar][03] value, the operator returns a **Boolean** value. When the left-hand value in the expression is a collection, the operator returns the elements of the collection that match the right-hand value of the expression. Right-hand values are always @@ -176,9 +176,9 @@ False In this example, we created two objects with identical properties. Yet, the equality test result is **False** because they're different objects. To create -comparable classes, you need to implement [System.IEquatable\][03] in your +comparable classes, you need to implement [System.IEquatable\][17] in your class. The following example demonstrates the partial implementation of a -**MyFileInfoSet** class that implements [System.IEquatable\][03] and has two +**MyFileInfoSet** class that implements [System.IEquatable\][17] and has two properties, **File** and **Size**. The `Equals()` method returns **True** if the File and Size properties of two **MyFileInfoSet** objects are the same. @@ -259,7 +259,7 @@ In the following examples, all statements return **True**. > [!NOTE] > In most programming languages the greater-than operator is `>`. In > PowerShell, this character is used for redirection. For details, see -> [about_Redirection][09]. +> [about_Redirection][08]. When the left-hand side is a collection, these operators compare each member of the collection with the right-hand side. Depending on their logic, they either @@ -313,7 +313,7 @@ Members smaller than or equal to 7 7 ``` -These operators work with any class that implements [System.IComparable][02]. +These operators work with any class that implements [System.IComparable][16]. Examples: @@ -372,7 +372,7 @@ used for the comparison and is obtained by casting the member to a string. ### -like and -notlike `-like` and `-notlike` behave similarly to `-eq` and `-ne`, but the right-hand -side could be a string containing [wildcards][11]. +side could be a string containing [wildcards][10]. Example: @@ -421,7 +421,12 @@ False `-match` and `-notmatch` use regular expressions to search for pattern in the left-hand side values. Regular expressions can match complex patterns like email addresses, UNC paths, or formatted phone numbers. The right-hand side -string must adhere to the [regular expressions][10] rules. +string must adhere to the [regular expressions][09] rules. + +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> [Regular expression safety][04] section of this article. Scalar examples: @@ -510,17 +515,22 @@ if ('1.0.0' -match '(.*?)') { } ``` -For details, see [about_Regular_Expressions][10] and -[about_Automatic_Variables][06]. +For details, see [about_Regular_Expressions][09] and +[about_Automatic_Variables][05]. ## Replacement operator -### Replacement with regular expressions - Like `-match`, the `-replace` operator uses regular expressions to find the specified pattern. But unlike `-match`, it replaces the matches with another specified value. +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> [Regular expression safety][04] section of this article. + +### Replacement with regular expressions + Syntax: ``` @@ -628,8 +638,8 @@ include a literal `$` in the resulting replacement. For example: '5.72' -replace '(.+)', '$$1' # Output: $1 ``` -To learn more, see [about_Regular_Expressions][10] and -[Substitutions in Regular Expressions][05]. +To learn more, see [about_Regular_Expressions][09] and +[Substitutions in Regular Expressions][02]. ### Substituting in a collection @@ -658,7 +668,7 @@ Syntax: Within the scriptblock, use the `$_` automatic variable to access the input text being replaced and other useful information. This variable's class type is -[System.Text.RegularExpressions.Match][04]. +[System.Text.RegularExpressions.Match][18]. The following example replaces each sequence of three digits with the character equivalents. The scriptblock runs for each set of three digits that needs to @@ -804,30 +814,79 @@ $b -isnot [int] # Output: True $a -isnot $b.GetType() # Output: True ``` +## Regular expression safety + +The number of comparison operations required to match a regular expression +pattern can increase exponentially if the pattern includes a large number of +alternation constructs, espcecially when it includes nested optional +quantifiers. For example, the regular expression pattern `^(a+)+$` is designed +to match a complete string that contains one or more "a" characters. The +regular expression engine must use the regular expression to follow all +possible paths through the data before it can conclude that the match is +unsuccessful, and the nested parentheses create many additional paths through +the data. + +> [!WARNING] +> A malicious user can provide input to regular expressions causing a +> [Denial-of-Service attack][11], also known as a ReDoS attack. + +To defend against ReDoS scenarios, create `[regex]` objects that specify a +timeout. The regex engine terminates the search for a match when it exceeds the +time limit. For example, the following code creates a regex object with a +2-second timeout: + +```powershell +$pattern = '^(a+)+$' +$regexOptions = 'None' +$matchTimeout = [timespan]::FromSeconds(2) +$regex = [regex]::new($pattern, $regexOptions, $matchTimeout) +$regex.IsMatch('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaX') +``` + +After 2 seconds, the regex engine terminates the search and returns the +following error: + +```Output +MethodInvocationException: Exception calling "IsMatch" with "1" argument(s): +"The Regex engine has timed out while trying to match a pattern to an input +string. This can occur for many reasons, including very large inputs or +excessive backtracking caused by nested quantifiers, back-references and other +factors." +``` + +For more information about the `[regex]` class and regex performance, see the +following articles: + +- [System.Text.RegularExpressions.Regex][19] +- [Backtracking in .NET regular expressions][01] + ## See also -- [about_Booleans][07] -- [about_Operators][08] -- [about_Regular_Expressions][10] -- [about_Wildcards][11] +- [about_Booleans][06] +- [about_Operators][07] +- [about_Regular_Expressions][09] +- [about_Wildcards][10] - [Compare-Object][14] - [ForEach-Object][12] - [Where-Object][13] -[01]: /dotnet/api/system.globalization.cultureinfo.invariantculture -[02]: /dotnet/api/system.icomparable -[03]: /dotnet/api/system.iequatable-1 -[04]: /dotnet/api/system.text.regularexpressions.match -[05]: /dotnet/standard/base-types/substitutions-in-regular-expressions -[06]: about_Automatic_Variables.md -[07]: about_Booleans.md -[08]: about_Operators.md -[09]: about_Redirection.md#potential-confusion-with-comparison-operators -[10]: about_Regular_Expressions.md -[11]: about_Wildcards.md +[01]: /dotnet/standard/base-types/backtracking-in-regular-expressions +[02]: /dotnet/standard/base-types/substitutions-in-regular-expressions +[03]: /powershell/scripting/learn/glossary#scalar-value +[04]: #regular-expression-safety +[05]: about_Automatic_Variables.md +[06]: about_Booleans.md +[07]: about_Operators.md +[08]: about_Redirection.md#potential-confusion-with-comparison-operators +[09]: about_Regular_Expressions.md +[10]: about_Wildcards.md +[11]: https://www.cisa.gov/news-events/news/understanding-denial-service-attacks [12]: xref:Microsoft.PowerShell.Core.ForEach-Object [13]: xref:Microsoft.PowerShell.Core.Where-Object [14]: xref:Microsoft.PowerShell.Utility.Compare-Object -[15]: /powershell/scripting/learn/glossary#scalar-value - +[15]: xref:System.Globalization.CultureInfo.InvariantCulture%2A +[16]: xref:System.IComparable +[17]: xref:System.IEquatable%601 +[18]: xref:System.Text.RegularExpressions.Match +[19]: xref:System.Text.RegularExpressions.Regex diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Error_Handling.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Error_Handling.md index 8f31b6f15c4..e96c465f733 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Error_Handling.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Error_Handling.md @@ -1,7 +1,7 @@ --- description: Describes the types of errors in PowerShell and the mechanisms for handling them. Locale: en-US -ms.date: 06/02/2026 +ms.date: 07/02/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_error_handling?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Error_Handling @@ -254,19 +254,19 @@ The scope of the escalated error depends on context: & { param() $ErrorActionPreference = 'Stop' - Get-Item 'NoSuchPath' + 1/0 # Divide by zero error } 2>$null 'after' ``` -- ADVANCED: script-terminating ('after' does NOT print) +- ADVANCED: statement-terminating ('after' DOES print) ```powershell & { [CmdletBinding()] param() $ErrorActionPreference = 'Stop' - Get-Item 'NoSuchPath' + 1/0 # Divide by zero error } 2>$null 'after' ``` diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Split.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Split.md index 98adf2db0c2..b3a54525c51 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Split operator to split one or more strings into substrings. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_split?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Split @@ -28,9 +28,14 @@ change the following elements of the Split operation: - Options that specify the conditions under which the delimiter is matched, such as SimpleMatch and Multiline. +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> _Regular expression safety_ section of [about_Comparison_Operators][01]. + ## Syntax -The following diagram shows the syntax for the -split operator. +The following diagram shows the syntax for the `-split` operator. The parameter names do not appear in the command. Include only the parameter values. The values must appear in the order specified in the syntax diagram. @@ -506,7 +511,14 @@ LastName, FirstName ## See also -- [Split-Path](xref:Microsoft.PowerShell.Management.Split-Path) -- [about_Operators](about_Operators.md) -- [about_Comparison_Operators](about_Comparison_Operators.md) -- [about_Join](about_Join.md) +- [Split-Path][05] +- [about_Operators][04] +- [about_Comparison_Operators][02] +- [about_Join][03] + + +[01]: about_Comparison_Operators.md#regular-expression-safety +[02]: about_Comparison_Operators.md +[03]: about_Join.md +[04]: about_Operators.md +[05]: xref:Microsoft.PowerShell.Management.Split-Path diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md index 0aa1e2ce901..8e178a9b170 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -47,7 +47,7 @@ if ("$()") -eq ("$()") {} Expressions include literal values (strings or numbers), variables, and scriptblocks that return a boolean value. The `switch` statement converts all values to strings before comparison. For an example, see -[Impact of string conversion][02] later in this article. +[Impact of string conversion][01] later in this article. The `` is evaluated in expression mode. If the expression returns more than one value, such as an array or other enumerable type, the @@ -110,7 +110,7 @@ conditions. It's equivalent to an `else` clause in an `if` statement. Only one default, the comparison is case-insensitive. The **File** parameter only supports one file. If multiple **File** parameters are included, only the last one is used. For more information see the - [**File** parameter examples][01]. + [**File** parameter examples][02]. - **Regex** - Performs regular expression matching of the value to the condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$Matches` automatic variable is @@ -392,6 +392,11 @@ switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { } ``` +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the _Regular expression +> safety_ section of [about_Comparison_Operators][05]. + ### Read the content of a file with `switch` Using the `switch` statement with the **File** parameter is an efficient way to @@ -443,15 +448,16 @@ switch -File $fileEscaped { foo { 'Foo' } } ## See also - [about_Break][04] -- [about_Continue][05] -- [about_If][06] -- [about_Script_Blocks][07] +- [about_Continue][06] +- [about_If][07] +- [about_Script_Blocks][08] -[01]: #read-the-content-of-a-file-with-switch -[02]: #impact-of-string-conversion +[01]: #impact-of-string-conversion +[02]: #read-the-content-of-a-file-with-switch [03]: about_Automatic_Variables.md [04]: about_break.md -[05]: about_Continue.md -[06]: about_If.md -[07]: about_Script_Blocks.md +[05]: about_Comparison_Operators.md#regular-expression-safety +[06]: about_Continue.md +[07]: about_If.md +[08]: about_Script_Blocks.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md index 0d5c9faf24b..993114f3071 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md @@ -1,7 +1,7 @@ --- description: Describes the features of PowerShell that use ANSI escape sequences and the terminal hosts that support them. Locale: en-US -ms.date: 12/09/2025 +ms.date: 07/02/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_ansi_terminals?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_ANSI_Terminals @@ -89,7 +89,9 @@ The following members control how or when ANSI formatting is used: - `PlainText`: ANSI escape sequences are always stripped so that it's only plain text. In remote sessions, if the remote host is set to `PlainText`, the output is stripped of ANSI escape sequences before sending it back to - the local client. + the local client. This mode removes text formatting and rendering + sequences. It's not intended to be a comprehensive terminal-control + sanitization mechanism. - `Host`: This is the default behavior. The ANSI escape sequences are removed from redirected or piped output. For more information, see [Redirecting output][02]. diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index a9c554d1569..d1d7c9e6939 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that compare values in PowerShell. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Comparison_Operators @@ -60,12 +60,12 @@ case-sensitive operator. To make a comparison operator case-sensitive, add a To make the case-insensitivity explicit, add an `i` after `-`. For example, `-ieq` is the explicitly case-insensitive version of `-eq`. -String comparisons use the [InvariantCulture][01] for both case-sensitive and +String comparisons use the [InvariantCulture][15] for both case-sensitive and case-insensitive comparisons. The comparisons are between unicode code points and don't use culture-specific collation ordering. The results are the same regardless of the current culture. -When the left-hand value in the comparison expression is a [scalar][15] value, +When the left-hand value in the comparison expression is a [scalar][03] value, the operator returns a **Boolean** value. When the left-hand value in the expression is a collection, the operator returns the elements of the collection that match the right-hand value of the expression. Right-hand values are always @@ -176,9 +176,9 @@ False In this example, we created two objects with identical properties. Yet, the equality test result is **False** because they're different objects. To create -comparable classes, you need to implement [System.IEquatable\][03] in your +comparable classes, you need to implement [System.IEquatable\][17] in your class. The following example demonstrates the partial implementation of a -**MyFileInfoSet** class that implements [System.IEquatable\][03] and has two +**MyFileInfoSet** class that implements [System.IEquatable\][17] and has two properties, **File** and **Size**. The `Equals()` method returns **True** if the File and Size properties of two **MyFileInfoSet** objects are the same. @@ -259,7 +259,7 @@ In the following examples, all statements return **True**. > [!NOTE] > In most programming languages the greater-than operator is `>`. In > PowerShell, this character is used for redirection. For details, see -> [about_Redirection][09]. +> [about_Redirection][08]. When the left-hand side is a collection, these operators compare each member of the collection with the right-hand side. Depending on their logic, they either @@ -313,7 +313,7 @@ Members smaller than or equal to 7 7 ``` -These operators work with any class that implements [System.IComparable][02]. +These operators work with any class that implements [System.IComparable][16]. Examples: @@ -372,7 +372,7 @@ used for the comparison and is obtained by casting the member to a string. ### -like and -notlike `-like` and `-notlike` behave similarly to `-eq` and `-ne`, but the right-hand -side could be a string containing [wildcards][11]. +side could be a string containing [wildcards][10]. Example: @@ -421,7 +421,12 @@ False `-match` and `-notmatch` use regular expressions to search for pattern in the left-hand side values. Regular expressions can match complex patterns like email addresses, UNC paths, or formatted phone numbers. The right-hand side -string must adhere to the [regular expressions][10] rules. +string must adhere to the [regular expressions][09] rules. + +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> [Regular expression safety][04] section of this article. Scalar examples: @@ -510,17 +515,22 @@ if ('1.0.0' -match '(.*?)') { } ``` -For details, see [about_Regular_Expressions][10] and -[about_Automatic_Variables][06]. +For details, see [about_Regular_Expressions][09] and +[about_Automatic_Variables][05]. ## Replacement operator -### Replacement with regular expressions - Like `-match`, the `-replace` operator uses regular expressions to find the specified pattern. But unlike `-match`, it replaces the matches with another specified value. +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> [Regular expression safety][04] section of this article. + +### Replacement with regular expressions + Syntax: ``` @@ -628,8 +638,8 @@ include a literal `$` in the resulting replacement. For example: '5.72' -replace '(.+)', '$$1' # Output: $1 ``` -To learn more, see [about_Regular_Expressions][10] and -[Substitutions in Regular Expressions][05]. +To learn more, see [about_Regular_Expressions][09] and +[Substitutions in Regular Expressions][02]. ### Substituting in a collection @@ -658,7 +668,7 @@ Syntax: Within the scriptblock, use the `$_` automatic variable to access the input text being replaced and other useful information. This variable's class type is -[System.Text.RegularExpressions.Match][04]. +[System.Text.RegularExpressions.Match][18]. The following example replaces each sequence of three digits with the character equivalents. The scriptblock runs for each set of three digits that needs to @@ -804,30 +814,79 @@ $b -isnot [int] # Output: True $a -isnot $b.GetType() # Output: True ``` +## Regular expression safety + +The number of comparison operations required to match a regular expression +pattern can increase exponentially if the pattern includes a large number of +alternation constructs, espcecially when it includes nested optional +quantifiers. For example, the regular expression pattern `^(a+)+$` is designed +to match a complete string that contains one or more "a" characters. The +regular expression engine must use the regular expression to follow all +possible paths through the data before it can conclude that the match is +unsuccessful, and the nested parentheses create many additional paths through +the data. + +> [!WARNING] +> A malicious user can provide input to regular expressions causing a +> [Denial-of-Service attack][11], also known as a ReDoS attack. + +To defend against ReDoS scenarios, create `[regex]` objects that specify a +timeout. The regex engine terminates the search for a match when it exceeds the +time limit. For example, the following code creates a regex object with a +2-second timeout: + +```powershell +$pattern = '^(a+)+$' +$regexOptions = 'None' +$matchTimeout = [timespan]::FromSeconds(2) +$regex = [regex]::new($pattern, $regexOptions, $matchTimeout) +$regex.IsMatch('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaX') +``` + +After 2 seconds, the regex engine terminates the search and returns the +following error: + +```Output +MethodInvocationException: Exception calling "IsMatch" with "1" argument(s): +"The Regex engine has timed out while trying to match a pattern to an input +string. This can occur for many reasons, including very large inputs or +excessive backtracking caused by nested quantifiers, back-references and other +factors." +``` + +For more information about the `[regex]` class and regex performance, see the +following articles: + +- [System.Text.RegularExpressions.Regex][19] +- [Backtracking in .NET regular expressions][01] + ## See also -- [about_Booleans][07] -- [about_Operators][08] -- [about_Regular_Expressions][10] -- [about_Wildcards][11] +- [about_Booleans][06] +- [about_Operators][07] +- [about_Regular_Expressions][09] +- [about_Wildcards][10] - [Compare-Object][14] - [ForEach-Object][12] - [Where-Object][13] -[01]: /dotnet/api/system.globalization.cultureinfo.invariantculture -[02]: /dotnet/api/system.icomparable -[03]: /dotnet/api/system.iequatable-1 -[04]: /dotnet/api/system.text.regularexpressions.match -[05]: /dotnet/standard/base-types/substitutions-in-regular-expressions -[06]: about_Automatic_Variables.md -[07]: about_Booleans.md -[08]: about_Operators.md -[09]: about_Redirection.md#potential-confusion-with-comparison-operators -[10]: about_Regular_Expressions.md -[11]: about_Wildcards.md +[01]: /dotnet/standard/base-types/backtracking-in-regular-expressions +[02]: /dotnet/standard/base-types/substitutions-in-regular-expressions +[03]: /powershell/scripting/learn/glossary#scalar-value +[04]: #regular-expression-safety +[05]: about_Automatic_Variables.md +[06]: about_Booleans.md +[07]: about_Operators.md +[08]: about_Redirection.md#potential-confusion-with-comparison-operators +[09]: about_Regular_Expressions.md +[10]: about_Wildcards.md +[11]: https://www.cisa.gov/news-events/news/understanding-denial-service-attacks [12]: xref:Microsoft.PowerShell.Core.ForEach-Object [13]: xref:Microsoft.PowerShell.Core.Where-Object [14]: xref:Microsoft.PowerShell.Utility.Compare-Object -[15]: /powershell/scripting/learn/glossary#scalar-value - +[15]: xref:System.Globalization.CultureInfo.InvariantCulture%2A +[16]: xref:System.IComparable +[17]: xref:System.IEquatable%601 +[18]: xref:System.Text.RegularExpressions.Match +[19]: xref:System.Text.RegularExpressions.Regex diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Error_Handling.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Error_Handling.md index 259f2e8f4c6..ec7150e8bc3 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Error_Handling.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Error_Handling.md @@ -1,7 +1,7 @@ --- description: Describes the types of errors in PowerShell and the mechanisms for handling them. Locale: en-US -ms.date: 06/02/2026 +ms.date: 07/02/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_error_handling?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Error_Handling @@ -254,19 +254,19 @@ The scope of the escalated error depends on context: & { param() $ErrorActionPreference = 'Stop' - Get-Item 'NoSuchPath' + 1/0 # Divide by zero error } 2>$null 'after' ``` -- ADVANCED: script-terminating ('after' does NOT print) +- ADVANCED: statement-terminating ('after' DOES print) ```powershell & { [CmdletBinding()] param() $ErrorActionPreference = 'Stop' - Get-Item 'NoSuchPath' + 1/0 # Divide by zero error } 2>$null 'after' ``` diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Split.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Split.md index 0806cbe3e19..3e854b9ff77 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Split operator to split one or more strings into substrings. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_split?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Split @@ -28,9 +28,14 @@ change the following elements of the Split operation: - Options that specify the conditions under which the delimiter is matched, such as SimpleMatch and Multiline. +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> _Regular expression safety_ section of [about_Comparison_Operators][01]. + ## Syntax -The following diagram shows the syntax for the -split operator. +The following diagram shows the syntax for the `-split` operator. The parameter names do not appear in the command. Include only the parameter values. The values must appear in the order specified in the syntax diagram. @@ -506,7 +511,14 @@ LastName, FirstName ## See also -- [Split-Path](xref:Microsoft.PowerShell.Management.Split-Path) -- [about_Operators](about_Operators.md) -- [about_Comparison_Operators](about_Comparison_Operators.md) -- [about_Join](about_Join.md) +- [Split-Path][05] +- [about_Operators][04] +- [about_Comparison_Operators][02] +- [about_Join][03] + + +[01]: about_Comparison_Operators.md#regular-expression-safety +[02]: about_Comparison_Operators.md +[03]: about_Join.md +[04]: about_Operators.md +[05]: xref:Microsoft.PowerShell.Management.Split-Path diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md index 09004a6eaf7..9dd32d3a42a 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -47,7 +47,7 @@ if ("$()") -eq ("$()") {} Expressions include literal values (strings or numbers), variables, and scriptblocks that return a boolean value. The `switch` statement converts all values to strings before comparison. For an example, see -[Impact of string conversion][02] later in this article. +[Impact of string conversion][01] later in this article. The `` is evaluated in expression mode. If the expression returns more than one value, such as an array or other enumerable type, the @@ -110,7 +110,7 @@ conditions. It's equivalent to an `else` clause in an `if` statement. Only one default, the comparison is case-insensitive. The **File** parameter only supports one file. If multiple **File** parameters are included, only the last one is used. For more information see the - [**File** parameter examples][01]. + [**File** parameter examples][02]. - **Regex** - Performs regular expression matching of the value to the condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$Matches` automatic variable is @@ -392,6 +392,11 @@ switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { } ``` +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the _Regular expression +> safety_ section of [about_Comparison_Operators][05]. + ### Read the content of a file with `switch` Using the `switch` statement with the **File** parameter is an efficient way to @@ -443,15 +448,16 @@ switch -File $fileEscaped { foo { 'Foo' } } ## See also - [about_Break][04] -- [about_Continue][05] -- [about_If][06] -- [about_Script_Blocks][07] +- [about_Continue][06] +- [about_If][07] +- [about_Script_Blocks][08] -[01]: #read-the-content-of-a-file-with-switch -[02]: #impact-of-string-conversion +[01]: #impact-of-string-conversion +[02]: #read-the-content-of-a-file-with-switch [03]: about_Automatic_Variables.md [04]: about_break.md -[05]: about_Continue.md -[06]: about_If.md -[07]: about_Script_Blocks.md +[05]: about_Comparison_Operators.md#regular-expression-safety +[06]: about_Continue.md +[07]: about_If.md +[08]: about_Script_Blocks.md diff --git a/reference/7.7/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md b/reference/7.7/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md index e1fe530b454..60aaec17141 100644 --- a/reference/7.7/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md +++ b/reference/7.7/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md @@ -1,7 +1,7 @@ --- description: Describes the features of PowerShell that use ANSI escape sequences and the terminal hosts that support them. Locale: en-US -ms.date: 12/09/2025 +ms.date: 07/02/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_ansi_terminals?view=powershell-7.7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_ANSI_Terminals @@ -89,7 +89,9 @@ The following members control how or when ANSI formatting is used: - `PlainText`: ANSI escape sequences are always stripped so that it's only plain text. In remote sessions, if the remote host is set to `PlainText`, the output is stripped of ANSI escape sequences before sending it back to - the local client. + the local client. This mode removes text formatting and rendering + sequences. It's not intended to be a comprehensive terminal-control + sanitization mechanism. - `Host`: This is the default behavior. The ANSI escape sequences are removed from redirected or piped output. For more information, see [Redirecting output][02]. diff --git a/reference/7.7/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/7.7/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index 8c9ffb7b35c..aa31f4824f5 100644 --- a/reference/7.7/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/7.7/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that compare values in PowerShell. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Comparison_Operators @@ -60,12 +60,12 @@ case-sensitive operator. To make a comparison operator case-sensitive, add a To make the case-insensitivity explicit, add an `i` after `-`. For example, `-ieq` is the explicitly case-insensitive version of `-eq`. -String comparisons use the [InvariantCulture][01] for both case-sensitive and +String comparisons use the [InvariantCulture][15] for both case-sensitive and case-insensitive comparisons. The comparisons are between unicode code points and don't use culture-specific collation ordering. The results are the same regardless of the current culture. -When the left-hand value in the comparison expression is a [scalar][15] value, +When the left-hand value in the comparison expression is a [scalar][03] value, the operator returns a **Boolean** value. When the left-hand value in the expression is a collection, the operator returns the elements of the collection that match the right-hand value of the expression. Right-hand values are always @@ -176,9 +176,9 @@ False In this example, we created two objects with identical properties. Yet, the equality test result is **False** because they're different objects. To create -comparable classes, you need to implement [System.IEquatable\][03] in your +comparable classes, you need to implement [System.IEquatable\][17] in your class. The following example demonstrates the partial implementation of a -**MyFileInfoSet** class that implements [System.IEquatable\][03] and has two +**MyFileInfoSet** class that implements [System.IEquatable\][17] and has two properties, **File** and **Size**. The `Equals()` method returns **True** if the File and Size properties of two **MyFileInfoSet** objects are the same. @@ -259,7 +259,7 @@ In the following examples, all statements return **True**. > [!NOTE] > In most programming languages the greater-than operator is `>`. In > PowerShell, this character is used for redirection. For details, see -> [about_Redirection][09]. +> [about_Redirection][08]. When the left-hand side is a collection, these operators compare each member of the collection with the right-hand side. Depending on their logic, they either @@ -313,7 +313,7 @@ Members smaller than or equal to 7 7 ``` -These operators work with any class that implements [System.IComparable][02]. +These operators work with any class that implements [System.IComparable][16]. Examples: @@ -372,7 +372,7 @@ used for the comparison and is obtained by casting the member to a string. ### -like and -notlike `-like` and `-notlike` behave similarly to `-eq` and `-ne`, but the right-hand -side could be a string containing [wildcards][11]. +side could be a string containing [wildcards][10]. Example: @@ -421,7 +421,12 @@ False `-match` and `-notmatch` use regular expressions to search for pattern in the left-hand side values. Regular expressions can match complex patterns like email addresses, UNC paths, or formatted phone numbers. The right-hand side -string must adhere to the [regular expressions][10] rules. +string must adhere to the [regular expressions][09] rules. + +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> [Regular expression safety][04] section of this article. Scalar examples: @@ -510,17 +515,22 @@ if ('1.0.0' -match '(.*?)') { } ``` -For details, see [about_Regular_Expressions][10] and -[about_Automatic_Variables][06]. +For details, see [about_Regular_Expressions][09] and +[about_Automatic_Variables][05]. ## Replacement operator -### Replacement with regular expressions - Like `-match`, the `-replace` operator uses regular expressions to find the specified pattern. But unlike `-match`, it replaces the matches with another specified value. +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> [Regular expression safety][04] section of this article. + +### Replacement with regular expressions + Syntax: ``` @@ -628,8 +638,8 @@ include a literal `$` in the resulting replacement. For example: '5.72' -replace '(.+)', '$$1' # Output: $1 ``` -To learn more, see [about_Regular_Expressions][10] and -[Substitutions in Regular Expressions][05]. +To learn more, see [about_Regular_Expressions][09] and +[Substitutions in Regular Expressions][02]. ### Substituting in a collection @@ -658,7 +668,7 @@ Syntax: Within the scriptblock, use the `$_` automatic variable to access the input text being replaced and other useful information. This variable's class type is -[System.Text.RegularExpressions.Match][04]. +[System.Text.RegularExpressions.Match][18]. The following example replaces each sequence of three digits with the character equivalents. The scriptblock runs for each set of three digits that needs to @@ -804,30 +814,79 @@ $b -isnot [int] # Output: True $a -isnot $b.GetType() # Output: True ``` +## Regular expression safety + +The number of comparison operations required to match a regular expression +pattern can increase exponentially if the pattern includes a large number of +alternation constructs, espcecially when it includes nested optional +quantifiers. For example, the regular expression pattern `^(a+)+$` is designed +to match a complete string that contains one or more "a" characters. The +regular expression engine must use the regular expression to follow all +possible paths through the data before it can conclude that the match is +unsuccessful, and the nested parentheses create many additional paths through +the data. + +> [!WARNING] +> A malicious user can provide input to regular expressions causing a +> [Denial-of-Service attack][11], also known as a ReDoS attack. + +To defend against ReDoS scenarios, create `[regex]` objects that specify a +timeout. The regex engine terminates the search for a match when it exceeds the +time limit. For example, the following code creates a regex object with a +2-second timeout: + +```powershell +$pattern = '^(a+)+$' +$regexOptions = 'None' +$matchTimeout = [timespan]::FromSeconds(2) +$regex = [regex]::new($pattern, $regexOptions, $matchTimeout) +$regex.IsMatch('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaX') +``` + +After 2 seconds, the regex engine terminates the search and returns the +following error: + +```Output +MethodInvocationException: Exception calling "IsMatch" with "1" argument(s): +"The Regex engine has timed out while trying to match a pattern to an input +string. This can occur for many reasons, including very large inputs or +excessive backtracking caused by nested quantifiers, back-references and other +factors." +``` + +For more information about the `[regex]` class and regex performance, see the +following articles: + +- [System.Text.RegularExpressions.Regex][19] +- [Backtracking in .NET regular expressions][01] + ## See also -- [about_Booleans][07] -- [about_Operators][08] -- [about_Regular_Expressions][10] -- [about_Wildcards][11] +- [about_Booleans][06] +- [about_Operators][07] +- [about_Regular_Expressions][09] +- [about_Wildcards][10] - [Compare-Object][14] - [ForEach-Object][12] - [Where-Object][13] -[01]: /dotnet/api/system.globalization.cultureinfo.invariantculture -[02]: /dotnet/api/system.icomparable -[03]: /dotnet/api/system.iequatable-1 -[04]: /dotnet/api/system.text.regularexpressions.match -[05]: /dotnet/standard/base-types/substitutions-in-regular-expressions -[06]: about_Automatic_Variables.md -[07]: about_Booleans.md -[08]: about_Operators.md -[09]: about_Redirection.md#potential-confusion-with-comparison-operators -[10]: about_Regular_Expressions.md -[11]: about_Wildcards.md +[01]: /dotnet/standard/base-types/backtracking-in-regular-expressions +[02]: /dotnet/standard/base-types/substitutions-in-regular-expressions +[03]: /powershell/scripting/learn/glossary#scalar-value +[04]: #regular-expression-safety +[05]: about_Automatic_Variables.md +[06]: about_Booleans.md +[07]: about_Operators.md +[08]: about_Redirection.md#potential-confusion-with-comparison-operators +[09]: about_Regular_Expressions.md +[10]: about_Wildcards.md +[11]: https://www.cisa.gov/news-events/news/understanding-denial-service-attacks [12]: xref:Microsoft.PowerShell.Core.ForEach-Object [13]: xref:Microsoft.PowerShell.Core.Where-Object [14]: xref:Microsoft.PowerShell.Utility.Compare-Object -[15]: /powershell/scripting/learn/glossary#scalar-value - +[15]: xref:System.Globalization.CultureInfo.InvariantCulture%2A +[16]: xref:System.IComparable +[17]: xref:System.IEquatable%601 +[18]: xref:System.Text.RegularExpressions.Match +[19]: xref:System.Text.RegularExpressions.Regex diff --git a/reference/7.7/Microsoft.PowerShell.Core/About/about_Error_Handling.md b/reference/7.7/Microsoft.PowerShell.Core/About/about_Error_Handling.md index 705a776b3ee..b8dc03064c8 100644 --- a/reference/7.7/Microsoft.PowerShell.Core/About/about_Error_Handling.md +++ b/reference/7.7/Microsoft.PowerShell.Core/About/about_Error_Handling.md @@ -1,7 +1,7 @@ --- description: Describes the types of errors in PowerShell and the mechanisms for handling them. Locale: en-US -ms.date: 06/02/2026 +ms.date: 07/02/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_error_handling?view=powershell-7.7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Error_Handling @@ -254,19 +254,19 @@ The scope of the escalated error depends on context: & { param() $ErrorActionPreference = 'Stop' - Get-Item 'NoSuchPath' + 1/0 # Divide by zero error } 2>$null 'after' ``` -- ADVANCED: script-terminating ('after' does NOT print) +- ADVANCED: statement-terminating ('after' DOES print) ```powershell & { [CmdletBinding()] param() $ErrorActionPreference = 'Stop' - Get-Item 'NoSuchPath' + 1/0 # Divide by zero error } 2>$null 'after' ``` diff --git a/reference/7.7/Microsoft.PowerShell.Core/About/about_Split.md b/reference/7.7/Microsoft.PowerShell.Core/About/about_Split.md index d0d686c14ce..61ddbfa94ec 100644 --- a/reference/7.7/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/7.7/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,7 +1,7 @@ --- description: Explains how to use the Split operator to split one or more strings into substrings. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_split?view=powershell-7.7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Split @@ -28,9 +28,14 @@ change the following elements of the Split operation: - Options that specify the conditions under which the delimiter is matched, such as SimpleMatch and Multiline. +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the +> _Regular expression safety_ section of [about_Comparison_Operators][01]. + ## Syntax -The following diagram shows the syntax for the -split operator. +The following diagram shows the syntax for the `-split` operator. The parameter names do not appear in the command. Include only the parameter values. The values must appear in the order specified in the syntax diagram. @@ -506,7 +511,14 @@ LastName, FirstName ## See also -- [Split-Path](xref:Microsoft.PowerShell.Management.Split-Path) -- [about_Operators](about_Operators.md) -- [about_Comparison_Operators](about_Comparison_Operators.md) -- [about_Join](about_Join.md) +- [Split-Path][05] +- [about_Operators][04] +- [about_Comparison_Operators][02] +- [about_Join][03] + + +[01]: about_Comparison_Operators.md#regular-expression-safety +[02]: about_Comparison_Operators.md +[03]: about_Join.md +[04]: about_Operators.md +[05]: xref:Microsoft.PowerShell.Management.Split-Path diff --git a/reference/7.7/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.7/Microsoft.PowerShell.Core/About/about_Switch.md index 60ecebb9521..0518be7c35d 100644 --- a/reference/7.7/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.7/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 01/18/2026 +ms.date: 07/01/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -47,7 +47,7 @@ if ("$()") -eq ("$()") {} Expressions include literal values (strings or numbers), variables, and scriptblocks that return a boolean value. The `switch` statement converts all values to strings before comparison. For an example, see -[Impact of string conversion][02] later in this article. +[Impact of string conversion][01] later in this article. The `` is evaluated in expression mode. If the expression returns more than one value, such as an array or other enumerable type, the @@ -110,7 +110,7 @@ conditions. It's equivalent to an `else` clause in an `if` statement. Only one default, the comparison is case-insensitive. The **File** parameter only supports one file. If multiple **File** parameters are included, only the last one is used. For more information see the - [**File** parameter examples][01]. + [**File** parameter examples][02]. - **Regex** - Performs regular expression matching of the value to the condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$Matches` automatic variable is @@ -392,6 +392,11 @@ switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { } ``` +> [!NOTE] +> Poorly designed or maliciously crafted regular expressions can create denial +> of service conditions. For more information, see the _Regular expression +> safety_ section of [about_Comparison_Operators][05]. + ### Read the content of a file with `switch` Using the `switch` statement with the **File** parameter is an efficient way to @@ -443,15 +448,16 @@ switch -File $fileEscaped { foo { 'Foo' } } ## See also - [about_Break][04] -- [about_Continue][05] -- [about_If][06] -- [about_Script_Blocks][07] +- [about_Continue][06] +- [about_If][07] +- [about_Script_Blocks][08] -[01]: #read-the-content-of-a-file-with-switch -[02]: #impact-of-string-conversion +[01]: #impact-of-string-conversion +[02]: #read-the-content-of-a-file-with-switch [03]: about_Automatic_Variables.md [04]: about_break.md -[05]: about_Continue.md -[06]: about_If.md -[07]: about_Script_Blocks.md +[05]: about_Comparison_Operators.md#regular-expression-safety +[06]: about_Continue.md +[07]: about_If.md +[08]: about_Script_Blocks.md diff --git a/reference/docs-conceptual/community/2026-updates.md b/reference/docs-conceptual/community/2026-updates.md index ac77e8d4e37..be008f085e0 100644 --- a/reference/docs-conceptual/community/2026-updates.md +++ b/reference/docs-conceptual/community/2026-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2026. -ms.date: 06/13/2026 +ms.date: 07/02/2026 title: What's New in PowerShell-Docs for 2026 --- # What's new in PowerShell Docs for 2026 @@ -15,6 +15,38 @@ get started. [01]: contributing/overview.md +## 2026-June + +Updated content + +- Release notes for monthly maintenance releases of PowerShell +- Major cleanup of PSScriptAnalyzer + [rules documentation](/powershell/utility-modules/psscriptanalyzer/rules/readme), including + refactoring the rules table. The rules table now shows which rules are always enabled, and which + rules can be configured or disabled. + +GitHub stats + +- 46 PRs merged (8 from Community) +- 42 issues opened (11 from Community, 31 Spam) +- 43 issues closed (12 from Community, 31 Spam) + +Top Community Contributors + +The following people contributed to PowerShell docs this month by submitting pull requests or +filing issues. Thank you! + +Special thanks to @ArieHein for another large PR to clean up 160 articles. + +| GitHub Id | PRs merged | Issues opened | +| --------------------- | :--------: | :-----------: | +| ArieHein | 1 | | +| baardhermansen | 4 | | +| michael-hollingsworth | 1 | | +| naffee | 1 | | +| PtJade-Ceramic | 1 | 1 | +| trashCode | | 2 | + ## 2026-May Updated content diff --git a/reference/docs-conceptual/community/hall-of-fame.md b/reference/docs-conceptual/community/hall-of-fame.md index e3363196692..51a9f31d380 100644 --- a/reference/docs-conceptual/community/hall-of-fame.md +++ b/reference/docs-conceptual/community/hall-of-fame.md @@ -1,6 +1,6 @@ --- description: List of the GitHub users that have the most contributions to PowerShell documentation. -ms.date: 06/13/2026 +ms.date: 07/02/2026 title: Community contributor Hall of Fame --- # Community Contributor Hall of Fame @@ -18,7 +18,7 @@ Pull Requests help us fix those issues and make the documentation better for eve | PRs Merged | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025 | 2026 | Total | | ------------------ | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ----: | -| Community | 8 | 189 | 452 | 468 | 321 | 165 | 101 | 134 | 117 | 95 | 160 | 21 | 2231 | +| Community | 8 | 189 | 452 | 468 | 321 | 165 | 101 | 134 | 117 | 95 | 160 | 28 | 2238 | | matt9ucci | | | 157 | 80 | 30 | 1 | 6 | | | | | | 274 | | nschonni | | | | 14 | 138 | 10 | | | | | | | 162 | | kiazhi | | 25 | 79 | 12 | | | | | | | | | 116 | @@ -27,7 +27,7 @@ Pull Requests help us fix those issues and make the documentation better for eve | doctordns | | 5 | 32 | 20 | 7 | 9 | 5 | | 1 | | | | 79 | | surfingoldelephant | | | | | | | | | | | 58 | 5 | 63 | | ehmiiz | | | | | | | | 22 | 14 | | | | 36 | -| ArieHein | | | | | 1 | | | | | 8 | 25 | | 34 | +| ArieHein | | | | | 1 | | | | | 8 | 25 | 1 | 35 | | yecril71pl | | | | | | 21 | 3 | 3 | | | | | 27 | | changeworld | | | | | | | | 3 | | | 22 | | 25 | | skycommand | | | 1 | 3 | 3 | 6 | | 1 | 4 | 1 | 4 | | 23 | @@ -42,6 +42,7 @@ Pull Requests help us fix those issues and make the documentation better for eve | markekraus | | | 11 | 1 | | | | | | | | | 12 | | exchange12rocks | | | 7 | 3 | | | 1 | | | | | 1 | 12 | | hrxn | | | | | | | 2 | 2 | 2 | 5 | | | 11 | +| baardhermansen | | | | | 2 | 1 | | 1 | 2 | | | 5 | 11 | ## GitHub issues opened @@ -49,7 +50,7 @@ GitHub issues help us identify errors and gaps in our documentation. | Issues Opened | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025 | 2026 | Total | | ------------------ | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ----: | -| Community | 6 | 52 | 96 | 213 | 567 | 564 | 367 | 244 | 291 | 243 | 182 | 65 | 2890 | +| Community | 6 | 52 | 96 | 213 | 567 | 563 | 367 | 244 | 291 | 243 | 182 | 74 | 2898 | | mklement0 | | | 19 | 60 | 56 | 61 | 28 | 8 | 20 | 24 | 2 | | 278 | | ehmiiz | | | | | | | | 21 | 14 | | | | 35 | | iRon7 | | | | | | 2 | 2 | 2 | 10 | 8 | 8 | | 32 | @@ -67,8 +68,8 @@ GitHub issues help us identify errors and gaps in our documentation. | alexandair | | 9 | 4 | 2 | | | | | | | | | 15 | | clamb123 | | | | | | | 14 | | | | | | 14 | | tabad | | | | | | | | | 11 | 2 | | | 13 | -| trollyanov | | | | | | | 11 | 1 | | | | | 12 | | ThomasNieto | | | | | | 3 | | 2 | 4 | 3 | | | 12 | +| trollyanov | | | | | | | 11 | 1 | | | | | 12 | | LaurentDardenne | | | 3 | 2 | | | | 5 | 2 | | | | 12 | | Liturgist | | | | | 1 | 1 | 1 | 2 | 5 | 2 | | | 12 | | jsilverm | | | | | | 8 | | | 4 | | | | 12 |