diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 99c6e1f5bd35..3f838c2554aa 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -1,7 +1,7 @@ --- description: Describes regular expressions in PowerShell. Locale: en-US -ms.date: 06/14/2024 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_regular_expressions?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Regular_Expressions @@ -17,19 +17,20 @@ Describes regular expressions in PowerShell. > [!NOTE] > This article shows the syntax and methods for using regular expressions in > PowerShell. It doesn't cover all possible expressions. For a more complete -> reference, see the [Regular Expression Language - Quick Reference][03]. +> reference, see the [Regular Expression Language - Quick Reference][02]. A regular expression is a pattern used to match text. It can be made up of -literal characters, operators, and other constructs. +literal characters, operators, and other constructs. PowerShell uses the +[.NET regex][03] engine. This article demonstrates regular expression syntax in PowerShell. PowerShell has several operators and cmdlets that use regular expressions. You can read more about their syntax and usage at the links below. -- [Select-String][10] -- [-match and -replace operators][06] -- [-split operator][08] -- [switch statement with -regex option][09] +- [Select-String][11] +- [-match and -replace operators][07] +- [-split operator][09] +- [switch statement with -regex option][10] PowerShell regular expressions are case-insensitive by default. Each method shown above has a different way to force case sensitivity. @@ -81,8 +82,8 @@ characters). ### Numbers -The `\d` character class will match any decimal digit. Conversely, `\D` will -match any character except decimal digits. +The `\d` character class matchs any decimal digit. Conversely, `\D` matches any +character except decimal digits. ```powershell # This expression returns true if it matches a server name. @@ -92,7 +93,7 @@ match any character except decimal digits. ### Word characters -The `\w` character class will match any word character `[a-zA-Z_0-9]`. To match +The `\w` character class matches any word character `[a-zA-Z_0-9]`. To match any non-word character, use `\W`. ```powershell @@ -103,8 +104,8 @@ any non-word character, use `\W`. ### Wildcards -The period (`.`) is a wildcard character in regular expressions. It will match -any character except a newline (`\n`). +The period (`.`) is a wildcard character in regular expressions. It matches any +character except a newline (`\n`). ```powershell # This expression returns true. @@ -155,7 +156,7 @@ The plus sign (`+`) matches the previous element one or more times. ``` The question mark `?` matches the previous element zero or one time. Like -asterisk `*`, it will even match strings where the element is absent. +asterisk `*`, it even matches strings where the element is absent. ```powershell # This returns true for any server name, even server names without dashes. @@ -208,7 +209,7 @@ When using anchors in PowerShell, you should understand the difference between instead of matching every character EXCEPT the newline `\n`. To read more about these options and how to use them, visit the -[Regular Expression Language - Quick Reference][03]. +[Regular Expression Language - Quick Reference][02]. ## Escaping characters @@ -354,7 +355,7 @@ The provided regular expression extracts the username and domain from the message and stores them under the keys:**N** for name and **D** for domain. ```powershell -$log = (Get-EventLog -LogName Security -Newest 1 -InstanceId 4689).Message +$log = (Get-WinEvent -LogName Security -MaxEvents 1).Message $r = '(?s).*Account Name:\s*(?.*).*Account Domain:\s*(?[A-Z,0-9]*)' $log -match $r ``` @@ -372,10 +373,10 @@ Name Value ---- ----- D CONTOSO N jsmith -0 A process has exited.... +0 A process has exited... ``` -For more information, see [Grouping Constructs in Regular Expressions][02]. +For more information, see [Grouping Constructs in Regular Expressions][01]. ### Substitutions in Regular Expressions @@ -461,18 +462,32 @@ Gobble Gobble For detailed information on substitution expressions, see [Substitutions in Regular Expressions][04]. +## Comments in regular expressions + +Regular expressions can be very complex and difficult to read. You can use +comments to make them more understandable. There are two types of comments +allowed in regular expressions. + +- Inline comment (`(?#)`) +- End-of-line comment (`#`) + +For more information, see the _Regular expression comments_ section of +[about_Comments][05]. + ## See also -- [about_Operators][07] -- [about_Comparison_Operators][05] +- [about_Operators][08] +- [about_Comparison_Operators][06] -[02]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions -[03]: /dotnet/standard/base-types/regular-expression-language-quick-reference +[01]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions +[02]: /dotnet/standard/base-types/regular-expression-language-quick-reference +[03]: /dotnet/standard/base-types/regular-expressions [04]: /dotnet/standard/base-types/substitutions-in-regular-expressions -[05]: about_Comparison_Operators.md -[06]: about_Comparison_Operators.md#matching-operators -[07]: about_Operators.md -[08]: about_Split.md -[09]: about_Switch.md -[10]: xref:Microsoft.PowerShell.Utility.Select-String +[05]: about_Comments.md#regular-expression-comments +[06]: about_Comparison_Operators.md +[07]: about_Comparison_Operators.md#matching-operators +[08]: about_Operators.md +[09]: about_Split.md +[10]: about_Switch.md +[11]: xref:Microsoft.PowerShell.Utility.Select-String diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md index ae6d5184e3aa..51bd0248ba5a 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md @@ -1,7 +1,7 @@ --- description: Explains how to sign scripts so that they comply with the PowerShell execution policies. Locale: en-US -ms.date: 01/07/2025 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Signing @@ -15,7 +15,7 @@ policies. ## Long description -The Restricted execution policy doesn't permit any scripts to run. The +The **Restricted** execution policy doesn't permit any scripts to run. The **AllSigned** and **RemoteSigned** execution policies prevent PowerShell from running scripts that don't have a digital signature. @@ -141,10 +141,8 @@ certificate. Two types of certificates are suitable for signing a script file: not run on other computers. Self-signed certificate should only be used to sign scripts for testing -purposes. - -It isn't appropriate for scripts that will be shared, even within an -enterprise. +purposes. Self-signed certificates aren't appropriate for scripts that you want +to share. If you create a self-signed certificate, be sure to enable strong private key protection on your certificate. This prevents malicious programs from signing @@ -220,7 +218,7 @@ Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My Thumbprint Subject ---------- ------- -4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ] +4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ``` ## Sign a script @@ -265,6 +263,10 @@ $cert = Get-ChildItem Cert:\CurrentUser\My -CodeSigningCert | Set-AuthenticodeSignature add-signature.ps1 $cert ``` +The `Set-AuthenticodeSignature` cmdlet adds the signature to the script file as +a comment block at the end of the file. The comment block begins and ends with +`# SIG #`. + After you sign the script, you can run it on the local computer. However, the script won't run on computers where the PowerShell execution policy requires a digital signature from a trusted authority. If you try, PowerShell displays the diff --git a/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index 9a69a1d1e988..cd5e88bd7f6c 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Json.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: 11/29/2023 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-json?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertFrom-Json @@ -35,10 +35,11 @@ To generate a JSON string from any object, use the `ConvertTo-Json` cmdlet. This cmdlet was introduced in PowerShell 3.0. > [!NOTE] -> Beginning with PowerShell 6, the cmdlet supports JSON with comments. JSON comments start with two -> forward slashes (`//`) characters. JSON comments aren't captured in the objects output by the -> cmdlet. Prior to PowerShell 6, `ConvertFrom-Json` would return an error when it encountered a JSON -> comment. +> In Windows PowerShell 5.1, `ConvertFrom-Json` returns an error when it encounters a JSON +> comment. In PowerShell 6 and higher, the cmdlet supports JSON with comments. JSON comments aren't +> captured in the objects output by the cmdlet. For more information, see the _JSON comments_ +> section of the +> [about_Comments](/powershell/module/microsoft.powershell.core/about/about_comments) article. ## EXAMPLES diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Invoke-RestMethod.md b/reference/5.1/Microsoft.PowerShell.Utility/Invoke-RestMethod.md index 581920411115..e84f1d73d13d 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Invoke-RestMethod.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Invoke-RestMethod.md @@ -32,7 +32,8 @@ The `Invoke-RestMethod` cmdlet sends HTTP and HTTPS requests to Representational PowerShell formats the response based to the data type. For an RSS or ATOM feed, PowerShell returns the Item or Entry XML nodes. For JavaScript Object Notation (JSON) or XML, PowerShell converts, or -deserializes, the content into `[PSCustomObject]` objects. +deserializes, the content into `[PSCustomObject]` objects. Comments aren't permitted in the JSON +data. > [!NOTE] > When the REST endpoint returns multiple objects, the objects are received as an array. If you pipe @@ -205,11 +206,11 @@ Accept wildcard characters: False ### -Certificate -Specifies the client certificate that is used for a secure web request. Enter a variable that +Specifies the client certificate that's used for a secure web request. Enter a variable that contains a certificate or a command or expression that gets the certificate. To find a certificate, use `Get-PfxCertificate` or use the `Get-ChildItem` cmdlet in the Certificate -(`Cert:`) drive. If the certificate is not valid or does not have sufficient authority, the command +(`Cert:`) drive. If the certificate isn't valid or doesn't have sufficient authority, the command fails. ```yaml @@ -252,7 +253,7 @@ Accept wildcard characters: False Specifies the content type of the web request. If this parameter is omitted and the request method is POST, `Invoke-RestMethod` sets the content -type to "application/x-www-form-urlencoded". Otherwise, the content type is not specified in the +type to `application/x-www-form-urlencoded`. Otherwise, the content type isn't specified in the call. ```yaml @@ -305,7 +306,7 @@ Aliases: Required: False Position: Named -Default value: KeepAlive +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -453,14 +454,14 @@ Accept wildcard characters: False ### -ProxyCredential -Specifies a user account that has permission to use the proxy server that is specified by the +Specifies a user account that has permission to use the proxy server that's specified by the **Proxy** parameter. The default is the current user. -Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as -one generated by the `Get-Credential` cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such +as one generated by the `Get-Credential` cmdlet. -This parameter is valid only when the **Proxy** parameter is also used in the command. You cannot -use the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command. +This parameter is valid only when the **Proxy** parameter is also used in the command. You can't use +the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command. ```yaml Type: System.Management.Automation.PSCredential @@ -479,8 +480,8 @@ Accept wildcard characters: False Uses the credentials of the current user to access the proxy server that is specified by the **Proxy** parameter. -This parameter is valid only when the **Proxy** parameter is also used in the command. You cannot -use the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command. +This parameter is valid only when the **Proxy** parameter is also used in the command. You can't use +the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command. ```yaml Type: System.Management.Automation.SwitchParameter @@ -576,7 +577,7 @@ Accept wildcard characters: False ### -Uri -Specifies the Uniform Resource Identifier (URI) of the Internet resource to which the web request is +Specifies the Uniform Resource Identifier (URI) of the internet resource to which the web request is sent. This parameter supports HTTP, HTTPS, FTP, and FILE values. This parameter is required. The parameter name (**Uri**) is optional. @@ -630,12 +631,13 @@ Accept wildcard characters: False Specifies a user agent string for the web request. -The default user agent is similar to "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) -WindowsPowerShell/3.0" with slight variations for each operating system and platform. +The default user agent is similar to +`Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0` with slight +variations for each operating system and platform. -To test a website with the standard user agent string that is used by most Internet browsers, use -the properties of the [PSUserAgent](/dotnet/api/microsoft.powershell.commands) class, such as -Chrome, Firefox, Internet Explorer, Opera, and Safari. +To test a website with the standard user agent string that's used by most internet browsers, use +the properties of the [PSUserAgent](xref:Microsoft.PowerShell.Commands.PSUserAgent) class, such as +Chrome, Firefox, InternetExplorer, Opera, and Safari. ```yaml Type: System.String @@ -656,17 +658,17 @@ Specifies a web request session. Enter the variable name, including the dollar s To override a value in the web request session, use a cmdlet parameter, such as **UserAgent** or **Credential**. Parameter values take precedence over values in the web request session. -Unlike a remote session, the web request session is not a persistent connection. It is an object -that contains information about the connection and the request, including cookies, credentials, the +Unlike a remote session, the web request session isn't a persistent connection. It's an object that +contains information about the connection and the request, including cookies, credentials, the maximum redirection value, and the user agent string. You can use it to share state and data among web requests. -To create a web request session, enter a variable name (without a dollar sign) in the value of the +To create a web request session, enter a variable name, without a dollar sign, in the value of the **SessionVariable** parameter of an `Invoke-RestMethod` command. `Invoke-RestMethod` creates the session and saves it in the variable. In subsequent commands, use the variable as the value of the **WebSession** parameter. -You cannot use the **SessionVariable** and **WebSession** parameters in the same command. +You can't use the **SessionVariable** and **WebSession** parameters in the same command. ```yaml Type: Microsoft.PowerShell.Commands.WebRequestSession diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index a9a6792d4d23..7d58eda17237 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -1,7 +1,7 @@ --- description: Describes regular expressions in PowerShell. Locale: en-US -ms.date: 06/14/2024 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_regular_expressions?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Regular_Expressions @@ -17,19 +17,20 @@ Describes regular expressions in PowerShell. > [!NOTE] > This article shows the syntax and methods for using regular expressions in > PowerShell. It doesn't cover all possible expressions. For a more complete -> reference, see the [Regular Expression Language - Quick Reference][03]. +> reference, see the [Regular Expression Language - Quick Reference][02]. A regular expression is a pattern used to match text. It can be made up of -literal characters, operators, and other constructs. +literal characters, operators, and other constructs. PowerShell uses the +[.NET regex][03] engine. This article demonstrates regular expression syntax in PowerShell. PowerShell has several operators and cmdlets that use regular expressions. You can read more about their syntax and usage at the links below. -- [Select-String][10] -- [-match and -replace operators][06] -- [-split operator][08] -- [switch statement with -regex option][09] +- [Select-String][11] +- [-match and -replace operators][07] +- [-split operator][09] +- [switch statement with -regex option][10] PowerShell regular expressions are case-insensitive by default. Each method shown above has a different way to force case sensitivity. @@ -81,8 +82,8 @@ characters). ### Numbers -The `\d` character class will match any decimal digit. Conversely, `\D` will -match any character except decimal digits. +The `\d` character class matchs any decimal digit. Conversely, `\D` matches any +character except decimal digits. ```powershell # This expression returns true if it matches a server name. @@ -92,7 +93,7 @@ match any character except decimal digits. ### Word characters -The `\w` character class will match any word character `[a-zA-Z_0-9]`. To match +The `\w` character class matches any word character `[a-zA-Z_0-9]`. To match any non-word character, use `\W`. ```powershell @@ -103,8 +104,8 @@ any non-word character, use `\W`. ### Wildcards -The period (`.`) is a wildcard character in regular expressions. It will match -any character except a newline (`\n`). +The period (`.`) is a wildcard character in regular expressions. It matches any +character except a newline (`\n`). ```powershell # This expression returns true. @@ -155,7 +156,7 @@ The plus sign (`+`) matches the previous element one or more times. ``` The question mark `?` matches the previous element zero or one time. Like -asterisk `*`, it will even match strings where the element is absent. +asterisk `*`, it even matches strings where the element is absent. ```powershell # This returns true for any server name, even server names without dashes. @@ -208,7 +209,7 @@ When using anchors in PowerShell, you should understand the difference between instead of matching every character EXCEPT the newline `\n`. To read more about these options and how to use them, visit the -[Regular Expression Language - Quick Reference][03]. +[Regular Expression Language - Quick Reference][02]. ## Escaping characters @@ -372,10 +373,10 @@ Name Value ---- ----- D CONTOSO N jsmith -0 A process has exited.... +0 A process has exited... ``` -For more information, see [Grouping Constructs in Regular Expressions][02]. +For more information, see [Grouping Constructs in Regular Expressions][01]. ### Substitutions in Regular Expressions @@ -461,18 +462,32 @@ Gobble Gobble For detailed information on substitution expressions, see [Substitutions in Regular Expressions][04]. +## Comments in regular expressions + +Regular expressions can be very complex and difficult to read. You can use +comments to make them more understandable. There are two types of comments +allowed in regular expressions. + +- Inline comment (`(?#)`) +- End-of-line comment (`#`) + +For more information, see the _Regular expression comments_ section of +[about_Comments][05]. + ## See also -- [about_Operators][07] -- [about_Comparison_Operators][05] +- [about_Operators][08] +- [about_Comparison_Operators][06] -[02]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions -[03]: /dotnet/standard/base-types/regular-expression-language-quick-reference +[01]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions +[02]: /dotnet/standard/base-types/regular-expression-language-quick-reference +[03]: /dotnet/standard/base-types/regular-expressions [04]: /dotnet/standard/base-types/substitutions-in-regular-expressions -[05]: about_Comparison_Operators.md -[06]: about_Comparison_Operators.md#matching-operators -[07]: about_Operators.md -[08]: about_Split.md -[09]: about_Switch.md -[10]: xref:Microsoft.PowerShell.Utility.Select-String +[05]: about_Comments.md#regular-expression-comments +[06]: about_Comparison_Operators.md +[07]: about_Comparison_Operators.md#matching-operators +[08]: about_Operators.md +[09]: about_Split.md +[10]: about_Switch.md +[11]: xref:Microsoft.PowerShell.Utility.Select-String diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Signing.md index 4efc99d0e5fa..ce7770cd155e 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Signing.md @@ -1,7 +1,7 @@ --- description: Explains how to sign scripts so that they comply with the PowerShell execution policies. Locale: en-US -ms.date: 01/07/2025 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Signing @@ -17,7 +17,7 @@ policies. > This information only applies to PowerShell running on Windows. -The Restricted execution policy doesn't permit any scripts to run. The +The **Restricted** execution policy doesn't permit any scripts to run. The **AllSigned** and **RemoteSigned** execution policies prevent PowerShell from running scripts that don't have a digital signature. @@ -143,10 +143,8 @@ certificate. Two types of certificates are suitable for signing a script file: not run on other computers. Self-signed certificate should only be used to sign scripts for testing -purposes. - -It isn't appropriate for scripts that will be shared, even within an -enterprise. +purposes. Self-signed certificates aren't appropriate for scripts that you want +to share. If you create a self-signed certificate, be sure to enable strong private key protection on your certificate. This prevents malicious programs from signing @@ -222,7 +220,7 @@ Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My Thumbprint Subject ---------- ------- -4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ] +4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ``` ## Sign a script @@ -267,6 +265,10 @@ $cert = Get-ChildItem Cert:\CurrentUser\My -CodeSigningCert | Set-AuthenticodeSignature add-signature.ps1 $cert ``` +The `Set-AuthenticodeSignature` cmdlet adds the signature to the script file as +a comment block at the end of the file. The comment block begins and ends with +`# SIG #`. + After you sign the script, you can run it on the local computer. However, the script won't run on computers where the PowerShell execution policy requires a digital signature from a trusted authority. If you try, PowerShell displays the diff --git a/reference/7.4/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/7.4/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index cca0870f8509..14f4a9c7973d 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/ConvertFrom-Json.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: 11/29/2023 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-json?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertFrom-Json @@ -35,10 +35,11 @@ To generate a JSON string from any object, use the `ConvertTo-Json` cmdlet. This cmdlet was introduced in PowerShell 3.0. > [!NOTE] -> Beginning with PowerShell 6, the cmdlet supports JSON with comments. JSON comments start with two -> forward slashes (`//`) characters. JSON comments aren't captured in the objects output by the -> cmdlet. Prior to PowerShell 6, `ConvertFrom-Json` would return an error when it encountered a JSON -> comment. +> In Windows PowerShell 5.1, `ConvertFrom-Json` returned an error when it encountered a JSON +> comment. In PowerShell 6 and higher, the cmdlet supports JSON with comments. JSON comments aren't +> captured in the objects output by the cmdlet. For more information, see the _JSON comments_ +> section of the +> [about_Comments](/powershell/module/microsoft.powershell.core/about/about_comments) article. ## EXAMPLES diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Invoke-RestMethod.md b/reference/7.4/Microsoft.PowerShell.Utility/Invoke-RestMethod.md index 11042b730684..ec6eab009030 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Invoke-RestMethod.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Invoke-RestMethod.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: 11/18/2024 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-restmethod?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Invoke-RestMethod @@ -99,17 +99,17 @@ The `Invoke-RestMethod` cmdlet sends HTTP and HTTPS requests to Representational PowerShell formats the response based to the data type. For an RSS or ATOM feed, PowerShell returns the Item or Entry XML nodes. For JavaScript Object Notation (JSON) or XML, PowerShell converts, or -deserializes, the content into `[PSCustomObject]` objects. +deserializes, the content into `[PSCustomObject]` objects. Comments are permitted in the JSON data. > [!NOTE] > When the REST endpoint returns multiple objects, the objects are received as an array. If you pipe -> the output from `Invoke-RestMethod` to another command, it is sent as a single `[Object[]]` -> object. The contents of that array are not enumerated for the next command on the pipeline. +> the output from `Invoke-RestMethod` to another command, it's sent as a single `[Object[]]` +> object. The contents of that array aren't enumerated for the next command on the pipeline. This cmdlet is introduced in Windows PowerShell 3.0. Beginning in PowerShell 7.0, `Invoke-RestMethod` supports proxy configuration defined by environment -variables. See the [Notes](#notes) section of this article. +variables. See the [NOTES](#notes) section of this article. Beginning in PowerShell 7.4, character encoding for requests defaults to UTF-8 instead of ASCII. If you need a different encoding, you must set the `charset` attribute in the `Content-Type` header. @@ -159,8 +159,8 @@ $Body = @{ Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv ``` -The credentials are prompted for and then stored in `$Cred` and the URL that will be access is -defined in `$Url`. +The cmdlet prompts for credentials and stores them in `$Cred`. `$Url` contains the REST endpoint +URL. The `$Body` variable describes the search criteria, specifies CSV as the output mode, and specifies a time period for returned data that starts two days ago and ends one day ago. The body variable @@ -202,18 +202,18 @@ $Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form The profile form requires these fields: `firstName`, `lastName`, `email`, `avatar`, `birthday`, and `hobbies`. The API is expecting an image for the user profile pic to be supplied in the `avatar` -field. The API will also accept multiple `hobbies` entries to be submitted in the same form. +field. The API also accepts multiple `hobbies` entries to be submitted in the same form. When creating the `$Form` HashTable, the key names are used as form field names. By default, the -values of the HashTable will be converted to strings. If a `System.IO.FileInfo` value is present, -the file contents will be submitted. If a collection such as arrays or lists are present, the form -field will be submitted multiple times. +values of the HashTable are converted to strings. If a `System.IO.FileInfo` value is present, the +file contents are submitted. If a collection, such as an array or list are present, the form field +is submitted multiple times. -By using `Get-Item` on the `avatar` key, the `FileInfo` object will be set as the value. The result -is that the image data for `jdoe.png` will be submitted. +By using `Get-Item` on the `avatar` key, the `FileInfo` object is set as the value. The result +is that the image data for `jdoe.png` is submitted. -By supplying a list to the `hobbies` key, the `hobbies` field will be present in the submissions -once for each list item. +By supplying a list to the `hobbies` key, the `hobbies` field is present in the submissions once for +each list item. ### Example 5: Pass multiple headers @@ -230,7 +230,7 @@ Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body ### Example 6: Enumerate returned items on the pipeline -GitHub returns multiple objects an array. If you pipe the output to another command, it is sent as a +GitHub returns multiple objects an array. If you pipe the output to another command, it's sent as a single `[Object[]]`object. To enumerate the objects into the pipeline, pipe the results to `Write-Output` or wrap the cmdlet in @@ -292,7 +292,7 @@ assigned a hash table where the value of `If-Match` is invalid because it's defi instead of `"12345"`. Calling `Invoke-RestMethod` with the invalid headers returns an error reporting that the formatted -value is invalid. The request is not sent to the endpoint. +value is invalid. The request isn't sent to the endpoint. Calling `Invoke-RestMethod` with the **SkipHeaderValidation** parameter ignores the validation failure and sends the request to the endpoint. Because the endpoint tolerates non-compliant header @@ -321,7 +321,7 @@ Invoke-RestMethod -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/r ### -AllowInsecureRedirect -Allows redirecting from HTTPS to HTTP. By default, any request that is redirected from HTTPS to +Allows redirecting from HTTPS to HTTP. By default, any request that's redirected from HTTPS to HTTP results in an error and the request is aborted to prevent unintentionally communicating in plain text over unencrypted connections. To override this behavior at your own risk, use the **AllowInsecureRedirect** parameter. @@ -343,14 +343,14 @@ Accept wildcard characters: False ### -AllowUnencryptedAuthentication Allows sending of credentials and secrets over unencrypted connections. By default, supplying -**Credential** or any **Authentication** option with a **Uri** that does not begin with `https://` -will result in an error and the request will abort to prevent unintentionally communicating secrets -in plain text over unencrypted connections. To override this behavior at your own risk, supply the +**Credential** or any **Authentication** option with a **Uri** that doesn't begin with `https://` +results in an error and the request aborts to prevent unintentionally communicating secrets in plain +text over unencrypted connections. To override this behavior at your own risk, supply the **AllowUnencryptedAuthentication** parameter. > [!WARNING] -> Using this parameter is not secure and is not recommended. It is provided only for compatibility -> with legacy systems that cannot provide encrypted connections. Use at your own risk. +> Using this parameter isn't secure and isn't recommended. It's provided only for compatibility +> with legacy systems that can't provide encrypted connections. Use at your own risk. This feature was added in PowerShell 6.0.0. @@ -373,9 +373,9 @@ The **Authentication** parameter can't be used with the **UseDefaultCredentials* Available Authentication Options: -- `None`: This is the default option when **Authentication** is not supplied. No explicit - authentication will be used. -- `Basic`: Requires **Credential**. The credentials will be used to send an RFC 7617 Basic +- `None`: This is the default option when **Authentication** isn't supplied. No explicit + authentication is used. +- `Basic`: Requires **Credential**. The credentials are used to send an RFC 7617 Basic Authentication `Authorization: Basic` header in the format of `base64(user:password)`. - `Bearer`: Requires the **Token** parameter. Sends an RFC 6750 `Authorization: Bearer` header with the supplied token. @@ -426,11 +426,11 @@ parameter. When the body is a form, or it's the output of another `Invoke-WebRequest` call, PowerShell sets the request content to the form fields. -The **Body** parameter may also accept a **System.Net.Http.MultipartFormDataContent** object. This -will facilitate `multipart/form-data` requests. When a **MultipartFormDataContent** object is -supplied for **Body**, any content related headers supplied to the **ContentType**, **Headers**, or -**WebSession** parameters will be overridden by the content headers of the -`MultipartFormDataContent` object. This feature was added in PowerShell 6.0.0. +The **Body** parameter can also accept a **System.Net.Http.MultipartFormDataContent** object, which +facilitates `multipart/form-data` requests. When a **MultipartFormDataContent** object is supplied +for **Body**, any content related headers supplied to the **ContentType**, **Headers**, or +**WebSession** parameters are overridden by the content headers of the `MultipartFormDataContent` +object. This feature was added in PowerShell 6.0.0. ```yaml Type: System.Object @@ -446,7 +446,7 @@ Accept wildcard characters: False ### -Certificate -Specifies the client certificate that is used for a secure web request. Enter a variable that +Specifies the client certificate that's used for a secure web request. Enter a variable that contains a certificate or a command or expression that gets the certificate. To find a certificate, use `Get-PfxCertificate` or use the `Get-ChildItem` cmdlet in the Certificate @@ -530,8 +530,7 @@ If this parameter is omitted and the request method is POST, `Invoke-RestMethod` type to `application/x-www-form-urlencoded`. Otherwise, the content type isn't specified in the call. -**ContentType** will be overridden when a `MultipartFormDataContent` object is supplied for -**Body**. +**ContentType** is overridden when a `MultipartFormDataContent` object is supplied for **Body**. Starting in PowerShell 7.4, if you use this both this parameter and the **Headers** parameter to define the `Content-Type` header, the value specified in the **ContentType** parameter is used. @@ -555,10 +554,10 @@ Specifies a user account that has permission to send the request. The default is Type a user name, such as **User01** or **Domain01\User01**, or enter a **PSCredential** object generated by the `Get-Credential` cmdlet. -**Credential** can be used alone or in conjunction with certain **Authentication** parameter -options. When used alone, it will only supply credentials to the remote server if the remote server +You can use **Credential** alone or in conjunction with certain **Authentication** parameter +options. When used alone, it only supplies credentials to the remote server if the remote server sends an authentication challenge request. When used with **Authentication** options, the -credentials will be explicitly sent. +credentials is explicitly sent. Credentials are stored in a [PSCredential](/dotnet/api/system.management.automation.pscredential) object and the password is stored as a [SecureString](/dotnet/api/system.security.securestring). @@ -582,7 +581,7 @@ Accept wildcard characters: False ### -CustomMethod Specifies custom method used for the web request. This can be used with the Request Method required -by the endpoint is not an available option on the **Method**. **Method** and **CustomMethod** cannot +by the endpoint isn't an available option on the **Method**. **Method** and **CustomMethod** can't be used together. Example: @@ -607,9 +606,8 @@ Accept wildcard characters: False ### -DisableKeepAlive -Indicates that the cmdlet sets the **KeepAlive** value in the HTTP header to False. By default, -**KeepAlive** is True. **KeepAlive** establishes a persistent connection to the server to facilitate -subsequent requests. +Sets the **KeepAlive** value in the HTTP header to False. By default, **KeepAlive** is True. +**KeepAlive** establishes a persistent connection to the server to facilitate subsequent requests. ```yaml Type: System.Management.Automation.SwitchParameter @@ -628,9 +626,9 @@ Accept wildcard characters: False Indicates the cmdlet should follow relation links. Some REST APIs support pagination via Relation Links per -[RFC5988](https://tools.ietf.org/html/rfc5988#page-6). Instead of parsing the header to get the URL -for the next page, you can have the cmdlet do this for you. To set how many times to follow relation -links, use the **MaximumFollowRelLink** parameter. +[RFC5988](https://tools.ietf.org/html/rfc5988#section-5). Instead of parsing the header to get the +URL for the next page, you can have the cmdlet do this for you. To set how many times to follow +relation links, use the **MaximumFollowRelLink** parameter. When using this switch, the cmdlet returns a collection of pages of results. Each page of results may contain multiple result items. @@ -652,15 +650,14 @@ Accept wildcard characters: False ### -Form Converts a dictionary to a `multipart/form-data` submission. **Form** may not be used with **Body**. -If **ContentType** will be ignored. +The **ContentType** is ignored. -The keys of the dictionary will be used as the form field names. By default, form values will be -converted to string values. +The keys of the dictionary are used as the form field names. By default, form values are converted +to string values. -If the value is a **System.IO.FileInfo** object, then the binary file contents will be submitted. -The name of the file will be submitted as the `filename`. The MIME will be set as -`application/octet-stream`. `Get-Item` can be used to simplify supplying the **System.IO.FileInfo** -object. +If the value is a **System.IO.FileInfo** object, then the binary file contents is submitted. The +name of the file is submitted as the `filename`. The MIME type is set as `application/octet-stream`. +`Get-Item` can be used to simplify supplying the **System.IO.FileInfo** object. ```powershell $Form = @{ @@ -668,9 +665,9 @@ $Form = @{ } ``` -If the value is a collection type, such as an Array or List, the for field will be submitted -multiple times. The values of the list will be treated as strings by default. If the value is a -**System.IO.FileInfo** object, then the binary file contents will be submitted. Nested collections +If the value is a collection type, such as an Array or List, the form field is submitted multiple +times. The values of the list are treated as strings by default. If the value is a +**System.IO.FileInfo** object, then the binary file contents are submitted. Nested collections aren't supported. ```powershell @@ -680,10 +677,9 @@ $Form = @{ } ``` -In the above example, the `tags` field will be supplied three times in the form, once for each of -`Vacation`, `Italy`, and `2017`. The `pictures` field will also be submitted once for each file in -the `2017-Italy` folder. The binary contents of the files in that folder will be submitted as the -values. +In the above example, the `tags` field is supplied three times in the form, once for each of the +values: `Vacation`, `Italy`, and `2017`. The `pictures` field is submitted once for each file in the +`2017-Italy` folder. The binary contents of the files in that folder are submitted as the values. This feature was added in PowerShell 6.1.0. @@ -848,10 +844,8 @@ Accept wildcard characters: False ### -NoProxy -Indicates that the cmdlet will not use a proxy to reach the destination. - -When you need to bypass the proxy configured in Internet Explorer, or a proxy specified in the -environment, use this switch. +Indicates that the cmdlet won't use a proxy to reach the destination. Use this to bypass the proxy +configured in your internet settings or specified in the environment. This parameter was introduced in PowerShell 6.0. @@ -1000,11 +994,11 @@ Accept wildcard characters: False ### -ProxyCredential -Specifies a user account that has permission to use the proxy server that is specified by the +Specifies a user account that has permission to use the proxy server that's specified by the **Proxy** parameter. The default is the current user. -Type a user name, such as **User01** or **Domain01\User01**, **User@Domain.Com**, or enter a -`PSCredential` object, such as one generated by the `Get-Credential` cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such +as one generated by the `Get-Credential` cmdlet. This parameter is valid only when the **Proxy** parameter is also used in the command. You can't use the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command. @@ -1023,8 +1017,8 @@ Accept wildcard characters: False ### -ProxyUseDefaultCredentials -Indicates that the cmdlet uses the credentials of the current user to access the proxy server that -is specified by the **Proxy** parameter. +Uses the credentials of the current user to access the proxy server that is specified by the +**Proxy** parameter. This parameter is valid only when the **Proxy** parameter is also used in the command. You can't use the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command. @@ -1069,22 +1063,22 @@ requires the **OutFile** parameter. **Resume** only operates on the size of the local file and remote file and performs no other validation that the local file and the remote file are the same. -If the local file size is smaller than the remote file size, then the cmdlet will attempt to resume +If the local file size is smaller than the remote file size, then the cmdlet attempts to resume downloading the file and append the remaining bytes to the end of the file. If the local file size is the same as the remote file size, then no action is taken and the cmdlet assumes the download already completed. -If the local file size is larger than the remote file size, then the local file will be overwritten -and the entire remote file will be completely re-downloaded. This behavior is the same as using -**OutFile** without **Resume**. +If the local file size is larger than the remote file size, then the local file is overwritten and +the entire remote file is re-downloaded. This behavior is the same as using **OutFile** without +**Resume**. -If the remote server does not support download resuming, then the local file will be overwritten and -the entire remote file will be completely re-downloaded. This behavior is the same as using -**OutFile** without **Resume**. +If the remote server doesn't support download resuming, then the local file is overwritten and the +entire remote file is re-downloaded. This behavior is the same as using **OutFile** without +**Resume**. -If the local file doesn't exist, then the local file will be created and the entire remote file will -be completely downloaded. This behavior is the same as using **OutFile** without **Resume**. +If the local file doesn't exist, then the local file is created and the entire remote file is +downloaded. This behavior is the same as using **OutFile** without **Resume**. This feature was added in PowerShell 6.1.0. @@ -1166,7 +1160,7 @@ Skips certificate validation checks that include all validations such as expirat trusted root authority, etc. > [!WARNING] -> Using this parameter is not secure and is not recommended. This switch is only intended to be used +> Using this parameter isn't secure and isn't recommended. This switch is only intended to be used > against known hosts using a self-signed certificate for testing purposes. Use at your own risk. This feature was added in PowerShell 6.0.0. @@ -1187,11 +1181,11 @@ Accept wildcard characters: False Indicates the cmdlet should add headers to the request without validation. -This switch should be used for sites that require header values that do not conform to standards. +This switch should be used for sites that require header values that don't conform to standards. Specifying this switch disables validation to allow the value to be passed unchecked. When specified, all headers are added without validation. -This will disable validation for values passed to the **ContentType**, **Headers**, and +This switch disables validation for values passed to the **ContentType**, **Headers**, and **UserAgent** parameters. This feature was added in PowerShell 6.0.0. @@ -1235,17 +1229,11 @@ protocols for compliance purposes. These values are defined as a flag-based enumeration. You can combine multiple values together to set multiple flags using this parameter. The values can be passed to the **SslProtocol** parameter -as an array of values or as a comma-separated string of those values. The cmdlet will combine the -values using a binary-OR operation. Passing values as an array is the simplest option and also -allows you to use tab-completion on the values. You may not be able to supply multiple values on all -platforms. - -> [!NOTE] -> On non-Windows platforms it may not be possible to supply `Tls` or `Tls12` as an option. Support -> for `Tls13` is not available on all operating systems and will need to be verified on a per -> operating system basis. +as an array of values or as a comma-separated string of those values. The cmdlet combines the values +using a binary-OR operation. Passing values as an array is the simplest option and also allows you +to use tab-completion on the values. You may not be able to supply multiple values on all platforms. -This feature was added in PowerShell 6.0.0 and support for `Tls13` was added in PowerShell 7.1. +This feature was added in PowerShell 6.0.0. Support for `Tls13` was added in PowerShell 7.1. ```yaml Type: Microsoft.PowerShell.Commands.WebSslProtocol @@ -1377,8 +1365,8 @@ Accept wildcard characters: False ### -UseBasicParsing This parameter has been deprecated. Beginning with PowerShell 6.0.0, all Web requests use basic -parsing only. This parameter is included for backwards compatibility only and any use of it will -have no effect on the operation of the cmdlet. +parsing only. This parameter is included for backwards compatibility only. When used, it has no +effect on the operation of the cmdlet. ```yaml Type: System.Management.Automation.SwitchParameter @@ -1417,9 +1405,9 @@ The default user agent is similar to `Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0` with slight variations for each operating system and platform. -To test a website with the standard user agent string that is used by most internet browsers, use -the properties of the [PSUserAgent](/dotnet/api/microsoft.powershell.commands.psuseragent) class, -such as Chrome, Firefox, InternetExplorer, Opera, and Safari. +To test a website with the standard user agent string that's used by most internet browsers, use +the properties of the [PSUserAgent](xref:Microsoft.PowerShell.Commands.PSUserAgent) class, such as +Chrome, Firefox, InternetExplorer, Opera, and Safari. ```yaml Type: System.String @@ -1439,8 +1427,8 @@ Specifies a web request session. Enter the variable name, including the dollar s To override a value in the web request session, use a cmdlet parameter, such as **UserAgent** or **Credential**. Parameter values take precedence over values in the web request session. Content -related headers, such as `Content-Type`, will be also be overridden when a -**MultipartFormDataContent** object is supplied for **Body**. +related headers, such as `Content-Type`, are overridden when a **MultipartFormDataContent** object +is supplied for **Body**. Unlike a remote session, the web request session isn't a persistent connection. It's an object that contains information about the connection and the request, including cookies, credentials, the @@ -1507,16 +1495,16 @@ PowerShell includes the following aliases for `Invoke-RestMethod`: Some features may not be available on all platforms. Because of changes in .NET Core 3.1, PowerShell 7.0 and higher use the -[HttpClient.DefaultProxy](xref:System.Net.Http.HttpClient.DefaultProxy*) -property to determine the proxy configuration. +[HttpClient.DefaultProxy](xref:System.Net.Http.HttpClient.DefaultProxy*) property to determine the +proxy configuration. -The value of this property is different rules depending on your platform: +The value of this property differ depending on your platform: -- **For Windows**: Reads proxy configuration from environment variables or, if those are not - defined, from the user's proxy settings. -- **For macOS**: Reads proxy configuration from environment variables or, if those are not defined, +- **For Windows**: Reads proxy configuration from environment variables or, if those aren't defined, + from the user's proxy settings. +- **For macOS**: Reads proxy configuration from environment variables or, if those aren't defined, from the system's proxy settings. -- **For Linux**: Reads proxy configuration from environment variables or, in case those are not +- **For Linux**: Reads proxy configuration from environment variables or, in case those aren't defined, this property initializes a non-configured instance that bypasses all addresses. The environment variables used for `DefaultProxy` initialization on Windows and Unix-based platforms @@ -1525,7 +1513,7 @@ are: - `HTTP_PROXY`: the hostname or IP address of the proxy server used on HTTP requests. - `HTTPS_PROXY`: the hostname or IP address of the proxy server used on HTTPS requests. - `ALL_PROXY`: the hostname or IP address of the proxy server used on HTTP and HTTPS requests in - case `HTTP_PROXY` or `HTTPS_PROXY` are not defined. + case `HTTP_PROXY` or `HTTPS_PROXY` aren't defined. - `NO_PROXY`: a comma-separated list of hostnames that should be excluded from proxying. PowerShell 7.4 added support for the Brotli compression algorithm. diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 3898c2d60aed..35787092707c 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -1,7 +1,7 @@ --- description: Describes regular expressions in PowerShell. Locale: en-US -ms.date: 06/14/2024 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_regular_expressions?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Regular_Expressions @@ -17,19 +17,20 @@ Describes regular expressions in PowerShell. > [!NOTE] > This article shows the syntax and methods for using regular expressions in > PowerShell. It doesn't cover all possible expressions. For a more complete -> reference, see the [Regular Expression Language - Quick Reference][03]. +> reference, see the [Regular Expression Language - Quick Reference][02]. A regular expression is a pattern used to match text. It can be made up of -literal characters, operators, and other constructs. +literal characters, operators, and other constructs. PowerShell uses the +[.NET regex][03] engine. This article demonstrates regular expression syntax in PowerShell. PowerShell has several operators and cmdlets that use regular expressions. You can read more about their syntax and usage at the links below. -- [Select-String][10] -- [-match and -replace operators][06] -- [-split operator][08] -- [switch statement with -regex option][09] +- [Select-String][11] +- [-match and -replace operators][07] +- [-split operator][09] +- [switch statement with -regex option][10] PowerShell regular expressions are case-insensitive by default. Each method shown above has a different way to force case sensitivity. @@ -81,8 +82,8 @@ characters). ### Numbers -The `\d` character class will match any decimal digit. Conversely, `\D` will -match any character except decimal digits. +The `\d` character class matchs any decimal digit. Conversely, `\D` matches any +character except decimal digits. ```powershell # This expression returns true if it matches a server name. @@ -92,7 +93,7 @@ match any character except decimal digits. ### Word characters -The `\w` character class will match any word character `[a-zA-Z_0-9]`. To match +The `\w` character class matches any word character `[a-zA-Z_0-9]`. To match any non-word character, use `\W`. ```powershell @@ -103,8 +104,8 @@ any non-word character, use `\W`. ### Wildcards -The period (`.`) is a wildcard character in regular expressions. It will match -any character except a newline (`\n`). +The period (`.`) is a wildcard character in regular expressions. It matches any +character except a newline (`\n`). ```powershell # This expression returns true. @@ -155,7 +156,7 @@ The plus sign (`+`) matches the previous element one or more times. ``` The question mark `?` matches the previous element zero or one time. Like -asterisk `*`, it will even match strings where the element is absent. +asterisk `*`, it even matches strings where the element is absent. ```powershell # This returns true for any server name, even server names without dashes. @@ -208,7 +209,7 @@ When using anchors in PowerShell, you should understand the difference between instead of matching every character EXCEPT the newline `\n`. To read more about these options and how to use them, visit the -[Regular Expression Language - Quick Reference][03]. +[Regular Expression Language - Quick Reference][02]. ## Escaping characters @@ -372,10 +373,10 @@ Name Value ---- ----- D CONTOSO N jsmith -0 A process has exited.... +0 A process has exited... ``` -For more information, see [Grouping Constructs in Regular Expressions][02]. +For more information, see [Grouping Constructs in Regular Expressions][01]. ### Substitutions in Regular Expressions @@ -461,18 +462,32 @@ Gobble Gobble For detailed information on substitution expressions, see [Substitutions in Regular Expressions][04]. +## Comments in regular expressions + +Regular expressions can be very complex and difficult to read. You can use +comments to make them more understandable. There are two types of comments +allowed in regular expressions. + +- Inline comment (`(?#)`) +- End-of-line comment (`#`) + +For more information, see the _Regular expression comments_ section of +[about_Comments][05]. + ## See also -- [about_Operators][07] -- [about_Comparison_Operators][05] +- [about_Operators][08] +- [about_Comparison_Operators][06] -[02]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions -[03]: /dotnet/standard/base-types/regular-expression-language-quick-reference +[01]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions +[02]: /dotnet/standard/base-types/regular-expression-language-quick-reference +[03]: /dotnet/standard/base-types/regular-expressions [04]: /dotnet/standard/base-types/substitutions-in-regular-expressions -[05]: about_Comparison_Operators.md -[06]: about_Comparison_Operators.md#matching-operators -[07]: about_Operators.md -[08]: about_Split.md -[09]: about_Switch.md -[10]: xref:Microsoft.PowerShell.Utility.Select-String +[05]: about_Comments.md#regular-expression-comments +[06]: about_Comparison_Operators.md +[07]: about_Comparison_Operators.md#matching-operators +[08]: about_Operators.md +[09]: about_Split.md +[10]: about_Switch.md +[11]: xref:Microsoft.PowerShell.Utility.Select-String diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Signing.md index b2c6e2752341..87713414bc19 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Signing.md @@ -1,7 +1,7 @@ --- description: Explains how to sign scripts so that they comply with the PowerShell execution policies. Locale: en-US -ms.date: 01/07/2025 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Signing @@ -17,7 +17,7 @@ policies. > This information only applies to PowerShell running on Windows. -The Restricted execution policy doesn't permit any scripts to run. The +The **Restricted** execution policy doesn't permit any scripts to run. The **AllSigned** and **RemoteSigned** execution policies prevent PowerShell from running scripts that don't have a digital signature. @@ -143,10 +143,8 @@ certificate. Two types of certificates are suitable for signing a script file: not run on other computers. Self-signed certificate should only be used to sign scripts for testing -purposes. - -It isn't appropriate for scripts that will be shared, even within an -enterprise. +purposes. Self-signed certificates aren't appropriate for scripts that you want +to share. If you create a self-signed certificate, be sure to enable strong private key protection on your certificate. This prevents malicious programs from signing @@ -222,7 +220,7 @@ Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My Thumbprint Subject ---------- ------- -4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ] +4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ``` ## Sign a script @@ -267,6 +265,10 @@ $cert = Get-ChildItem Cert:\CurrentUser\My -CodeSigningCert | Set-AuthenticodeSignature add-signature.ps1 $cert ``` +The `Set-AuthenticodeSignature` cmdlet adds the signature to the script file as +a comment block at the end of the file. The comment block begins and ends with +`# SIG #`. + After you sign the script, you can run it on the local computer. However, the script won't run on computers where the PowerShell execution policy requires a digital signature from a trusted authority. If you try, PowerShell displays the diff --git a/reference/7.5/Microsoft.PowerShell.Core/Add-History.md b/reference/7.5/Microsoft.PowerShell.Core/Add-History.md index cfc81afadb0f..cd03d669d993 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Add-History.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Add-History.md @@ -31,7 +31,8 @@ about the session history, see [about_History](About/about_History.md). The session history is managed separately from the history maintained by the **PSReadLine** module. Both histories are available in sessions where **PSReadLine** is loaded. This cmdlet only works with -the session history. For more information see, [about_PSReadLine](../PSReadLine/About/about_PSReadLine.md). +the session history. For more information see, +[about_PSReadLine](../PSReadLine/About/about_PSReadLine.md). You can use the `Get-History` cmdlet to get the commands and pass them to `Add-History`, or you can export the commands to a CSV or XML file, then import the commands, and pass the imported file to @@ -122,9 +123,9 @@ PowerShell. The `Add-History` cmdlet then adds the commands in the file to the s ### -InputObject -Specifies an array of entries to add to the history as **HistoryInfo** object to the session history. -You can use this parameter to submit a **HistoryInfo** object, such as the ones that are returned by -the `Get-History`, `Import-Clixml`, or `Import-Csv` cmdlets, to `Add-History`. +Specifies an array of entries to add to the history as **HistoryInfo** object to the session +history. You can use this parameter to submit a **HistoryInfo** object, such as the ones that are +returned by the `Get-History`, `Import-Clixml`, or `Import-Csv` cmdlets, to `Add-History`. ```yaml Type: System.Management.Automation.PSObject[] diff --git a/reference/7.5/Microsoft.PowerShell.Core/Clear-History.md b/reference/7.5/Microsoft.PowerShell.Core/Clear-History.md index 9d73bd9b7254..6f4a803b35b0 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Clear-History.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Clear-History.md @@ -256,7 +256,8 @@ wildcards to match commands in the PowerShell session history displayed by `Get- enter more than one string, `Clear-History` deletes commands that match any of the strings. The **CommandLine** parameter can be used with **Count**. -For strings with a space, use single quotations. For more information, see [about_Quoting_Rules](About/about_Quoting_Rules.md). +For strings with a space, use single quotations. For more information, see +[about_Quoting_Rules](About/about_Quoting_Rules.md). ```yaml Type: System.String[] @@ -400,7 +401,8 @@ information, see [about_History](About/about_History.md). The session history is managed separately from the history maintained by the **PSReadLine** module. Both histories are available in sessions where **PSReadLine** is loaded. This cmdlet only works with -the session history. For more information see, [about_PSReadLine](../PSReadLine/About/about_PSReadLine.md). +the session history. For more information see, +[about_PSReadLine](../PSReadLine/About/about_PSReadLine.md). ## RELATED LINKS diff --git a/reference/7.5/Microsoft.PowerShell.Core/Disable-ExperimentalFeature.md b/reference/7.5/Microsoft.PowerShell.Core/Disable-ExperimentalFeature.md index e005e29c364d..6ce9274d074d 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Disable-ExperimentalFeature.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Disable-ExperimentalFeature.md @@ -32,9 +32,9 @@ This cmdlet was introduced in PowerShell 6.2. ### Example 1: Disable an experimental feature -In this example, if this experimental feature was previously enabled, then the `powershell.config.json` -file is updated for the user to not enable that feature once PowerShell is restarted. -Upon success nothing is output to the pipeline and only a warning message is displayed. +In this example, if this experimental feature was previously enabled, then the +`powershell.config.json` file is updated for the user to not enable that feature once PowerShell is +restarted. Upon success nothing is output to the pipeline and only a warning message is displayed. ```powershell Disable-ExperimentalFeature -Name PSImplicitRemotingBatching @@ -142,6 +142,6 @@ Changes to state of an experimental feature only take effect on restart of Power [Get-ExperimentalFeature](Get-ExperimentalFeature.md) -[about_Experimental_Features](/powershell/module/microsoft.powershell.core/about/about_experimental_features) +[about_Experimental_Features](About/about_Experimental_Features.md) [Using Experimental Features](/powershell/scripting/learn/experimental-features) diff --git a/reference/7.5/Microsoft.PowerShell.Core/Disable-PSRemoting.md b/reference/7.5/Microsoft.PowerShell.Core/Disable-PSRemoting.md index 5f88d0a1e869..084c436d9bd0 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Disable-PSRemoting.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Disable-PSRemoting.md @@ -57,7 +57,8 @@ option. ### Example 1: Prevent remote access to all PowerShell session configurations -This example prevents remote access to all PowerShell session endpoint configurations on the computer. +This example prevents remote access to all PowerShell session endpoint configurations on the +computer. ```powershell Disable-PSRemoting @@ -537,9 +538,9 @@ This cmdlet is only available on Windows platforms. following changes manually. 1. Stop and disable the WinRM service. - 2. Delete the listener that accepts requests on any IP address. - 3. Disable the firewall exceptions for WS-Management communications. - 4. Restore the value of the LocalAccountTokenFilterPolicy to 0, which restricts remote access to + 1. Delete the listener that accepts requests on any IP address. + 1. Disable the firewall exceptions for WS-Management communications. + 1. Restore the value of the LocalAccountTokenFilterPolicy to 0, which restricts remote access to members of the Administrators group on the computer. - A session endpoint configuration is a group of settings that define the environment for a session. diff --git a/reference/7.5/Microsoft.PowerShell.Core/Disconnect-PSSession.md b/reference/7.5/Microsoft.PowerShell.Core/Disconnect-PSSession.md index c84df485da70..276299d9da27 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Disconnect-PSSession.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Disconnect-PSSession.md @@ -193,7 +193,7 @@ and in the session configuration on the remote computer. Values set for the sess over values set in the session configuration, but session values cannot exceed quotas set in the session configuration, such as the **MaxIdleTimeoutMs** value. -``` +```powershell PS> $Timeout = New-PSSessionOption -IdleTimeout 172800000 PS> $s = New-PSSession -Computer Server01 -Name ITTask -SessionOption $Timeout PS> Disconnect-PSSession -Session $s diff --git a/reference/7.5/Microsoft.PowerShell.Core/Enable-ExperimentalFeature.md b/reference/7.5/Microsoft.PowerShell.Core/Enable-ExperimentalFeature.md index cd78fa42c6c5..b11255ece794 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Enable-ExperimentalFeature.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Enable-ExperimentalFeature.md @@ -32,9 +32,9 @@ This cmdlet was introduced in PowerShell 6.2. ### Example 1: Enable an experimental feature -In this example, if this experimental feature was previously disabled, then the `powershell.config.json` -file is updated for the user to enable that feature once PowerShell is restarted. -Upon success nothing is output to the pipeline and only a warning message is displayed. +In this example, if this experimental feature was previously disabled, then the +`powershell.config.json` file is updated for the user to enable that feature once PowerShell is +restarted. Upon success nothing is output to the pipeline and only a warning message is displayed. ```powershell Enable-ExperimentalFeature PSImplicitRemotingBatching @@ -117,7 +117,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -141,6 +142,6 @@ Changes to state of an experimental feature only take effect on restart of Power [Get-ExperimentalFeature](Get-ExperimentalFeature.md) -[about_Experimental_Features](/powershell/module/microsoft.powershell.core/about/about_experimental_features) +[about_Experimental_Features](About/about_Experimental_Features.md) [Using Experimental Features](/powershell/scripting/learn/experimental-features) diff --git a/reference/7.5/Microsoft.PowerShell.Core/Enable-PSRemoting.md b/reference/7.5/Microsoft.PowerShell.Core/Enable-PSRemoting.md index 7884a028c0e4..635fb4c05fd1 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Enable-PSRemoting.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Enable-PSRemoting.md @@ -83,8 +83,8 @@ option. This cmdlet is not available on Linux or macOS versions of PowerShell. For more information about using PowerShell remoting, see the following articles: -- [about_Remote_Requirements](about/about_Remote_Requirements.md) -- [about_Remote](about/about_Remote.md) +- [about_Remote_Requirements](About/about_Remote_Requirements.md) +- [about_Remote](About/about_Remote.md) ## EXAMPLES diff --git a/reference/7.5/Microsoft.PowerShell.Core/Enable-PSSessionConfiguration.md b/reference/7.5/Microsoft.PowerShell.Core/Enable-PSSessionConfiguration.md index 76c9c1e28c7c..f70d9b96df07 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Enable-PSSessionConfiguration.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Enable-PSSessionConfiguration.md @@ -229,7 +229,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/7.5/Microsoft.PowerShell.Core/Export-ModuleMember.md b/reference/7.5/Microsoft.PowerShell.Core/Export-ModuleMember.md index 8912e8b19f56..160ebdd1fb2f 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Export-ModuleMember.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Export-ModuleMember.md @@ -201,7 +201,8 @@ Accept wildcard characters: True This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-Command.md b/reference/7.5/Microsoft.PowerShell.Core/Get-Command.md index ef90f3bbe25d..2960c9a23fc7 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-Command.md @@ -764,12 +764,12 @@ PowerShell includes the following aliases for `Get-Command`: - When more than one command that has the same name is available to the session, `Get-Command` returns the command that runs when you type the command name. To get commands that have the same name, listed in run order, use the **All** parameter. For more information, see - [about_Command_Precedence](../Microsoft.PowerShell.Core/About/about_Command_Precedence.md). + [about_Command_Precedence](About/about_Command_Precedence.md). - When a module is imported automatically, the effect is the same as using the `Import-Module` cmdlet. The module can add commands, types and formatting files, and run scripts in the session. To enable, disable, and configuration automatic importing of modules, use the `$PSModuleAutoLoadingPreference` preference variable. For more information, see - [about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). + [about_Preference_Variables](About/about_Preference_Variables.md). ## RELATED LINKS diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-ExperimentalFeature.md b/reference/7.5/Microsoft.PowerShell.Core/Get-ExperimentalFeature.md index 5cf0647f3d73..596e02122a0a 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-ExperimentalFeature.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-ExperimentalFeature.md @@ -63,7 +63,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -84,6 +85,6 @@ name is specified. [Enable-ExperimentalFeature](Enable-ExperimentalFeature.md) -[about_Experimental_Features](/powershell/module/microsoft.powershell.core/about/about_experimental_features) +[about_Experimental_Features](About/about_Experimental_Features.md) [Using Experimental Features](/powershell/scripting/learn/experimental-features) diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-Help.md b/reference/7.5/Microsoft.PowerShell.Core/Get-Help.md index 8713409b8c31..7db0e48f5321 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-Help.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-Help.md @@ -100,8 +100,8 @@ fallback locale, it looks for help articles in English, **en-US**, before it ret message or displaying autogenerated help. For information about the symbols that `Get-Help` displays in the command syntax diagram, see -[about_Command_Syntax](./About/about_Command_Syntax.md). For information about parameter attributes, -such as **Required** and **Position**, see [about_Parameters](./About/about_Parameters.md). +[about_Command_Syntax](About/about_Command_Syntax.md). For information about parameter attributes, +such as **Required** and **Position**, see [about_Parameters](About/about_Parameters.md). > [!NOTE] > In PowerShell 3.0 and PowerShell 4.0, `Get-Help` can't find **About** articles in modules unless @@ -118,10 +118,10 @@ immediately to the left of a parameter, the function jumps to that parameter's d full help topic. When you hit Q to exit the help view, you are returned to the command line at the same cursor position so you can continue typing the command. -When you use the key combination Alt+h, the **PSReadLine** `ShowParameterHelp` function -displays help information for the parameter immediately to the left of the cursor. The help text is -displayed below the command line. This allows you to see the description of the parameter and -continue typing your command. +When you use the key combination Alt+h, the **PSReadLine** `ShowParameterHelp` +function displays help information for the parameter immediately to the left of the cursor. The help +text is displayed below the command line. This allows you to see the description of the parameter +and continue typing your command. For more information, see [Using dynamic help](/powershell/scripting/learn/shell/dynamic-help). @@ -329,7 +329,7 @@ SYNOPSIS ### Example 12: Display help for a script This example gets help for the `MyScript.ps1 script`. For information about how to write help for -your functions and scripts, see [about_Comment_Based_Help](./About/about_Comment_Based_Help.md). +your functions and scripts, see [about_Comment_Based_Help](About/about_Comment_Based_Help.md). ```powershell Get-Help -Name C:\PS-Test\MyScript.ps1 @@ -505,7 +505,7 @@ for cmdlet, function, workflow, and script help articles. You can't use the **On with `Get-Help` in a remote session. For information about supporting this feature in help articles that you write, see -[about_Comment_Based_Help](./About/about_Comment_Based_Help.md), and +[about_Comment_Based_Help](About/about_Comment_Based_Help.md), and [Supporting Online Help](/powershell/scripting/developer/module/supporting-online-help), and [Writing Help for PowerShell Cmdlets](/powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets). @@ -554,7 +554,7 @@ To see the custom cmdlet help for a provider path, go to the provider path locat the provider path. You can also find custom cmdlet help online in the provider help section of the help articles. -For more information about PowerShell providers, see [about_Providers](./About/about_Providers.md). +For more information about PowerShell providers, see [about_Providers](About/about_Providers.md). > [!NOTE] > The provider for the path specified must have a PowerShell provider help file installed. If no @@ -691,7 +691,7 @@ following fields: [about_Command_Syntax](About/about_Command_Syntax.md) -[about_Comment_Based_Help](./About/about_Comment_Based_Help.md) +[about_Comment_Based_Help](About/about_Comment_Based_Help.md) [Get-Command](Get-Command.md) diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-History.md b/reference/7.5/Microsoft.PowerShell.Core/Get-History.md index fe27434dafce..111252c8357a 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-History.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-History.md @@ -31,7 +31,8 @@ features in PowerShell, see [about_History](About/about_History.md). The session history is managed separately from the history maintained by the **PSReadLine** module. Both histories are available in sessions where **PSReadLine** is loaded. This cmdlet only works with -the session history. For more information see, [about_PSReadLine](../PSReadLine/About/about_PSReadLine.md). +the session history. For more information, see +[about_PSReadLine](../PSReadLine/About/about_PSReadLine.md). ## EXAMPLES @@ -163,7 +164,8 @@ command history, see [about_History](About/about_History.md). Starting in Windows PowerShell 3.0, the default value of the `$MaximumHistoryCount` preference variable is `4096`. In Windows PowerShell 2.0, the default value is `64`. For more information about -the `$MaximumHistoryCount` variable, see [about_Preference_Variables](About/about_Preference_Variables.md). +the `$MaximumHistoryCount` variable, see +[about_Preference_Variables](About/about_Preference_Variables.md). ## RELATED LINKS diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-Job.md b/reference/7.5/Microsoft.PowerShell.Core/Get-Job.md index c63643ad276a..95611ed499e4 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-Job.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-Job.md @@ -70,7 +70,7 @@ contain the job results. To get the results, use the `Receive-Job` cmdlet. A Windows PowerShell background job is a command that runs in the background without interacting with the current session. Typically, you use a background job to run a complex command that takes a long time to finish. For more information about background jobs in Windows PowerShell, see -[about_Jobs](./about/about_Jobs.md). +[about_Jobs](About/about_Jobs.md). Beginning in Windows PowerShell 3.0, the `Get-Job` cmdlet also gets custom job types, such as workflow jobs and instances of scheduled jobs. To find the job type of a job, use the @@ -146,7 +146,8 @@ Id Name PSJobTypeName State HasMoreData Location ### Example 4: Get jobs that include a specific command by using the pipeline Like the command in the previous example, this command gets the jobs on the system that include a -`Get-Process` command. The command uses a pipeline operator (`|`) to send a PSCustomObject with the NoteProperty **Command**, to the `Get-Job` cmdlet. It is the equivalent of the previous command. +`Get-Process` command. The command uses a pipeline operator (`|`) to send a PSCustomObject with the +NoteProperty **Command**, to the `Get-Job` cmdlet. It is the equivalent of the previous command. ```powershell [pscustomobject]@{Command='*Get-Process*'} | Get-Job @@ -244,7 +245,7 @@ parameter. It then gets the job using the `Get-Job` command on the S2 computer u The sample output shows the results of the `Get-Job` command. On the S2 computer, the job appears to be a local job. The computer name is localhost and the job type is a background job. For more information about how to run background jobs on remote computers, see -[about_Remote_Jobs](./about/about_Remote_Jobs.md). +[about_Remote_Jobs](About/about_Remote_Jobs.md). ```powershell Start-Job -ScriptBlock {Get-EventLog -LogName System} @@ -298,8 +299,8 @@ error. In this case, the user forgot to use the Run as administrator option when PowerShell.Because background jobs use the remoting features of Windows PowerShell, the computer must be configured for remoting to run a job, even when the job runs on the local computer.For information about requirements for remoting in Windows PowerShell, see -[about_Remote_Requirements](./about/about_Remote_Requirements.md). For troubleshooting tips, see -[about_Remote_Troubleshooting](./about/about_Remote_Troubleshooting.md). +[about_Remote_Requirements](About/about_Remote_Requirements.md). For troubleshooting tips, see +[about_Remote_Troubleshooting](About/about_Remote_Troubleshooting.md). ```powershell PS> Start-Job -ScriptBlock {Get-Process} @@ -415,7 +416,7 @@ Access is denied. ``` For more information, see the -[about_Remote_Troubleshooting](./about/about_Remote_Troubleshooting.md) Help topic. +[about_Remote_Troubleshooting](About/about_Remote_Troubleshooting.md) Help topic. ## PARAMETERS diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-Module.md b/reference/7.5/Microsoft.PowerShell.Core/Get-Module.md index 329effea5a19..f1589cab4314 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-Module.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-Module.md @@ -122,7 +122,7 @@ This command gets all of the exported files for all available modules. ```powershell $FullyQualifiedName = @{ModuleName="Microsoft.PowerShell.Management";ModuleVersion="3.1.0.0"} -Get-Module -FullyQualifiedName $FullyQualifiedName | Format-Table -Property Name,Version +Get-Module -FullyQualifiedName $FullyQualifiedName | Format-Table -Property Name, Version ``` ```Output @@ -249,7 +249,7 @@ information about a module, its requirements, and its contents. ```powershell # First command -$m = Get-Module -list -Name BitsTransfer +$m = Get-Module -List -Name BitsTransfer # Second command Get-Content $m.Path diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md b/reference/7.5/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md index 21a1c3f74bde..79b85b4ca818 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md @@ -122,7 +122,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-PSSession.md b/reference/7.5/Microsoft.PowerShell.Core/Get-PSSession.md index 22e987ce2db5..984e49be9999 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-PSSession.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-PSSession.md @@ -132,7 +132,7 @@ command runs when you use the **ComputerName** or **ConnectionUri** parameters. > in the current session. The **ComputerName** parameter gets sessions that were created in the > current session and connect to the specified computer. -For more information about PowerShell sessions, see [about_PSSessions](about/about_PSSessions.md). +For more information about PowerShell sessions, see [about_PSSessions](About/about_PSSessions.md). ## EXAMPLES @@ -684,8 +684,8 @@ values for this parameter are: `All`, `Opened`, `Disconnected`, `Closed`, and `B value is `All`. The session state value is relative to the current sessions. Sessions that were not created in the -current sessions and are not connected to the current session have a state of `Disconnected` even when -they are connected to a different session. +current sessions and are not connected to the current session have a state of `Disconnected` even +when they are connected to a different session. The state of a session is stored in the **State** property of the session. diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-PSSessionCapability.md b/reference/7.5/Microsoft.PowerShell.Core/Get-PSSessionCapability.md index e54550c3201d..8c52513832fb 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-PSSessionCapability.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-PSSessionCapability.md @@ -44,7 +44,8 @@ and Environmental Variables. Get-PSSessionCapability -ConfigurationName Endpoint1 -Username 'CONTOSO\User' ``` -This example returns the commands available to the user CONTOSO\User when connecting to the Endpoint1 constrained endpoint on the local computer. +This example returns the commands available to the user `CONTOSO\User` when connecting to the +Endpoint1 constrained endpoint on the local computer. ### Example 2: Get details about a runspace for a user @@ -52,7 +53,8 @@ This example returns the commands available to the user CONTOSO\User when connec Get-PSSessionCapability -ConfigurationName Endpoint1 -Username 'CONTOSO\User' -Full ``` -This example returns details about the runspace the user CONTOSO\User would interact with when connecting to the Endpoint1 constrained endpoint. +This example returns details about the runspace the user `CONTOSO\User` would interact with when +connecting to the Endpoint1 constrained endpoint. ## PARAMETERS @@ -109,7 +111,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md b/reference/7.5/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md index 55a418408a10..81a878c5b8b1 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md @@ -34,7 +34,8 @@ object that `Get-PSSessionConfiguration` returns. These properties make it easie session configuration authors to examine and compare session configurations. To create and register a session configuration, use the `Register-PSSessionConfiguration` cmdlet. -For more information about session configurations, see [about_Session_Configurations](About/about_Session_Configurations.md). +For more information about session configurations, see +[about_Session_Configurations](About/about_Session_Configurations.md). ## EXAMPLES @@ -120,7 +121,8 @@ session type, language mode, and execution policy of sessions that are created w configuration, session quotas, and the full path to the session configuration file. This view of a session configuration is used for sessions that include a session configuration file. -For more information about session configuration files, see [about_Session_Configuration_Files](About/about_Session_Configuration_Files.md). +For more information about session configuration files, see +[about_Session_Configuration_Files](About/about_Session_Configuration_Files.md). ### Example 4 - Another way to look at the session configurations @@ -277,7 +279,7 @@ Accept wildcard characters: True This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](./About/about_CommonParameters.md). +[about_CommonParameters](About/about_CommonParameters.md). ## INPUTS diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-PSSubsystem.md b/reference/7.5/Microsoft.PowerShell.Core/Get-PSSubsystem.md index 34489ac384ae..ce5fecdc67e4 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-PSSubsystem.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-PSSubsystem.md @@ -138,7 +138,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[about_experimental_features](about/about_experimental_features.md) +[about_experimental_features](About/about_Experimental_Features.md) [Disable-ExperimentalFeature](Disable-ExperimentalFeature.md) diff --git a/reference/7.5/Microsoft.PowerShell.Core/Import-Module.md b/reference/7.5/Microsoft.PowerShell.Core/Import-Module.md index 9d87b4cd7c4b..654bd50e47de 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Import-Module.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Import-Module.md @@ -411,7 +411,7 @@ module runs, instead of the `Get-Date` cmdlet. To run the original version of `G qualify the command name with the module name. For more information about command precedence in PowerShell, see -[about_Command_Precedence](about/about_Command_Precedence.md). +[about_Command_Precedence](About/about_Command_Precedence.md). ### Example 10: Import a minimum version of a module @@ -440,7 +440,7 @@ PowerShellGet 2.1.3 PowerShellGet 2.1.2 PowerShellGet 1.0.0.1 -PS> Import-Module -FullyQualifiedName @{ModuleName = 'PowerShellGet'; ModuleVersion = '2.1.3' } +PS> Import-Module -FullyQualifiedName @{ModuleName = 'PowerShellGet'; ModuleVersion = '2.1.3'} ``` ### Example 12: Import using a fully qualified path @@ -603,7 +603,7 @@ Specifies an array of arguments, or parameter values, that are passed to a scrip You can also refer to the **ArgumentList** parameter by its alias, **args**. For more information about the behavior of **ArgumentList**, see -[about_Splatting](about/about_Splatting.md#splatting-with-arrays). +[about_Splatting](About/about_Splatting.md#splatting-with-arrays). ```yaml Type: System.Object[] @@ -959,7 +959,7 @@ imported, and you might be missing important members of the module. > [!NOTE] > While it's possible to import a script (`.ps1`) file as a module, script files are usually not > structured like script modules file (`.psm1`) file. Importing a script file doesn't guarantee -> that it's usable as a module. For more information, see [about_Modules](about/about_Modules.md). +> that it's usable as a module. For more information, see [about_Modules](About/about_Modules.md). ```yaml Type: System.String[] @@ -981,8 +981,8 @@ default, `Import-Module` imports all exported module commands. Commands that have the same names can hide or replace commands in the session. To avoid command name conflicts in a session, use the **Prefix** or **NoClobber** parameters. For more information about name conflicts and command precedence, see "Modules and Name Conflicts" in -[about_Modules](about/about_Modules.md) and -[about_Command_Precedence](about/about_Command_Precedence.md). +[about_Modules](About/about_Modules.md) and +[about_Command_Precedence](About/about_Command_Precedence.md). This parameter was introduced in Windows PowerShell 3.0. @@ -1340,7 +1340,7 @@ PowerShell includes the following aliases for `Import-Module`: ## RELATED LINKS -[about_Modules](about/about_Modules.md) +[about_Modules](About/about_Modules.md) [Export-ModuleMember](Export-ModuleMember.md) diff --git a/reference/7.5/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/7.5/Microsoft.PowerShell.Core/Invoke-Command.md index 05695b0a304d..a959361e9117 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Invoke-Command.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Invoke-Command.md @@ -180,7 +180,7 @@ You can also use `Invoke-Command` on a local computer to a run script block as a runs the script block immediately in a child scope of the current scope. Before using `Invoke-Command` to run commands on a remote computer, read -[about_Remote](./About/about_Remote.md). +[about_Remote](About/about_Remote.md). Starting with PowerShell 6.0 you can use Secure Shell (SSH) to establish a connection to and invoke commands on remote computers. SSH must be installed on the local computer and the remote computer @@ -191,7 +191,7 @@ connection information. For more information about how to set up PowerShell SSH [PowerShell Remoting Over SSH](/powershell/scripting/learn/remoting/ssh-remoting-in-powershell-core). Some code samples use splatting to reduce the line length. For more information, see -[about_Splatting](./About/about_Splatting.md). +[about_Splatting](About/about_Splatting.md). ## EXAMPLES @@ -397,8 +397,8 @@ This example shows how to include the values of local variables in a command run computer. The command uses the `Using` scope modifier to identify a local variable in a remote command. By default, all variables are assumed to be defined in the remote session. The `Using` scope modifier was introduced in PowerShell 3.0. For more information about the `Using` scope -modifier, see [about_Remote_Variables](./About/about_Remote_Variables.md) and -[about_Scopes](./about/about_scopes.md). +modifier, see [about_Remote_Variables](About/about_Remote_Variables.md) and +[about_Scopes](About/about_scopes.md). ```powershell $Log = 'PowerShellCore/Operational' @@ -455,7 +455,7 @@ parameters in a script block. This example displays filenames that begin with th have the `.pdf` extension. For more information about the `Param` keyword, see -[about_Language_Keywords](./about/about_language_keywords.md#param). +[about_Language_Keywords](About/about_language_keywords.md#param). ```powershell $parameters = @{ @@ -488,7 +488,7 @@ files. The `Get-ChildItem` **Path** parameter is position 0 and the **Filter** p 1. For more information about the `$args` variable, see -[about_Automatic_Variables](./about/about_automatic_variables.md#args) +[about_Automatic_Variables](About/about_automatic_variables.md#args) ```powershell $parameters = @{ @@ -785,7 +785,7 @@ application name when you aren't using the **ConnectionURI** parameter in the co The default value is the value of the `$PSSessionApplicationName` preference variable on the local computer. If this preference variable isn't defined, the default value is WSMAN. This value is appropriate for most uses. For more information, see -[about_Preference_Variables](./About/about_Preference_Variables.md). +[about_Preference_Variables](About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the **URLPrefix** property of a listener on @@ -808,7 +808,7 @@ Accept wildcard characters: False Supplies the values of parameters for the scriptblock. The parameters in the script block are passed by position from the array value supplied to **ArgumentList**. This is known as array splatting. For more information about the behavior of **ArgumentList**, see -[about_Splatting](about/about_Splatting.md#splatting-with-arrays). +[about_Splatting](About/about_Splatting.md#splatting-with-arrays). ```yaml Type: System.Object[] @@ -966,7 +966,7 @@ configuration doesn't exist on the remote computer, the command fails. The default value is the value of the `$PSSessionConfigurationName` preference variable on the local computer. If this preference variable isn't set, the default is **Microsoft.PowerShell**. For more -information, see [about_Preference_Variables](about/about_Preference_Variables.md). +information, see [about_Preference_Variables](About/about_Preference_Variables.md). ```yaml Type: System.String @@ -1204,10 +1204,10 @@ provides sufficient time for you to connect before deleting the session. You can set the output buffering mode and idle time-out in the **SessionOption** parameter or in the `$PSSessionOption` preference variable. For more information about session options, see -`New-PSSessionOption` and [about_Preference_Variables](./about/about_preference_variables.md). +`New-PSSessionOption` and [about_Preference_Variables](About/about_preference_variables.md). For more information about the Disconnected Sessions feature, see -[about_Remote_Disconnected_Sessions](about/about_Remote_Disconnected_Sessions.md). +[about_Remote_Disconnected_Sessions](About/about_Remote_Disconnected_Sessions.md). This parameter was introduced in PowerShell 3.0. @@ -1251,7 +1251,7 @@ is an ordinal number. If you use the **JobName** parameter in a command, the command is run as a job, and `Invoke-Command` returns a job object, even if you don't include **AsJob** in the command. -For more information about PowerShell background jobs, see [about_Jobs](./About/about_Jobs.md). +For more information about PowerShell background jobs, see [about_Jobs](About/about_Jobs.md). ```yaml Type: System.String @@ -1426,7 +1426,7 @@ Specifies an array of sessions in which this cmdlet runs the command. Enter a va When you create a **PSSession**, PowerShell establishes a persistent connection to the remote computer. Use a **PSSession** to run a series of related commands that share data. To run a single command or a series of unrelated commands, use the **ComputerName** parameter. For more information, -see [about_PSSessions](./About/about_PSSessions.md). +see [about_PSSessions](About/about_PSSessions.md). ```yaml Type: System.Management.Automation.Runspaces.PSSession[] @@ -1780,17 +1780,17 @@ hashtable. For more information about `ssh_config` files, see ## RELATED LINKS -[about_PSSessions](./About/about_PSSessions.md) +[about_PSSessions](About/about_PSSessions.md) -[about_Remote](./About/about_Remote.md) +[about_Remote](About/about_Remote.md) -[about_Remote_Disconnected_Sessions](./About/about_Remote_Disconnected_Sessions.md) +[about_Remote_Disconnected_Sessions](About/about_Remote_Disconnected_Sessions.md) -[about_Remote_Troubleshooting](./About/about_remote_troubleshooting.md) +[about_Remote_Troubleshooting](About/about_Remote_Troubleshooting.md) -[about_Remote_Variables](./About/about_Remote_Variables.md) +[about_Remote_Variables](About/about_Remote_Variables.md) -[about_Scopes](./About/about_scopes.md) +[about_Scopes](About/about_Scopes.md) [Enter-PSSession](Enter-PSSession.md) diff --git a/reference/7.5/Microsoft.PowerShell.Core/Invoke-History.md b/reference/7.5/Microsoft.PowerShell.Core/Invoke-History.md index 856dca51ac0d..e627696a08f4 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Invoke-History.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Invoke-History.md @@ -27,7 +27,8 @@ the `Get-History` cmdlet. The session history is managed separately from the history maintained by the **PSReadLine** module. Both histories are available in sessions where **PSReadLine** is loaded. This cmdlet only works with -the session history. For more information see, [about_PSReadLine](../PSReadLine/About/about_PSReadLine.md). +the session history. For more information, see +[about_PSReadLine](../PSReadLine/About/about_PSReadLine.md). ## EXAMPLES diff --git a/reference/7.5/Microsoft.PowerShell.Core/Microsoft.PowerShell.Core.md b/reference/7.5/Microsoft.PowerShell.Core/Microsoft.PowerShell.Core.md index 47041fa8a6de..d8c079622bab 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Microsoft.PowerShell.Core.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Microsoft.PowerShell.Core.md @@ -257,7 +257,8 @@ Downloads and installs the newest help files on your computer. ### [Wait-Job](Wait-Job.md) -Suppresses the command prompt until one or all of the PowerShell background jobs running in the session are completed. +Suppresses the command prompt until one or all of the PowerShell background jobs running in the +session are completed. ### [Where-Object](Where-Object.md) diff --git a/reference/7.5/Microsoft.PowerShell.Core/New-Module.md b/reference/7.5/Microsoft.PowerShell.Core/New-Module.md index 81d5a5ddc852..224ac424cb08 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/New-Module.md +++ b/reference/7.5/Microsoft.PowerShell.Core/New-Module.md @@ -122,7 +122,7 @@ This example uses the `Export-ModuleMember` cmdlet to export a variable into the Without the `Export-ModuleMember` command, only the function is exported. ```powershell -New-Module -ScriptBlock {$SayHelloHelp="Type 'SayHello', a space, and a name."; function SayHello ($name) { "Hello, $name" }; Export-ModuleMember -function SayHello -Variable SayHelloHelp} +New-Module -ScriptBlock {$SayHelloHelp="Type 'SayHello', a space, and a name."; function SayHello ($name) { "Hello, $name" }; Export-ModuleMember -Function SayHello -Variable SayHelloHelp} $SayHelloHelp ``` @@ -151,7 +151,7 @@ return any objects by default, there is no output from this command. `Get-Module **GreetingModule** has been imported into the current session. ```powershell -New-Module -ScriptBlock {function Hello {"Hello!"}} -name GreetingModule | Import-Module +New-Module -ScriptBlock {function Hello {"Hello!"}} -Name GreetingModule | Import-Module Get-Module ``` @@ -255,7 +255,8 @@ Hello, World! ### -ArgumentList Specifies an array of arguments which are parameter values that are passed to the script block. For -more information about the behavior of **ArgumentList**, see [about_Splatting](about/about_Splatting.md#splatting-with-arrays). +more information about the behavior of **ArgumentList**, see +[about_Splatting](About/about_Splatting.md#splatting-with-arrays). ```yaml Type: System.Object[] diff --git a/reference/7.5/Microsoft.PowerShell.Core/New-ModuleManifest.md b/reference/7.5/Microsoft.PowerShell.Core/New-ModuleManifest.md index 36a0e62da043..6e9408a7b29b 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/New-ModuleManifest.md +++ b/reference/7.5/Microsoft.PowerShell.Core/New-ModuleManifest.md @@ -121,10 +121,12 @@ Copyright = '(c) ContosoAdmin. All rights reserved.' # Minimum version of the PowerShell host required by this module # PowerShellHostVersion = '' -# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only. +# Minimum version of Microsoft .NET Framework required by this module. This prerequisite +# is valid for the PowerShell Desktop edition only. # DotNetFrameworkVersion = '' -# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only. +# Minimum version of the common language runtime (CLR) required by this module. This +# prerequisite is valid for the PowerShell Desktop edition only. # CLRVersion = '' # Processor architecture (None, X86, Amd64) required by this module @@ -136,7 +138,8 @@ Copyright = '(c) ContosoAdmin. All rights reserved.' # Assemblies that must be loaded prior to importing this module # RequiredAssemblies = @() -# Script files (.ps1) that are run in the caller's environment prior to importing this module. +# Script files (.ps1) that are run in the caller's environment prior to importing this +# module. # ScriptsToProcess = @() # Type files (.ps1xml) to be loaded when importing this module @@ -148,16 +151,19 @@ Copyright = '(c) ContosoAdmin. All rights reserved.' # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess # NestedModules = @() -# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export. +# Functions to export from this module, for best performance, do not use wildcards and do +# not delete the entry, use an empty array if there are no functions to export. FunctionsToExport = @() -# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. +# Cmdlets to export from this module, for best performance, do not use wildcards and do +# not delete the entry, use an empty array if there are no cmdlets to export. CmdletsToExport = @() # Variables to export from this module VariablesToExport = '*' -# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export. +# Aliases to export from this module, for best performance, do not use wildcards and do +# not delete the entry, use an empty array if there are no aliases to export. AliasesToExport = @() # DSC resources to export from this module @@ -169,7 +175,8 @@ AliasesToExport = @() # List of all files packaged with this module # FileList = @() -# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. +# Private data to pass to the module specified in RootModule/ModuleToProcess. This may +also contain a PSData hashtable with additional module metadata used by PowerShell. PrivateData = @{ PSData = @{ @@ -205,7 +212,8 @@ PrivateData = @{ # HelpInfo URI of this module # HelpInfoURI = '' -# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. +# Default prefix for commands exported from this module. Override the default prefix +# using Import-Module -Prefix. # DefaultCommandPrefix = '' } @@ -265,8 +273,9 @@ $moduleSettings = @{ New-ModuleManifest @moduleSettings ``` -For information about Updatable Help, see [about_Updatable_Help](./About/about_Updatable_Help.md). -For information about the HelpInfo XML file, see [Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). +For information about Updatable Help, see [about_Updatable_Help](About/about_Updatable_Help.md). +For information about the HelpInfo XML file, see +[Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). ### Example 5 - Getting module information @@ -654,7 +663,7 @@ The HelpInfo XML file supports the Updatable Help feature that was introduced in contains information about the location of downloadable help files for the module and the version numbers of the newest help files for each supported locale. -For information about Updatable Help, see [about_Updatable_Help](./About/about_Updatable_Help.md). +For information about Updatable Help, see [about_Updatable_Help](About/about_Updatable_Help.md). For information about the HelpInfo XML file, see [Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). @@ -1238,4 +1247,4 @@ module and the caller's session state is the module's session state. [Test-ModuleManifest](Test-ModuleManifest.md) -[about_Modules](./About/about_Modules.md) +[about_Modules](About/about_Modules.md) diff --git a/reference/7.5/Microsoft.PowerShell.Core/New-PSSession.md b/reference/7.5/Microsoft.PowerShell.Core/New-PSSession.md index 514f71be2280..1b35c7a6c1d1 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/7.5/Microsoft.PowerShell.Core/New-PSSession.md @@ -89,7 +89,7 @@ remote computer. Use a **PSSession** to run multiple commands that share data, such as a function or the value of a variable. To run commands in a **PSSession**, use the `Invoke-Command` cmdlet. To use the **PSSession** to interact directly with a remote computer, use the `Enter-PSSession` cmdlet. For -more information, see [about_PSSessions](about/about_PSSessions.md). +more information, see [about_PSSessions](About/about_PSSessions.md). You can run commands on a remote computer without creating a **PSSession** with the **ComputerName** parameters of `Enter-PSSession` or `Invoke-Command`. When you use the **ComputerName** parameter, @@ -138,7 +138,7 @@ help you manage the **PSSession** objects in subsequent commands. ### Example 3: Create sessions on multiple computers ```powershell -$s1, $s2, $s3 = New-PSSession -ComputerName Server01,Server02,Server03 +$s1, $s2, $s3 = New-PSSession -ComputerName Server01, Server02, Server03 ``` This command creates three **PSSession** objects, one on each of the computers specified by the @@ -461,7 +461,7 @@ To use an IP address in the value of the **ComputerName** parameter, the command address of the remote computer must be included in the WinRM TrustedHosts list on the local computer. For instructions for adding a computer name to the TrustedHosts list, see "How to Add a Computer to the Trusted Host List" in -[about_Remote_Troubleshooting](about/about_Remote_Troubleshooting.md). +[about_Remote_Troubleshooting](About/about_Remote_Troubleshooting.md). To include the local computer in the value of the **ComputerName** parameter, start Windows PowerShell by using the **Run as administrator option**. @@ -740,7 +740,7 @@ Before using another port, you must configure the WinRM listener on the remote c that port. Use the following commands to configure the listener: 1. `winrm delete winrm/config/listener?Address=*+Transport=HTTP` -2. `winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="\"}` +1. `winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="\"}` Do not use the **Port** parameter unless you must. The port setting in the command applies to all computers or sessions on which the command runs. An alternate port setting might prevent the command @@ -1033,8 +1033,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see about_CommonParameters -(https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/7.5/Microsoft.PowerShell.Core/New-PSSessionConfigurationFile.md b/reference/7.5/Microsoft.PowerShell.Core/New-PSSessionConfigurationFile.md index 2d454a6e7c31..fb556a62ffb3 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/New-PSSessionConfigurationFile.md +++ b/reference/7.5/Microsoft.PowerShell.Core/New-PSSessionConfigurationFile.md @@ -234,13 +234,15 @@ CompanyName = 'Fabrikam Corporation' # Copyright statement for this document Copyright = '(c) Fabrikam Corporation. All rights reserved.' -# Session type defaults to apply for this session configuration. Can be 'RestrictedRemoteServer' (recommended), 'Empty', or 'Default' +# Session type defaults to apply for this session configuration. Can be +# 'RestrictedRemoteServer' (recommended), 'Empty', or 'Default' SessionType = 'Default' # Directory to place session transcripts for this session configuration # TranscriptDirectory = 'C:\Transcripts\' -# Whether to run this session configuration as the machine's (virtual) administrator account +# Whether to run this session configuration as the machine's (virtual) administrator +# account RunAsVirtualAccount = $true # Groups associated with machine's (virtual) administrator account @@ -249,10 +251,12 @@ RunAsVirtualAccountGroups = 'Backup Operators' # Scripts to run when applied to a session ScriptsToProcess = 'Get-Inputs.ps1' -# User roles (security groups), and the role capabilities that should be applied to them when applied to a session +# User roles (security groups), and the role capabilities that should be applied to them +# when applied to a session # RoleDefinitions = @{ 'CONTOSO\SqlAdmins' = @{ RoleCapabilities = 'SqlAdministration' }; 'CONTOSO\SqlManaged' = @{ RoleCapabilityFiles = 'C:\RoleCapability\SqlManaged.psrc' }; 'CONTOSO\ServerMonitors' = @{ VisibleCmdlets = 'Get-Process' } } -# Language mode to apply when applied to a session. Can be 'NoLanguage' (recommended), 'RestrictedLanguage', 'ConstrainedLanguage', or 'FullLanguage' +# Language mode to apply when applied to a session. Can be 'NoLanguage' (recommended), +# 'RestrictedLanguage', 'ConstrainedLanguage', or 'FullLanguage' LanguageMode = 'FullLanguage' # Execution policy to apply when applied to a session @@ -458,7 +462,7 @@ Accept wildcard characters: False Specifies the execution policy of sessions that use the session configuration. If you omit this parameter, the value of the **ExecutionPolicy** key in the session configuration file is **Restricted**. For information about execution policies in PowerShell, see -[about_Execution_Policies](about/about_Execution_Policies.md). +[about_Execution_Policies](About/about_Execution_Policies.md). ```yaml Type: Microsoft.PowerShell.ExecutionPolicy diff --git a/reference/7.5/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/7.5/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index e99e7d28af21..50630d18049e 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/ConvertFrom-Json.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: 01/29/2024 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-json?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertFrom-Json @@ -36,10 +36,11 @@ To generate a JSON string from any object, use the `ConvertTo-Json` cmdlet. This cmdlet was introduced in PowerShell 3.0. > [!NOTE] -> Beginning with PowerShell 6, the cmdlet supports JSON with comments. JSON comments start with two -> forward slashes (`//`) characters. JSON comments aren't captured in the objects output by the -> cmdlet. Prior to PowerShell 6, `ConvertFrom-Json` would return an error when it encountered a JSON -> comment. +> In Windows PowerShell 5.1, `ConvertFrom-Json` returned an error when it encountered a JSON +> comment. In PowerShell 6 and higher, the cmdlet supports JSON with comments. JSON comments aren't +> captured in the objects output by the cmdlet. For more information, see the _JSON comments_ +> section of the +> [about_Comments](/powershell/module/microsoft.powershell.core/about/about_comments) article. ## EXAMPLES @@ -76,16 +77,16 @@ TimeOfDay : @{Ticks=546269310476; Days=0; Hours=15; Milliseconds=931; Microsec Year : 2024 ``` -The example uses the `Select-Object` cmdlet to get all of the properties of the **DateTime** object. -It uses the `ConvertTo-Json` cmdlet to convert the **DateTime** object to a string formatted as a -JSON object and the `ConvertFrom-Json` cmdlet to convert the JSON-formatted string to a -**PSCustomObject** object. +The example uses the `Select-Object` cmdlet to get all of the properties of the **DateTime** +object. It uses the `ConvertTo-Json` cmdlet to convert the **DateTime** object to a string +formatted as a JSON object and the `ConvertFrom-Json` cmdlet to convert the JSON-formatted string +to a **PSCustomObject** object. ### Example 2: Get JSON strings from a web service and convert them to PowerShell objects -This command uses the `Invoke-WebRequest` cmdlet to get JSON strings from a web service and then it -uses the `ConvertFrom-Json` cmdlet to convert JSON content to objects that can be managed in -PowerShell. +This command uses the `Invoke-WebRequest` cmdlet to get JSON strings from a web service +and then it uses the `ConvertFrom-Json` cmdlet to convert JSON content to objects +that can be managed in PowerShell. ```powershell # Ensures that Invoke-WebRequest uses TLS 1.2 @@ -105,9 +106,9 @@ custom object. Get-Content -Raw JsonFile.JSON | ConvertFrom-Json ``` -The command uses Get-Content cmdlet to get the strings in a JSON file. The **Raw** parameter returns -the whole file as a single JSON object. Then it uses the pipeline operator to send the delimited -string to the `ConvertFrom-Json` cmdlet, which converts it to a custom object. +The command uses Get-Content cmdlet to get the strings in a JSON file. The **Raw** parameter +returns the whole file as a single JSON object. Then it uses the pipeline operator to send the +delimited string to the `ConvertFrom-Json` cmdlet, which converts it to a custom object. ### Example 4: Convert a JSON string to a hash table diff --git a/reference/7.5/Microsoft.PowerShell.Utility/Invoke-RestMethod.md b/reference/7.5/Microsoft.PowerShell.Utility/Invoke-RestMethod.md index 4806dd48ce23..6eb9ca1cf9d3 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/Invoke-RestMethod.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/Invoke-RestMethod.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: 11/18/2024 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-restmethod?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: Invoke-RestMethod @@ -99,17 +99,17 @@ The `Invoke-RestMethod` cmdlet sends HTTP and HTTPS requests to Representational PowerShell formats the response based to the data type. For an RSS or ATOM feed, PowerShell returns the Item or Entry XML nodes. For JavaScript Object Notation (JSON) or XML, PowerShell converts, or -deserializes, the content into `[PSCustomObject]` objects. +deserializes, the content into `[PSCustomObject]` objects. Comments are permitted in the JSON data. > [!NOTE] > When the REST endpoint returns multiple objects, the objects are received as an array. If you pipe -> the output from `Invoke-RestMethod` to another command, it is sent as a single `[Object[]]` -> object. The contents of that array are not enumerated for the next command on the pipeline. +> the output from `Invoke-RestMethod` to another command, it's sent as a single `[Object[]]` +> object. The contents of that array aren't enumerated for the next command on the pipeline. This cmdlet is introduced in Windows PowerShell 3.0. Beginning in PowerShell 7.0, `Invoke-RestMethod` supports proxy configuration defined by environment -variables. See the [Notes](#notes) section of this article. +variables. See the [NOTES](#notes) section of this article. Beginning in PowerShell 7.4, character encoding for requests defaults to UTF-8 instead of ASCII. If you need a different encoding, you must set the `charset` attribute in the `Content-Type` header. @@ -159,8 +159,8 @@ $Body = @{ Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv ``` -The credentials are prompted for and then stored in `$Cred` and the URL that will be access is -defined in `$Url`. +The cmdlet prompts for credentials and stores them in `$Cred`. `$Url` contains the REST endpoint +URL. The `$Body` variable describes the search criteria, specifies CSV as the output mode, and specifies a time period for returned data that starts two days ago and ends one day ago. The body variable @@ -202,18 +202,18 @@ $Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form The profile form requires these fields: `firstName`, `lastName`, `email`, `avatar`, `birthday`, and `hobbies`. The API is expecting an image for the user profile pic to be supplied in the `avatar` -field. The API will also accept multiple `hobbies` entries to be submitted in the same form. +field. The API also accepts multiple `hobbies` entries to be submitted in the same form. When creating the `$Form` HashTable, the key names are used as form field names. By default, the -values of the HashTable will be converted to strings. If a `System.IO.FileInfo` value is present, -the file contents will be submitted. If a collection such as arrays or lists are present, the form -field will be submitted multiple times. +values of the HashTable are converted to strings. If a `System.IO.FileInfo` value is present, the +file contents are submitted. If a collection, such as an array or list are present, the form field +is submitted multiple times. -By using `Get-Item` on the `avatar` key, the `FileInfo` object will be set as the value. The result -is that the image data for `jdoe.png` will be submitted. +By using `Get-Item` on the `avatar` key, the `FileInfo` object is set as the value. The result +is that the image data for `jdoe.png` is submitted. -By supplying a list to the `hobbies` key, the `hobbies` field will be present in the submissions -once for each list item. +By supplying a list to the `hobbies` key, the `hobbies` field is present in the submissions once for +each list item. ### Example 5: Pass multiple headers @@ -230,7 +230,7 @@ Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body ### Example 6: Enumerate returned items on the pipeline -GitHub returns multiple objects an array. If you pipe the output to another command, it is sent as a +GitHub returns multiple objects an array. If you pipe the output to another command, it's sent as a single `[Object[]]`object. To enumerate the objects into the pipeline, pipe the results to `Write-Output` or wrap the cmdlet in @@ -292,7 +292,7 @@ assigned a hash table where the value of `If-Match` is invalid because it's defi instead of `"12345"`. Calling `Invoke-RestMethod` with the invalid headers returns an error reporting that the formatted -value is invalid. The request is not sent to the endpoint. +value is invalid. The request isn't sent to the endpoint. Calling `Invoke-RestMethod` with the **SkipHeaderValidation** parameter ignores the validation failure and sends the request to the endpoint. Because the endpoint tolerates non-compliant header @@ -321,7 +321,7 @@ Invoke-RestMethod -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/r ### -AllowInsecureRedirect -Allows redirecting from HTTPS to HTTP. By default, any request that is redirected from HTTPS to +Allows redirecting from HTTPS to HTTP. By default, any request that's redirected from HTTPS to HTTP results in an error and the request is aborted to prevent unintentionally communicating in plain text over unencrypted connections. To override this behavior at your own risk, use the **AllowInsecureRedirect** parameter. @@ -343,14 +343,14 @@ Accept wildcard characters: False ### -AllowUnencryptedAuthentication Allows sending of credentials and secrets over unencrypted connections. By default, supplying -**Credential** or any **Authentication** option with a **Uri** that does not begin with `https://` -will result in an error and the request will abort to prevent unintentionally communicating secrets -in plain text over unencrypted connections. To override this behavior at your own risk, supply the +**Credential** or any **Authentication** option with a **Uri** that doesn't begin with `https://` +results in an error and the request aborts to prevent unintentionally communicating secrets in plain +text over unencrypted connections. To override this behavior at your own risk, supply the **AllowUnencryptedAuthentication** parameter. > [!WARNING] -> Using this parameter is not secure and is not recommended. It is provided only for compatibility -> with legacy systems that cannot provide encrypted connections. Use at your own risk. +> Using this parameter isn't secure and isn't recommended. It's provided only for compatibility +> with legacy systems that can't provide encrypted connections. Use at your own risk. This feature was added in PowerShell 6.0.0. @@ -373,9 +373,9 @@ The **Authentication** parameter can't be used with the **UseDefaultCredentials* Available Authentication Options: -- `None`: This is the default option when **Authentication** is not supplied. No explicit - authentication will be used. -- `Basic`: Requires **Credential**. The credentials will be used to send an RFC 7617 Basic +- `None`: This is the default option when **Authentication** isn't supplied. No explicit + authentication is used. +- `Basic`: Requires **Credential**. The credentials are used to send an RFC 7617 Basic Authentication `Authorization: Basic` header in the format of `base64(user:password)`. - `Bearer`: Requires the **Token** parameter. Sends an RFC 6750 `Authorization: Bearer` header with the supplied token. @@ -426,11 +426,11 @@ parameter. When the body is a form, or it's the output of another `Invoke-WebRequest` call, PowerShell sets the request content to the form fields. -The **Body** parameter may also accept a **System.Net.Http.MultipartFormDataContent** object. This -will facilitate `multipart/form-data` requests. When a **MultipartFormDataContent** object is -supplied for **Body**, any content related headers supplied to the **ContentType**, **Headers**, or -**WebSession** parameters will be overridden by the content headers of the -`MultipartFormDataContent` object. This feature was added in PowerShell 6.0.0. +The **Body** parameter can also accept a **System.Net.Http.MultipartFormDataContent** object, which +facilitates `multipart/form-data` requests. When a **MultipartFormDataContent** object is supplied +for **Body**, any content related headers supplied to the **ContentType**, **Headers**, or +**WebSession** parameters are overridden by the content headers of the `MultipartFormDataContent` +object. This feature was added in PowerShell 6.0.0. ```yaml Type: System.Object @@ -446,7 +446,7 @@ Accept wildcard characters: False ### -Certificate -Specifies the client certificate that is used for a secure web request. Enter a variable that +Specifies the client certificate that's used for a secure web request. Enter a variable that contains a certificate or a command or expression that gets the certificate. To find a certificate, use `Get-PfxCertificate` or use the `Get-ChildItem` cmdlet in the Certificate @@ -530,8 +530,7 @@ If this parameter is omitted and the request method is POST, `Invoke-RestMethod` type to `application/x-www-form-urlencoded`. Otherwise, the content type isn't specified in the call. -**ContentType** will be overridden when a `MultipartFormDataContent` object is supplied for -**Body**. +**ContentType** is overridden when a `MultipartFormDataContent` object is supplied for **Body**. Starting in PowerShell 7.4, if you use this both this parameter and the **Headers** parameter to define the `Content-Type` header, the value specified in the **ContentType** parameter is used. @@ -555,10 +554,10 @@ Specifies a user account that has permission to send the request. The default is Type a user name, such as **User01** or **Domain01\User01**, or enter a **PSCredential** object generated by the `Get-Credential` cmdlet. -**Credential** can be used alone or in conjunction with certain **Authentication** parameter -options. When used alone, it will only supply credentials to the remote server if the remote server +You can use **Credential** alone or in conjunction with certain **Authentication** parameter +options. When used alone, it only supplies credentials to the remote server if the remote server sends an authentication challenge request. When used with **Authentication** options, the -credentials will be explicitly sent. +credentials is explicitly sent. Credentials are stored in a [PSCredential](/dotnet/api/system.management.automation.pscredential) object and the password is stored as a [SecureString](/dotnet/api/system.security.securestring). @@ -582,7 +581,7 @@ Accept wildcard characters: False ### -CustomMethod Specifies custom method used for the web request. This can be used with the Request Method required -by the endpoint is not an available option on the **Method**. **Method** and **CustomMethod** cannot +by the endpoint isn't an available option on the **Method**. **Method** and **CustomMethod** can't be used together. Example: @@ -607,9 +606,8 @@ Accept wildcard characters: False ### -DisableKeepAlive -Indicates that the cmdlet sets the **KeepAlive** value in the HTTP header to False. By default, -**KeepAlive** is True. **KeepAlive** establishes a persistent connection to the server to facilitate -subsequent requests. +Sets the **KeepAlive** value in the HTTP header to False. By default, **KeepAlive** is True. +**KeepAlive** establishes a persistent connection to the server to facilitate subsequent requests. ```yaml Type: System.Management.Automation.SwitchParameter @@ -628,9 +626,9 @@ Accept wildcard characters: False Indicates the cmdlet should follow relation links. Some REST APIs support pagination via Relation Links per -[RFC5988](https://tools.ietf.org/html/rfc5988#page-6). Instead of parsing the header to get the URL -for the next page, you can have the cmdlet do this for you. To set how many times to follow relation -links, use the **MaximumFollowRelLink** parameter. +[RFC5988](https://tools.ietf.org/html/rfc5988#section-5). Instead of parsing the header to get the +URL for the next page, you can have the cmdlet do this for you. To set how many times to follow +relation links, use the **MaximumFollowRelLink** parameter. When using this switch, the cmdlet returns a collection of pages of results. Each page of results may contain multiple result items. @@ -652,15 +650,14 @@ Accept wildcard characters: False ### -Form Converts a dictionary to a `multipart/form-data` submission. **Form** may not be used with **Body**. -If **ContentType** will be ignored. +The **ContentType** is ignored. -The keys of the dictionary will be used as the form field names. By default, form values will be -converted to string values. +The keys of the dictionary are used as the form field names. By default, form values are converted +to string values. -If the value is a **System.IO.FileInfo** object, then the binary file contents will be submitted. -The name of the file will be submitted as the `filename`. The MIME will be set as -`application/octet-stream`. `Get-Item` can be used to simplify supplying the **System.IO.FileInfo** -object. +If the value is a **System.IO.FileInfo** object, then the binary file contents is submitted. The +name of the file is submitted as the `filename`. The MIME type is set as `application/octet-stream`. +`Get-Item` can be used to simplify supplying the **System.IO.FileInfo** object. ```powershell $Form = @{ @@ -668,9 +665,9 @@ $Form = @{ } ``` -If the value is a collection type, such as an Array or List, the for field will be submitted -multiple times. The values of the list will be treated as strings by default. If the value is a -**System.IO.FileInfo** object, then the binary file contents will be submitted. Nested collections +If the value is a collection type, such as an Array or List, the form field is submitted multiple +times. The values of the list are treated as strings by default. If the value is a +**System.IO.FileInfo** object, then the binary file contents are submitted. Nested collections aren't supported. ```powershell @@ -680,10 +677,9 @@ $Form = @{ } ``` -In the above example, the `tags` field will be supplied three times in the form, once for each of -`Vacation`, `Italy`, and `2017`. The `pictures` field will also be submitted once for each file in -the `2017-Italy` folder. The binary contents of the files in that folder will be submitted as the -values. +In the above example, the `tags` field is supplied three times in the form, once for each of the +values: `Vacation`, `Italy`, and `2017`. The `pictures` field is submitted once for each file in the +`2017-Italy` folder. The binary contents of the files in that folder are submitted as the values. This feature was added in PowerShell 6.1.0. @@ -848,10 +844,8 @@ Accept wildcard characters: False ### -NoProxy -Indicates that the cmdlet will not use a proxy to reach the destination. - -When you need to bypass the proxy configured in Internet Explorer, or a proxy specified in the -environment, use this switch. +Indicates that the cmdlet won't use a proxy to reach the destination. Use this to bypass the proxy +configured in your internet settings or specified in the environment. This parameter was introduced in PowerShell 6.0. @@ -995,11 +989,11 @@ Accept wildcard characters: False ### -ProxyCredential -Specifies a user account that has permission to use the proxy server that is specified by the +Specifies a user account that has permission to use the proxy server that's specified by the **Proxy** parameter. The default is the current user. -Type a user name, such as **User01** or **Domain01\User01**, **User@Domain.Com**, or enter a -`PSCredential` object, such as one generated by the `Get-Credential` cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such +as one generated by the `Get-Credential` cmdlet. This parameter is valid only when the **Proxy** parameter is also used in the command. You can't use the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command. @@ -1018,8 +1012,8 @@ Accept wildcard characters: False ### -ProxyUseDefaultCredentials -Indicates that the cmdlet uses the credentials of the current user to access the proxy server that -is specified by the **Proxy** parameter. +Uses the credentials of the current user to access the proxy server that is specified by the +**Proxy** parameter. This parameter is valid only when the **Proxy** parameter is also used in the command. You can't use the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command. @@ -1064,22 +1058,22 @@ requires the **OutFile** parameter. **Resume** only operates on the size of the local file and remote file and performs no other validation that the local file and the remote file are the same. -If the local file size is smaller than the remote file size, then the cmdlet will attempt to resume +If the local file size is smaller than the remote file size, then the cmdlet attempts to resume downloading the file and append the remaining bytes to the end of the file. If the local file size is the same as the remote file size, then no action is taken and the cmdlet assumes the download already completed. -If the local file size is larger than the remote file size, then the local file will be overwritten -and the entire remote file will be completely re-downloaded. This behavior is the same as using -**OutFile** without **Resume**. +If the local file size is larger than the remote file size, then the local file is overwritten and +the entire remote file is re-downloaded. This behavior is the same as using **OutFile** without +**Resume**. -If the remote server does not support download resuming, then the local file will be overwritten and -the entire remote file will be completely re-downloaded. This behavior is the same as using -**OutFile** without **Resume**. +If the remote server doesn't support download resuming, then the local file is overwritten and the +entire remote file is re-downloaded. This behavior is the same as using **OutFile** without +**Resume**. -If the local file doesn't exist, then the local file will be created and the entire remote file will -be completely downloaded. This behavior is the same as using **OutFile** without **Resume**. +If the local file doesn't exist, then the local file is created and the entire remote file is +downloaded. This behavior is the same as using **OutFile** without **Resume**. This feature was added in PowerShell 6.1.0. @@ -1161,7 +1155,7 @@ Skips certificate validation checks that include all validations such as expirat trusted root authority, etc. > [!WARNING] -> Using this parameter is not secure and is not recommended. This switch is only intended to be used +> Using this parameter isn't secure and isn't recommended. This switch is only intended to be used > against known hosts using a self-signed certificate for testing purposes. Use at your own risk. This feature was added in PowerShell 6.0.0. @@ -1182,11 +1176,11 @@ Accept wildcard characters: False Indicates the cmdlet should add headers to the request without validation. -This switch should be used for sites that require header values that do not conform to standards. +This switch should be used for sites that require header values that don't conform to standards. Specifying this switch disables validation to allow the value to be passed unchecked. When specified, all headers are added without validation. -This will disable validation for values passed to the **ContentType**, **Headers**, and +This switch disables validation for values passed to the **ContentType**, **Headers**, and **UserAgent** parameters. This feature was added in PowerShell 6.0.0. @@ -1230,17 +1224,11 @@ protocols for compliance purposes. These values are defined as a flag-based enumeration. You can combine multiple values together to set multiple flags using this parameter. The values can be passed to the **SslProtocol** parameter -as an array of values or as a comma-separated string of those values. The cmdlet will combine the -values using a binary-OR operation. Passing values as an array is the simplest option and also -allows you to use tab-completion on the values. You may not be able to supply multiple values on all -platforms. - -> [!NOTE] -> On non-Windows platforms it may not be possible to supply `Tls` or `Tls12` as an option. Support -> for `Tls13` is not available on all operating systems and will need to be verified on a per -> operating system basis. +as an array of values or as a comma-separated string of those values. The cmdlet combines the values +using a binary-OR operation. Passing values as an array is the simplest option and also allows you +to use tab-completion on the values. You may not be able to supply multiple values on all platforms. -This feature was added in PowerShell 6.0.0 and support for `Tls13` was added in PowerShell 7.1. +This feature was added in PowerShell 6.0.0. Support for `Tls13` was added in PowerShell 7.1. ```yaml Type: Microsoft.PowerShell.Commands.WebSslProtocol @@ -1372,8 +1360,8 @@ Accept wildcard characters: False ### -UseBasicParsing This parameter has been deprecated. Beginning with PowerShell 6.0.0, all Web requests use basic -parsing only. This parameter is included for backwards compatibility only and any use of it will -have no effect on the operation of the cmdlet. +parsing only. This parameter is included for backwards compatibility only. When used, it has no +effect on the operation of the cmdlet. ```yaml Type: System.Management.Automation.SwitchParameter @@ -1412,9 +1400,9 @@ The default user agent is similar to `Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0` with slight variations for each operating system and platform. -To test a website with the standard user agent string that is used by most internet browsers, use -the properties of the [PSUserAgent](/dotnet/api/microsoft.powershell.commands.psuseragent) class, -such as Chrome, Firefox, InternetExplorer, Opera, and Safari. +To test a website with the standard user agent string that's used by most internet browsers, use +the properties of the [PSUserAgent](xref:Microsoft.PowerShell.Commands.PSUserAgent) class, such as +Chrome, Firefox, InternetExplorer, Opera, and Safari. ```yaml Type: System.String @@ -1434,8 +1422,8 @@ Specifies a web request session. Enter the variable name, including the dollar s To override a value in the web request session, use a cmdlet parameter, such as **UserAgent** or **Credential**. Parameter values take precedence over values in the web request session. Content -related headers, such as `Content-Type`, will be also be overridden when a -**MultipartFormDataContent** object is supplied for **Body**. +related headers, such as `Content-Type`, are overridden when a **MultipartFormDataContent** object +is supplied for **Body**. Unlike a remote session, the web request session isn't a persistent connection. It's an object that contains information about the connection and the request, including cookies, credentials, the @@ -1502,16 +1490,16 @@ PowerShell includes the following aliases for `Invoke-RestMethod`: Some features may not be available on all platforms. Because of changes in .NET Core 3.1, PowerShell 7.0 and higher use the -[HttpClient.DefaultProxy](xref:System.Net.Http.HttpClient.DefaultProxy*) -property to determine the proxy configuration. +[HttpClient.DefaultProxy](xref:System.Net.Http.HttpClient.DefaultProxy*) property to determine the +proxy configuration. -The value of this property is different rules depending on your platform: +The value of this property differ depending on your platform: -- **For Windows**: Reads proxy configuration from environment variables or, if those are not - defined, from the user's proxy settings. -- **For macOS**: Reads proxy configuration from environment variables or, if those are not defined, +- **For Windows**: Reads proxy configuration from environment variables or, if those aren't defined, + from the user's proxy settings. +- **For macOS**: Reads proxy configuration from environment variables or, if those aren't defined, from the system's proxy settings. -- **For Linux**: Reads proxy configuration from environment variables or, in case those are not +- **For Linux**: Reads proxy configuration from environment variables or, in case those aren't defined, this property initializes a non-configured instance that bypasses all addresses. The environment variables used for `DefaultProxy` initialization on Windows and Unix-based platforms @@ -1520,7 +1508,7 @@ are: - `HTTP_PROXY`: the hostname or IP address of the proxy server used on HTTP requests. - `HTTPS_PROXY`: the hostname or IP address of the proxy server used on HTTPS requests. - `ALL_PROXY`: the hostname or IP address of the proxy server used on HTTP and HTTPS requests in - case `HTTP_PROXY` or `HTTPS_PROXY` are not defined. + case `HTTP_PROXY` or `HTTPS_PROXY` aren't defined. - `NO_PROXY`: a comma-separated list of hostnames that should be excluded from proxying. PowerShell 7.4 added support for the Brotli compression algorithm. diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 902a953ca034..7698b2f16cbb 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -1,7 +1,7 @@ --- description: Describes regular expressions in PowerShell. Locale: en-US -ms.date: 06/14/2024 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_regular_expressions?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Regular_Expressions @@ -17,19 +17,20 @@ Describes regular expressions in PowerShell. > [!NOTE] > This article shows the syntax and methods for using regular expressions in > PowerShell. It doesn't cover all possible expressions. For a more complete -> reference, see the [Regular Expression Language - Quick Reference][03]. +> reference, see the [Regular Expression Language - Quick Reference][02]. A regular expression is a pattern used to match text. It can be made up of -literal characters, operators, and other constructs. +literal characters, operators, and other constructs. PowerShell uses the +[.NET regex][03] engine. This article demonstrates regular expression syntax in PowerShell. PowerShell has several operators and cmdlets that use regular expressions. You can read more about their syntax and usage at the links below. -- [Select-String][10] -- [-match and -replace operators][06] -- [-split operator][08] -- [switch statement with -regex option][09] +- [Select-String][11] +- [-match and -replace operators][07] +- [-split operator][09] +- [switch statement with -regex option][10] PowerShell regular expressions are case-insensitive by default. Each method shown above has a different way to force case sensitivity. @@ -81,8 +82,8 @@ characters). ### Numbers -The `\d` character class will match any decimal digit. Conversely, `\D` will -match any character except decimal digits. +The `\d` character class matchs any decimal digit. Conversely, `\D` matches any +character except decimal digits. ```powershell # This expression returns true if it matches a server name. @@ -92,7 +93,7 @@ match any character except decimal digits. ### Word characters -The `\w` character class will match any word character `[a-zA-Z_0-9]`. To match +The `\w` character class matches any word character `[a-zA-Z_0-9]`. To match any non-word character, use `\W`. ```powershell @@ -103,8 +104,8 @@ any non-word character, use `\W`. ### Wildcards -The period (`.`) is a wildcard character in regular expressions. It will match -any character except a newline (`\n`). +The period (`.`) is a wildcard character in regular expressions. It matches any +character except a newline (`\n`). ```powershell # This expression returns true. @@ -155,7 +156,7 @@ The plus sign (`+`) matches the previous element one or more times. ``` The question mark `?` matches the previous element zero or one time. Like -asterisk `*`, it will even match strings where the element is absent. +asterisk `*`, it even matches strings where the element is absent. ```powershell # This returns true for any server name, even server names without dashes. @@ -208,7 +209,7 @@ When using anchors in PowerShell, you should understand the difference between instead of matching every character EXCEPT the newline `\n`. To read more about these options and how to use them, visit the -[Regular Expression Language - Quick Reference][03]. +[Regular Expression Language - Quick Reference][02]. ## Escaping characters @@ -372,10 +373,10 @@ Name Value ---- ----- D CONTOSO N jsmith -0 A process has exited.... +0 A process has exited... ``` -For more information, see [Grouping Constructs in Regular Expressions][02]. +For more information, see [Grouping Constructs in Regular Expressions][01]. ### Substitutions in Regular Expressions @@ -461,18 +462,32 @@ Gobble Gobble For detailed information on substitution expressions, see [Substitutions in Regular Expressions][04]. +## Comments in regular expressions + +Regular expressions can be very complex and difficult to read. You can use +comments to make them more understandable. There are two types of comments +allowed in regular expressions. + +- Inline comment (`(?#)`) +- End-of-line comment (`#`) + +For more information, see the _Regular expression comments_ section of +[about_Comments][05]. + ## See also -- [about_Operators][07] -- [about_Comparison_Operators][05] +- [about_Operators][08] +- [about_Comparison_Operators][06] -[02]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions -[03]: /dotnet/standard/base-types/regular-expression-language-quick-reference +[01]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions +[02]: /dotnet/standard/base-types/regular-expression-language-quick-reference +[03]: /dotnet/standard/base-types/regular-expressions [04]: /dotnet/standard/base-types/substitutions-in-regular-expressions -[05]: about_Comparison_Operators.md -[06]: about_Comparison_Operators.md#matching-operators -[07]: about_Operators.md -[08]: about_Split.md -[09]: about_Switch.md -[10]: xref:Microsoft.PowerShell.Utility.Select-String +[05]: about_Comments.md#regular-expression-comments +[06]: about_Comparison_Operators.md +[07]: about_Comparison_Operators.md#matching-operators +[08]: about_Operators.md +[09]: about_Split.md +[10]: about_Switch.md +[11]: xref:Microsoft.PowerShell.Utility.Select-String diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Signing.md index 7050663c78b6..48d14ee43833 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Signing.md @@ -1,7 +1,7 @@ --- description: Explains how to sign scripts so that they comply with the PowerShell execution policies. Locale: en-US -ms.date: 01/07/2025 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Signing @@ -17,7 +17,7 @@ policies. > This information only applies to PowerShell running on Windows. -The Restricted execution policy doesn't permit any scripts to run. The +The **Restricted** execution policy doesn't permit any scripts to run. The **AllSigned** and **RemoteSigned** execution policies prevent PowerShell from running scripts that don't have a digital signature. @@ -143,10 +143,8 @@ certificate. Two types of certificates are suitable for signing a script file: not run on other computers. Self-signed certificate should only be used to sign scripts for testing -purposes. - -It isn't appropriate for scripts that will be shared, even within an -enterprise. +purposes. Self-signed certificates aren't appropriate for scripts that you want +to share. If you create a self-signed certificate, be sure to enable strong private key protection on your certificate. This prevents malicious programs from signing @@ -222,7 +220,7 @@ Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My Thumbprint Subject ---------- ------- -4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ] +4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ``` ## Sign a script @@ -267,6 +265,10 @@ $cert = Get-ChildItem Cert:\CurrentUser\My -CodeSigningCert | Set-AuthenticodeSignature add-signature.ps1 $cert ``` +The `Set-AuthenticodeSignature` cmdlet adds the signature to the script file as +a comment block at the end of the file. The comment block begins and ends with +`# SIG #`. + After you sign the script, you can run it on the local computer. However, the script won't run on computers where the PowerShell execution policy requires a digital signature from a trusted authority. If you try, PowerShell displays the diff --git a/reference/7.6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/7.6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index 2c8444a026ee..e324a5b87640 100644 --- a/reference/7.6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/7.6/Microsoft.PowerShell.Utility/ConvertFrom-Json.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: 01/29/2024 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-json?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertFrom-Json @@ -36,10 +36,11 @@ To generate a JSON string from any object, use the `ConvertTo-Json` cmdlet. This cmdlet was introduced in PowerShell 3.0. > [!NOTE] -> Beginning with PowerShell 6, the cmdlet supports JSON with comments. JSON comments start with two -> forward slashes (`//`) characters. JSON comments aren't captured in the objects output by the -> cmdlet. Prior to PowerShell 6, `ConvertFrom-Json` would return an error when it encountered a JSON -> comment. +> In Windows PowerShell 5.1, `ConvertFrom-Json` returned an error when it encountered a JSON +> comment. In PowerShell 6 and higher, the cmdlet supports JSON with comments. JSON comments aren't +> captured in the objects output by the cmdlet. For more information, see the _JSON comments_ +> section of the +> [about_Comments](/powershell/module/microsoft.powershell.core/about/about_comments) article. ## EXAMPLES @@ -76,16 +77,16 @@ TimeOfDay : @{Ticks=546269310476; Days=0; Hours=15; Milliseconds=931; Microsec Year : 2024 ``` -The example uses the `Select-Object` cmdlet to get all of the properties of the **DateTime** object. -It uses the `ConvertTo-Json` cmdlet to convert the **DateTime** object to a string formatted as a -JSON object and the `ConvertFrom-Json` cmdlet to convert the JSON-formatted string to a -**PSCustomObject** object. +The example uses the `Select-Object` cmdlet to get all of the properties of the **DateTime** +object. It uses the `ConvertTo-Json` cmdlet to convert the **DateTime** object to a string +formatted as a JSON object and the `ConvertFrom-Json` cmdlet to convert the JSON-formatted string +to a **PSCustomObject** object. ### Example 2: Get JSON strings from a web service and convert them to PowerShell objects -This command uses the `Invoke-WebRequest` cmdlet to get JSON strings from a web service and then it -uses the `ConvertFrom-Json` cmdlet to convert JSON content to objects that can be managed in -PowerShell. +This command uses the `Invoke-WebRequest` cmdlet to get JSON strings from a web service +and then it uses the `ConvertFrom-Json` cmdlet to convert JSON content to objects +that can be managed in PowerShell. ```powershell # Ensures that Invoke-WebRequest uses TLS 1.2 @@ -105,9 +106,9 @@ custom object. Get-Content -Raw JsonFile.JSON | ConvertFrom-Json ``` -The command uses Get-Content cmdlet to get the strings in a JSON file. The **Raw** parameter returns -the whole file as a single JSON object. Then it uses the pipeline operator to send the delimited -string to the `ConvertFrom-Json` cmdlet, which converts it to a custom object. +The command uses Get-Content cmdlet to get the strings in a JSON file. The **Raw** parameter +returns the whole file as a single JSON object. Then it uses the pipeline operator to send the +delimited string to the `ConvertFrom-Json` cmdlet, which converts it to a custom object. ### Example 4: Convert a JSON string to a hash table diff --git a/reference/7.6/Microsoft.PowerShell.Utility/Invoke-RestMethod.md b/reference/7.6/Microsoft.PowerShell.Utility/Invoke-RestMethod.md index a4425a3a327a..5949adf58149 100644 --- a/reference/7.6/Microsoft.PowerShell.Utility/Invoke-RestMethod.md +++ b/reference/7.6/Microsoft.PowerShell.Utility/Invoke-RestMethod.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: 11/18/2024 +ms.date: 01/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-restmethod?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: Invoke-RestMethod @@ -99,17 +99,17 @@ The `Invoke-RestMethod` cmdlet sends HTTP and HTTPS requests to Representational PowerShell formats the response based to the data type. For an RSS or ATOM feed, PowerShell returns the Item or Entry XML nodes. For JavaScript Object Notation (JSON) or XML, PowerShell converts, or -deserializes, the content into `[PSCustomObject]` objects. +deserializes, the content into `[PSCustomObject]` objects. Comments are permitted in the JSON data. > [!NOTE] > When the REST endpoint returns multiple objects, the objects are received as an array. If you pipe -> the output from `Invoke-RestMethod` to another command, it is sent as a single `[Object[]]` -> object. The contents of that array are not enumerated for the next command on the pipeline. +> the output from `Invoke-RestMethod` to another command, it's sent as a single `[Object[]]` +> object. The contents of that array aren't enumerated for the next command on the pipeline. This cmdlet is introduced in Windows PowerShell 3.0. Beginning in PowerShell 7.0, `Invoke-RestMethod` supports proxy configuration defined by environment -variables. See the [Notes](#notes) section of this article. +variables. See the [NOTES](#notes) section of this article. Beginning in PowerShell 7.4, character encoding for requests defaults to UTF-8 instead of ASCII. If you need a different encoding, you must set the `charset` attribute in the `Content-Type` header. @@ -159,8 +159,8 @@ $Body = @{ Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv ``` -The credentials are prompted for and then stored in `$Cred` and the URL that will be access is -defined in `$Url`. +The cmdlet prompts for credentials and stores them in `$Cred`. `$Url` contains the REST endpoint +URL. The `$Body` variable describes the search criteria, specifies CSV as the output mode, and specifies a time period for returned data that starts two days ago and ends one day ago. The body variable @@ -202,18 +202,18 @@ $Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form The profile form requires these fields: `firstName`, `lastName`, `email`, `avatar`, `birthday`, and `hobbies`. The API is expecting an image for the user profile pic to be supplied in the `avatar` -field. The API will also accept multiple `hobbies` entries to be submitted in the same form. +field. The API also accepts multiple `hobbies` entries to be submitted in the same form. When creating the `$Form` HashTable, the key names are used as form field names. By default, the -values of the HashTable will be converted to strings. If a `System.IO.FileInfo` value is present, -the file contents will be submitted. If a collection such as arrays or lists are present, the form -field will be submitted multiple times. +values of the HashTable are converted to strings. If a `System.IO.FileInfo` value is present, the +file contents are submitted. If a collection, such as an array or list are present, the form field +is submitted multiple times. -By using `Get-Item` on the `avatar` key, the `FileInfo` object will be set as the value. The result -is that the image data for `jdoe.png` will be submitted. +By using `Get-Item` on the `avatar` key, the `FileInfo` object is set as the value. The result +is that the image data for `jdoe.png` is submitted. -By supplying a list to the `hobbies` key, the `hobbies` field will be present in the submissions -once for each list item. +By supplying a list to the `hobbies` key, the `hobbies` field is present in the submissions once for +each list item. ### Example 5: Pass multiple headers @@ -230,7 +230,7 @@ Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body ### Example 6: Enumerate returned items on the pipeline -GitHub returns multiple objects an array. If you pipe the output to another command, it is sent as a +GitHub returns multiple objects an array. If you pipe the output to another command, it's sent as a single `[Object[]]`object. To enumerate the objects into the pipeline, pipe the results to `Write-Output` or wrap the cmdlet in @@ -292,7 +292,7 @@ assigned a hash table where the value of `If-Match` is invalid because it's defi instead of `"12345"`. Calling `Invoke-RestMethod` with the invalid headers returns an error reporting that the formatted -value is invalid. The request is not sent to the endpoint. +value is invalid. The request isn't sent to the endpoint. Calling `Invoke-RestMethod` with the **SkipHeaderValidation** parameter ignores the validation failure and sends the request to the endpoint. Because the endpoint tolerates non-compliant header @@ -321,7 +321,7 @@ Invoke-RestMethod -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/r ### -AllowInsecureRedirect -Allows redirecting from HTTPS to HTTP. By default, any request that is redirected from HTTPS to +Allows redirecting from HTTPS to HTTP. By default, any request that's redirected from HTTPS to HTTP results in an error and the request is aborted to prevent unintentionally communicating in plain text over unencrypted connections. To override this behavior at your own risk, use the **AllowInsecureRedirect** parameter. @@ -343,14 +343,14 @@ Accept wildcard characters: False ### -AllowUnencryptedAuthentication Allows sending of credentials and secrets over unencrypted connections. By default, supplying -**Credential** or any **Authentication** option with a **Uri** that does not begin with `https://` -will result in an error and the request will abort to prevent unintentionally communicating secrets -in plain text over unencrypted connections. To override this behavior at your own risk, supply the +**Credential** or any **Authentication** option with a **Uri** that doesn't begin with `https://` +results in an error and the request aborts to prevent unintentionally communicating secrets in plain +text over unencrypted connections. To override this behavior at your own risk, supply the **AllowUnencryptedAuthentication** parameter. > [!WARNING] -> Using this parameter is not secure and is not recommended. It is provided only for compatibility -> with legacy systems that cannot provide encrypted connections. Use at your own risk. +> Using this parameter isn't secure and isn't recommended. It's provided only for compatibility +> with legacy systems that can't provide encrypted connections. Use at your own risk. This feature was added in PowerShell 6.0.0. @@ -373,9 +373,9 @@ The **Authentication** parameter can't be used with the **UseDefaultCredentials* Available Authentication Options: -- `None`: This is the default option when **Authentication** is not supplied. No explicit - authentication will be used. -- `Basic`: Requires **Credential**. The credentials will be used to send an RFC 7617 Basic +- `None`: This is the default option when **Authentication** isn't supplied. No explicit + authentication is used. +- `Basic`: Requires **Credential**. The credentials are used to send an RFC 7617 Basic Authentication `Authorization: Basic` header in the format of `base64(user:password)`. - `Bearer`: Requires the **Token** parameter. Sends an RFC 6750 `Authorization: Bearer` header with the supplied token. @@ -426,11 +426,11 @@ parameter. When the body is a form, or it's the output of another `Invoke-WebRequest` call, PowerShell sets the request content to the form fields. -The **Body** parameter may also accept a **System.Net.Http.MultipartFormDataContent** object. This -will facilitate `multipart/form-data` requests. When a **MultipartFormDataContent** object is -supplied for **Body**, any content related headers supplied to the **ContentType**, **Headers**, or -**WebSession** parameters will be overridden by the content headers of the -`MultipartFormDataContent` object. This feature was added in PowerShell 6.0.0. +The **Body** parameter can also accept a **System.Net.Http.MultipartFormDataContent** object, which +facilitates `multipart/form-data` requests. When a **MultipartFormDataContent** object is supplied +for **Body**, any content related headers supplied to the **ContentType**, **Headers**, or +**WebSession** parameters are overridden by the content headers of the `MultipartFormDataContent` +object. This feature was added in PowerShell 6.0.0. ```yaml Type: System.Object @@ -446,7 +446,7 @@ Accept wildcard characters: False ### -Certificate -Specifies the client certificate that is used for a secure web request. Enter a variable that +Specifies the client certificate that's used for a secure web request. Enter a variable that contains a certificate or a command or expression that gets the certificate. To find a certificate, use `Get-PfxCertificate` or use the `Get-ChildItem` cmdlet in the Certificate @@ -530,8 +530,7 @@ If this parameter is omitted and the request method is POST, `Invoke-RestMethod` type to `application/x-www-form-urlencoded`. Otherwise, the content type isn't specified in the call. -**ContentType** will be overridden when a `MultipartFormDataContent` object is supplied for -**Body**. +**ContentType** is overridden when a `MultipartFormDataContent` object is supplied for **Body**. Starting in PowerShell 7.4, if you use this both this parameter and the **Headers** parameter to define the `Content-Type` header, the value specified in the **ContentType** parameter is used. @@ -555,10 +554,10 @@ Specifies a user account that has permission to send the request. The default is Type a user name, such as **User01** or **Domain01\User01**, or enter a **PSCredential** object generated by the `Get-Credential` cmdlet. -**Credential** can be used alone or in conjunction with certain **Authentication** parameter -options. When used alone, it will only supply credentials to the remote server if the remote server +You can use **Credential** alone or in conjunction with certain **Authentication** parameter +options. When used alone, it only supplies credentials to the remote server if the remote server sends an authentication challenge request. When used with **Authentication** options, the -credentials will be explicitly sent. +credentials is explicitly sent. Credentials are stored in a [PSCredential](/dotnet/api/system.management.automation.pscredential) object and the password is stored as a [SecureString](/dotnet/api/system.security.securestring). @@ -582,7 +581,7 @@ Accept wildcard characters: False ### -CustomMethod Specifies custom method used for the web request. This can be used with the Request Method required -by the endpoint is not an available option on the **Method**. **Method** and **CustomMethod** cannot +by the endpoint isn't an available option on the **Method**. **Method** and **CustomMethod** can't be used together. Example: @@ -607,9 +606,8 @@ Accept wildcard characters: False ### -DisableKeepAlive -Indicates that the cmdlet sets the **KeepAlive** value in the HTTP header to False. By default, -**KeepAlive** is True. **KeepAlive** establishes a persistent connection to the server to facilitate -subsequent requests. +Sets the **KeepAlive** value in the HTTP header to False. By default, **KeepAlive** is True. +**KeepAlive** establishes a persistent connection to the server to facilitate subsequent requests. ```yaml Type: System.Management.Automation.SwitchParameter @@ -628,9 +626,9 @@ Accept wildcard characters: False Indicates the cmdlet should follow relation links. Some REST APIs support pagination via Relation Links per -[RFC5988](https://tools.ietf.org/html/rfc5988#page-6). Instead of parsing the header to get the URL -for the next page, you can have the cmdlet do this for you. To set how many times to follow relation -links, use the **MaximumFollowRelLink** parameter. +[RFC5988](https://tools.ietf.org/html/rfc5988#section-5). Instead of parsing the header to get the +URL for the next page, you can have the cmdlet do this for you. To set how many times to follow +relation links, use the **MaximumFollowRelLink** parameter. When using this switch, the cmdlet returns a collection of pages of results. Each page of results may contain multiple result items. @@ -652,15 +650,14 @@ Accept wildcard characters: False ### -Form Converts a dictionary to a `multipart/form-data` submission. **Form** may not be used with **Body**. -If **ContentType** will be ignored. +The **ContentType** is ignored. -The keys of the dictionary will be used as the form field names. By default, form values will be -converted to string values. +The keys of the dictionary are used as the form field names. By default, form values are converted +to string values. -If the value is a **System.IO.FileInfo** object, then the binary file contents will be submitted. -The name of the file will be submitted as the `filename`. The MIME will be set as -`application/octet-stream`. `Get-Item` can be used to simplify supplying the **System.IO.FileInfo** -object. +If the value is a **System.IO.FileInfo** object, then the binary file contents is submitted. The +name of the file is submitted as the `filename`. The MIME type is set as `application/octet-stream`. +`Get-Item` can be used to simplify supplying the **System.IO.FileInfo** object. ```powershell $Form = @{ @@ -668,9 +665,9 @@ $Form = @{ } ``` -If the value is a collection type, such as an Array or List, the for field will be submitted -multiple times. The values of the list will be treated as strings by default. If the value is a -**System.IO.FileInfo** object, then the binary file contents will be submitted. Nested collections +If the value is a collection type, such as an Array or List, the form field is submitted multiple +times. The values of the list are treated as strings by default. If the value is a +**System.IO.FileInfo** object, then the binary file contents are submitted. Nested collections aren't supported. ```powershell @@ -680,10 +677,9 @@ $Form = @{ } ``` -In the above example, the `tags` field will be supplied three times in the form, once for each of -`Vacation`, `Italy`, and `2017`. The `pictures` field will also be submitted once for each file in -the `2017-Italy` folder. The binary contents of the files in that folder will be submitted as the -values. +In the above example, the `tags` field is supplied three times in the form, once for each of the +values: `Vacation`, `Italy`, and `2017`. The `pictures` field is submitted once for each file in the +`2017-Italy` folder. The binary contents of the files in that folder are submitted as the values. This feature was added in PowerShell 6.1.0. @@ -848,10 +844,8 @@ Accept wildcard characters: False ### -NoProxy -Indicates that the cmdlet will not use a proxy to reach the destination. - -When you need to bypass the proxy configured in Internet Explorer, or a proxy specified in the -environment, use this switch. +Indicates that the cmdlet won't use a proxy to reach the destination. Use this to bypass the proxy +configured in your internet settings or specified in the environment. This parameter was introduced in PowerShell 6.0. @@ -995,11 +989,11 @@ Accept wildcard characters: False ### -ProxyCredential -Specifies a user account that has permission to use the proxy server that is specified by the +Specifies a user account that has permission to use the proxy server that's specified by the **Proxy** parameter. The default is the current user. -Type a user name, such as **User01** or **Domain01\User01**, **User@Domain.Com**, or enter a -`PSCredential` object, such as one generated by the `Get-Credential` cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such +as one generated by the `Get-Credential` cmdlet. This parameter is valid only when the **Proxy** parameter is also used in the command. You can't use the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command. @@ -1018,8 +1012,8 @@ Accept wildcard characters: False ### -ProxyUseDefaultCredentials -Indicates that the cmdlet uses the credentials of the current user to access the proxy server that -is specified by the **Proxy** parameter. +Uses the credentials of the current user to access the proxy server that is specified by the +**Proxy** parameter. This parameter is valid only when the **Proxy** parameter is also used in the command. You can't use the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command. @@ -1064,22 +1058,22 @@ requires the **OutFile** parameter. **Resume** only operates on the size of the local file and remote file and performs no other validation that the local file and the remote file are the same. -If the local file size is smaller than the remote file size, then the cmdlet will attempt to resume +If the local file size is smaller than the remote file size, then the cmdlet attempts to resume downloading the file and append the remaining bytes to the end of the file. If the local file size is the same as the remote file size, then no action is taken and the cmdlet assumes the download already completed. -If the local file size is larger than the remote file size, then the local file will be overwritten -and the entire remote file will be completely re-downloaded. This behavior is the same as using -**OutFile** without **Resume**. +If the local file size is larger than the remote file size, then the local file is overwritten and +the entire remote file is re-downloaded. This behavior is the same as using **OutFile** without +**Resume**. -If the remote server does not support download resuming, then the local file will be overwritten and -the entire remote file will be completely re-downloaded. This behavior is the same as using -**OutFile** without **Resume**. +If the remote server doesn't support download resuming, then the local file is overwritten and the +entire remote file is re-downloaded. This behavior is the same as using **OutFile** without +**Resume**. -If the local file doesn't exist, then the local file will be created and the entire remote file will -be completely downloaded. This behavior is the same as using **OutFile** without **Resume**. +If the local file doesn't exist, then the local file is created and the entire remote file is +downloaded. This behavior is the same as using **OutFile** without **Resume**. This feature was added in PowerShell 6.1.0. @@ -1161,7 +1155,7 @@ Skips certificate validation checks that include all validations such as expirat trusted root authority, etc. > [!WARNING] -> Using this parameter is not secure and is not recommended. This switch is only intended to be used +> Using this parameter isn't secure and isn't recommended. This switch is only intended to be used > against known hosts using a self-signed certificate for testing purposes. Use at your own risk. This feature was added in PowerShell 6.0.0. @@ -1182,11 +1176,11 @@ Accept wildcard characters: False Indicates the cmdlet should add headers to the request without validation. -This switch should be used for sites that require header values that do not conform to standards. +This switch should be used for sites that require header values that don't conform to standards. Specifying this switch disables validation to allow the value to be passed unchecked. When specified, all headers are added without validation. -This will disable validation for values passed to the **ContentType**, **Headers**, and +This switch disables validation for values passed to the **ContentType**, **Headers**, and **UserAgent** parameters. This feature was added in PowerShell 6.0.0. @@ -1230,17 +1224,11 @@ protocols for compliance purposes. These values are defined as a flag-based enumeration. You can combine multiple values together to set multiple flags using this parameter. The values can be passed to the **SslProtocol** parameter -as an array of values or as a comma-separated string of those values. The cmdlet will combine the -values using a binary-OR operation. Passing values as an array is the simplest option and also -allows you to use tab-completion on the values. You may not be able to supply multiple values on all -platforms. - -> [!NOTE] -> On non-Windows platforms it may not be possible to supply `Tls` or `Tls12` as an option. Support -> for `Tls13` is not available on all operating systems and will need to be verified on a per -> operating system basis. +as an array of values or as a comma-separated string of those values. The cmdlet combines the values +using a binary-OR operation. Passing values as an array is the simplest option and also allows you +to use tab-completion on the values. You may not be able to supply multiple values on all platforms. -This feature was added in PowerShell 6.0.0 and support for `Tls13` was added in PowerShell 7.1. +This feature was added in PowerShell 6.0.0. Support for `Tls13` was added in PowerShell 7.1. ```yaml Type: Microsoft.PowerShell.Commands.WebSslProtocol @@ -1372,8 +1360,8 @@ Accept wildcard characters: False ### -UseBasicParsing This parameter has been deprecated. Beginning with PowerShell 6.0.0, all Web requests use basic -parsing only. This parameter is included for backwards compatibility only and any use of it will -have no effect on the operation of the cmdlet. +parsing only. This parameter is included for backwards compatibility only. When used, it has no +effect on the operation of the cmdlet. ```yaml Type: System.Management.Automation.SwitchParameter @@ -1412,9 +1400,9 @@ The default user agent is similar to `Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0` with slight variations for each operating system and platform. -To test a website with the standard user agent string that is used by most internet browsers, use -the properties of the [PSUserAgent](/dotnet/api/microsoft.powershell.commands.psuseragent) class, -such as Chrome, Firefox, InternetExplorer, Opera, and Safari. +To test a website with the standard user agent string that's used by most internet browsers, use +the properties of the [PSUserAgent](xref:Microsoft.PowerShell.Commands.PSUserAgent) class, such as +Chrome, Firefox, InternetExplorer, Opera, and Safari. ```yaml Type: System.String @@ -1434,8 +1422,8 @@ Specifies a web request session. Enter the variable name, including the dollar s To override a value in the web request session, use a cmdlet parameter, such as **UserAgent** or **Credential**. Parameter values take precedence over values in the web request session. Content -related headers, such as `Content-Type`, will be also be overridden when a -**MultipartFormDataContent** object is supplied for **Body**. +related headers, such as `Content-Type`, are overridden when a **MultipartFormDataContent** object +is supplied for **Body**. Unlike a remote session, the web request session isn't a persistent connection. It's an object that contains information about the connection and the request, including cookies, credentials, the @@ -1502,16 +1490,16 @@ PowerShell includes the following aliases for `Invoke-RestMethod`: Some features may not be available on all platforms. Because of changes in .NET Core 3.1, PowerShell 7.0 and higher use the -[HttpClient.DefaultProxy](xref:System.Net.Http.HttpClient.DefaultProxy*) -property to determine the proxy configuration. +[HttpClient.DefaultProxy](xref:System.Net.Http.HttpClient.DefaultProxy*) property to determine the +proxy configuration. -The value of this property is different rules depending on your platform: +The value of this property differ depending on your platform: -- **For Windows**: Reads proxy configuration from environment variables or, if those are not - defined, from the user's proxy settings. -- **For macOS**: Reads proxy configuration from environment variables or, if those are not defined, +- **For Windows**: Reads proxy configuration from environment variables or, if those aren't defined, + from the user's proxy settings. +- **For macOS**: Reads proxy configuration from environment variables or, if those aren't defined, from the system's proxy settings. -- **For Linux**: Reads proxy configuration from environment variables or, in case those are not +- **For Linux**: Reads proxy configuration from environment variables or, in case those aren't defined, this property initializes a non-configured instance that bypasses all addresses. The environment variables used for `DefaultProxy` initialization on Windows and Unix-based platforms @@ -1520,7 +1508,7 @@ are: - `HTTP_PROXY`: the hostname or IP address of the proxy server used on HTTP requests. - `HTTPS_PROXY`: the hostname or IP address of the proxy server used on HTTPS requests. - `ALL_PROXY`: the hostname or IP address of the proxy server used on HTTP and HTTPS requests in - case `HTTP_PROXY` or `HTTPS_PROXY` are not defined. + case `HTTP_PROXY` or `HTTPS_PROXY` aren't defined. - `NO_PROXY`: a comma-separated list of hostnames that should be excluded from proxying. PowerShell 7.4 added support for the Brotli compression algorithm.