From 26458f5234826337667071271734dcf27aa5368e Mon Sep 17 00:00:00 2001 From: StephenRoille Date: Mon, 16 May 2022 15:41:31 +0200 Subject: [PATCH 1/6] Improve section on `Where` method in `about_Arrays.md` (#8816) Add clarity to the `"SkipUntil"` `mode`: - Mention that the first item for which the condition is met is also included in the result - Emphasize that ALL remaining items are returned regardless of the expression in the `Where` clause - Drop mistyped word *the* (presumably *then*), since it is clear from the context Co-authored-by: Stephen Roille --- reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md | 4 ++-- reference/7.0/Microsoft.PowerShell.Core/About/about_Arrays.md | 4 ++-- reference/7.1/Microsoft.PowerShell.Core/About/about_Arrays.md | 4 ++-- reference/7.2/Microsoft.PowerShell.Core/About/about_Arrays.md | 4 ++-- reference/7.3/Microsoft.PowerShell.Core/About/about_Arrays.md | 4 ++-- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md index 65347dc40f67..58a1475e26fb 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -627,8 +627,8 @@ The acceptable values for `mode` are: - Default (0) - Return all items - First (1) - Return the first item - Last (2) - Return the last item -- SkipUntil (3) - Skip items until condition is true, the return the remaining - items +- SkipUntil (3) - Skip items until condition is true, return all the remaining + items (including the first item for which the condition is true) - Until (4) - Return all items until condition is true - Split (5) - Return an array of two elements - The first element contains matching items diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Arrays.md index b47449328ae5..1254312dbf3d 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -627,8 +627,8 @@ The acceptable values for `mode` are: - Default (0) - Return all items - First (1) - Return the first item - Last (2) - Return the last item -- SkipUntil (3) - Skip items until condition is true, the return the remaining - items +- SkipUntil (3) - Skip items until condition is true, return all the remaining + items (including the first item for which the condition is true) - Until (4) - Return all items until condition is true - Split (5) - Return an array of two elements - The first element contains matching items diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Arrays.md index 999ca024fa14..23de4cb65581 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -627,8 +627,8 @@ The acceptable values for `mode` are: - Default (0) - Return all items - First (1) - Return the first item - Last (2) - Return the last item -- SkipUntil (3) - Skip items until condition is true, the return the remaining - items +- SkipUntil (3) - Skip items until condition is true, return all the remaining + items (including the first item for which the condition is true) - Until (4) - Return all items until condition is true - Split (5) - Return an array of two elements - The first element contains matching items diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Arrays.md index 711a7db7b2f0..1895b73b3e1a 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -627,8 +627,8 @@ The acceptable values for `mode` are: - Default (0) - Return all items - First (1) - Return the first item - Last (2) - Return the last item -- SkipUntil (3) - Skip items until condition is true, the return the remaining - items +- SkipUntil (3) - Skip items until condition is true, return all the remaining + items (including the first item for which the condition is true) - Until (4) - Return all items until condition is true - Split (5) - Return an array of two elements - The first element contains matching items diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Arrays.md index 461d27021dee..38c0a8d372fe 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -627,8 +627,8 @@ The acceptable values for `mode` are: - Default (0) - Return all items - First (1) - Return the first item - Last (2) - Return the last item -- SkipUntil (3) - Skip items until condition is true, the return the remaining - items +- SkipUntil (3) - Skip items until condition is true, return all the remaining + items (including the first item for which the condition is true) - Until (4) - Return all items until condition is true - Split (5) - Return an array of two elements - The first element contains matching items From 2ba2e7e0fb24ce11d550ff4ab3b6f0bf71acc5f7 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 16 May 2022 15:01:51 -0500 Subject: [PATCH 2/6] Update differences rollup to include 7.x change (#8818) * Initial updates * Update differences rollup to include 7.x change * fix include link * Add notes about new cmdlets * Apply suggestions from code review Co-authored-by: Mikey Lombardi (He/Him) * Minor feedback edits Co-authored-by: Mikey Lombardi (He/Him) --- .../differences-from-windows-powershell.md | 395 ++++++++++++++++-- 1 file changed, 352 insertions(+), 43 deletions(-) diff --git a/reference/docs-conceptual/whats-new/differences-from-windows-powershell.md b/reference/docs-conceptual/whats-new/differences-from-windows-powershell.md index 458671e03151..f193a6681d9c 100644 --- a/reference/docs-conceptual/whats-new/differences-from-windows-powershell.md +++ b/reference/docs-conceptual/whats-new/differences-from-windows-powershell.md @@ -1,18 +1,17 @@ --- -ms.date: 09/17/2021 +ms.date: 05/16/2022 title: Differences between Windows PowerShell 5.1 and PowerShell 7.x description: This article summarizes the differences and breaking changes from Windows PowerShell 5.1 and the current version of PowerShell that is based on .NET Core. --- # Differences between Windows PowerShell 5.1 and PowerShell 7.x Windows PowerShell 5.1 is built on top of the .NET Framework v4.5. With the release of PowerShell -6.0, PowerShell became an open source project built on .NET Core 2.0. PowerShell 7.0 is built on -.NET Core 3.1. And, with the release of PowerShell 7.2, PowerShell will be built on .NET 6.0. Moving -from the .NET Framework to .NET Core allowed PowerShell to become a cross-platform solution. -PowerShell runs on Windows, macOS, and Linux. +6.0, PowerShell became an open source project built on .NET Core 2.0. Moving from the .NET Framework +to .NET Core allowed PowerShell to become a cross-platform solution. PowerShell runs on Windows, +macOS, and Linux. There are few differences in the PowerShell language between Windows PowerShell and PowerShell. The -differences are most notable in the availability and behavior of PowerShell cmdlets between Windows +most notable differences are in the availability and behavior of PowerShell cmdlets between Windows and non-Windows platforms and the changes that stem from the differences between the .NET Framework and .NET Core. @@ -23,20 +22,20 @@ article is to present the current state of PowerShell and how that is different PowerShell. For a detailed discussion of changes between versions and the addition of new features, see the **What's New** articles for each version. -- [What's new in PowerShell 7.3](What-s-New-in-PowerShell-73.md) -- [What's new in PowerShell 7.2](What-s-New-in-PowerShell-72.md) -- [What's new in PowerShell 7.1](What-s-New-in-PowerShell-71.md) -- [What's new in PowerShell 7.0](What-s-New-in-PowerShell-70.md) -- [What's new in PowerShell 6.x](/previous-versions/powershell/scripting/whats-new/what-s-new-in-powershell-core-62?view=powershell-6&preserve-view=true) +- [What's new in PowerShell 7.3][WhatsNew73] +- [What's new in PowerShell 7.2][WhatsNew72] +- [What's new in PowerShell 7.1][WhatsNew71] +- [What's new in PowerShell 7.0][WhatsNew70] +- [What's new in PowerShell 6.x][WhatsNew6x] ## .NET Framework vs .NET Core -PowerShell on Linux and macOS uses .NET Core, which is a subset of the full .NET Framework on +PowerShell on Linux and macOS uses .NET core, which is a subset of the full .NET Framework on Microsoft Windows. This is significant because PowerShell provides direct access to the underlying framework types and methods. As a result, scripts that run on Windows may not run on non-Windows platforms because of the differences in the frameworks. For more information about changes in .NET Core, see -[Breaking changes for migration from .NET Framework to .NET Core](/dotnet/core/compatibility/fx-core). +[Breaking changes for migration from .NET Framework to .NET Core][fxcore]. Each new release of PowerShell is built on a newer version of .NET. There can be breaking changes in .NET that affect PowerShell. @@ -49,16 +48,15 @@ Each new release of PowerShell is built on a newer version of .NET. There can be - PowerShell 6.1 - Built on .NET Core 2.1 - PowerShell 6.0 - Built on .NET Core 2.0 -With the advent of -[.NET Standard 2.0](https://devblogs.microsoft.com/dotnet/introducing-net-standard/), PowerShell can -load many traditional Windows PowerShell modules without modification. Additionally, PowerShell 7 -includes a Windows PowerShell Compatibility feature that allows you to use Windows PowerShell -modules that still require the full framework. +With the advent of [.NET Standard 2.0][NETStd2], PowerShell can load many traditional Windows +PowerShell modules without modification. Additionally, PowerShell 7 includes a Windows PowerShell +Compatibility feature that allows you to use Windows PowerShell modules that still require the full +framework. For more information see: -- [about_Windows_PowerShell_Compatibility](/powershell/module/microsoft.powershell.core/about/about_windows_powershell_compatibility) -- [PowerShell 7 module compatibility](module-compatibility.md) +- [about_Windows_PowerShell_Compatibility][about-WinCompat] +- [PowerShell 7 module compatibility][mod-compat] [!INCLUDE [Product terminology](../../includes/product-terms.md)] @@ -90,9 +88,6 @@ If there is a need to use checkpoints to resume a script after the OS restarts, using Task Scheduler to run a script on OS startup, but the script would need to maintain its own state (like persisting it to a file). -[workflow]: /previous-versions/powershell/scripting/components/workflows-guide -[workflow-foundation]: /dotnet/framework/windows-workflow-foundation/ - ## Cmdlets removed from PowerShell For the modules that are included in PowerShell, the following cmdlets were removed from PowerShell @@ -217,10 +212,9 @@ Windows-specific features: Beginning with PowerShell 7.2, the PSDesiredStateConfiguration module has been removed from PowerShell and has been published to the PowerShell Gallery. For more information, see the -[announcement](https://devblogs.microsoft.com/powershell/announcing-psdesiredstateconfiguration-on-powershell-gallery/) -in the PowerShell Team blog. +[announcement][PSDSC-announce] in the PowerShell Team blog. -## Engine/language changes +## PowerShell executable changes ### Renamed `powershell.exe` to `pwsh.exe` @@ -252,6 +246,33 @@ Previously, using `pwsh.exe` to execute a PowerShell script using `-File` provid `$true`/`$false` as parameter values. Support for `$true`/`$false` as parsed values to parameters was added. Switch values are also supported. +## Improved backwards compatibility with Windows PowerShell + +For Windows, a new switch parameter **UseWindowsPowerShell** is added to `Import-Module`. This +switch creates a proxy module in PowerShell 7 that uses a local Windows PowerShell process to +implicitly run any cmdlets contained in that module. For more information, see +[Import-Module][Import-Module]. + +For more information on which Microsoft modules work with PowerShell 7.0, see the +[Module Compatibility Table][mod-compat]. + +### Microsoft Update support for Windows + +PowerShell 7.2 added support for Microsoft Update. When you enable this feature, you'll get the latest +PowerShell 7 updates in your traditional Windows Update (WU) management flow, whether that's with +Windows Update for Business, WSUS, SCCM, or the interactive WU dialog in Settings. + +The PowerShell 7.2 MSI package includes following command-line options: + +- `USE_MU` - This property has two possible values: + - `1` (default) - Opts into updating through Microsoft Update or WSUS + - `0` - Do not opt into updating through Microsoft Update or WSUS +- `ENABLE_MU` + - `1` (default) - Opts into using Microsoft Update the Automatic Updates or Windows Update + - `0` - Do not opt into using Microsoft Update the Automatic Updates or Windows Update + +## Engine changes + ### Support PowerShell as a default Unix shell On Unix, it is a convention for shells to accept `-i` for an interactive shell and many tools @@ -267,19 +288,15 @@ adoption in the PowerShell community. Due to the complexity of supporting snap-ins and their lack of usage in the community, we no longer support custom snap-ins in PowerShell. -[snapin]: /powershell/module/microsoft.powershell.core/about/about_pssnapins - ### Experimental feature flags -We enabled support for [Experimental Features][exp]. This allows PowerShell developers to deliver -new features and get feedback before the design is complete. This way we avoid making breaking -changes as the design evolves. +PowerShell 6.2 enabled support for [Experimental Features][exp]. This allows PowerShell developers +to deliver new features and get feedback before the design is complete. This way we avoid making +breaking changes as the design evolves. Use `Get-ExperimentalFeature` to get a list of available experimental features. You can enable or disable these features with `Enable-ExperimentalFeature` and `Disable-ExperimentalFeature`. -[exp]: /powershell/module/Microsoft.PowerShell.Core/About/about_Experimental_Features - ### Load assembly from module base path before trying to load from the GAC Previously, when a binary module has the module assembly in GAC, we loaded the assembly from GAC @@ -382,6 +399,119 @@ PS> SimpleTest @hash "MyPath" Name: Hello; Path: MyPath; Args: -Blah: World ``` +## Language changes + +### Null-coalescing operator `??` + +The null-coalescing operator `??` returns the value of its left-hand operand if +it isn't null. Otherwise, it evaluates the right-hand operand and returns its +result. The `??` operator doesn't evaluate its right-hand operand if the +left-hand operand evaluates to non-null. + +```powershell +$x = $null +$x ?? 100 +``` + +```Output +100 +``` + +In the following example, the right-hand operand won't be evaluated. + +```powershell +[string] $todaysDate = '1/10/2020' +$todaysDate ?? (Get-Date).ToShortDateString() +``` + +```Output +1/10/2020 +``` + +### Null-coalescing assignment operator `??=` + +The null-coalescing assignment operator `??=` assigns the value of its +right-hand operand to its left-hand operand only if the left-hand operand +evaluates to null. The `??=` operator doesn't evaluate its right-hand operand +if the left-hand operand evaluates to non-null. + +```powershell +$x = $null +$x ??= 100 +$x +``` + +```Output +100 +``` + +In the following example, the right-hand operand won't be evaluated. + +```powershell +[string] $todaysDate = '1/10/2020' +$todaysDate ??= (Get-Date).ToShortDateString() +``` + +```Output +1/10/2020 +``` + +### Null-conditional operators + +> [!NOTE] +> This feature was moved from experimental to mainstream in PowerShell 7.1. + +A null-conditional operator applies a member access, `?.`, or element access, +`?[]`, operation to its operand only if that operand evaluates to non-null; +otherwise, it returns null. + +Since PowerShell allows `?` to be part of the variable name, formal +specification of the variable name is required for using these operators. So it +is required to use `{}` around the variable names like `${a}` or when `?` is +part of the variable name `${a?}`. + +In the following example, the value of **PropName** is returned. + +```powershell +$a = @{ PropName = 100 } +${a}?.PropName +``` + +```Output +100 +``` + +The following example will return null, without trying to access the member +name **PropName**. + +```powershell +$a = $null +${a}?.PropName +``` + +Similarly, the value of the element will be returned. + +```powershell +$a = 1..10 +${a}?[0] +``` + +```Output +1 +``` + +And when the operand is null, the element isn't accessed and null is returned. + +```PowerShell +$a = $null +${a}?[0] +``` + +> [!NOTE] +> The variable name syntax of `${}` should not be confused with the `$()` +> subexpression operator. For more information, see Variable name section of +> [about_Variables][about_Variables]. + ### Added `&` operator for job control Putting `&` at the end of a pipeline causes the pipeline to be run as a PowerShell job. When a @@ -459,7 +589,7 @@ class M { PowerShell 7.1 is built on .NET 5.0, which introduced the following breaking change: -- [Behavior changes when comparing strings on .NET 5+](/dotnet/standard/base-types/string-comparison-net-5-plus) +- [Behavior changes when comparing strings on .NET 5+][NET5-strings] As of .NET 5.0, culture invariant string comparisons ignore non-printing control characters. @@ -474,8 +604,147 @@ For example, the following two strings are considered to be identical: True ``` +## New cmdlets + +### New Get-Uptime cmdlet + +The [Get-Uptime][Get-Uptime] cmdlet returns the time elapsed since the last boot of the operating +system. The cmdlet was introduced in PowerShell 6.0. + +### New Remove-Alias cmdlet + +The [Remove-Alias][Remove-Alias] cmdlet removes an alias from the current PowerShell session. The +cmdlet was introduced in PowerShell 6.0. + +### New cmdlet Remove-Service + +The [Remove-Service][Remove-Service] cmdlet removes a Windows service in the registry and in the service database. +The `Remove-Service` cmdlet was introduced in PowerShell 6.0. + +### New Markdown cmdlets + +Markdown is a standard for creating readable plaintext documents with basic formatting that can be +rendered into HTML. + +The following cmdlets were added in PowerShell 6.1: + +- [ConvertFrom-Markdown][ConvertFrom-Markdown] - Convert the contents of a string or a file to a + **MarkdownInfo** object. +- [Get-MarkdownOption][Get-MarkdownOption] - Returns the current colors and styles used for + rendering Markdown content in the console. +- [Set-MarkdownOption][Set-MarkdownOption] - Sets the colors and styles used for rendering Markdown + content in the console. +- [Show-Markdown][Show-Markdown] - Displays Markdown content in the console or as HTML + +### New Test-Json cmdlet + +The [Test-Json][Test-Json] cmdlet tests whether a string is a valid JavaScript Object Notation (JSON) document +and can optionally verify that JSON document against a provided schema. + +This cmdlet was introduced in PowerShell 6.1 + +### New cmdlets to support Experimental Features + +The following cmdlets were added in PowerShell 6.2 to support Experimental Features. + +- [Disable-ExperimentalFeature][Disable-ExperimentalFeature] +- [Enable-ExperimentalFeature][Enable-ExperimentalFeature] +- [Get-ExperimentalFeature][Get-ExperimentalFeature] + +### New Join-String cmdlet + +The [Join-String][Join-String] cmdlet combines objects from the pipeline into a single string. This cmdlet was +added in PowerShell 6.2. + +### New view ConciseView and cmdlet Get-Error + +PowerShell 7.0 enhances the display of error messages to improve the readability of interactive and +script errors with a new default view, **ConciseView**. The views are user-selectable through the +preference variable `$ErrorView`. + +With **ConciseView**, if an error is not from a script or parser error, then it's a single line +error message: + +```powershell +Get-Childitem -Path c:\NotReal +``` + +```Output +Get-ChildItem: Cannot find path 'C:\NotReal' because it does not exist +``` + +If the error occurs during script execution or is a parsing error, PowerShell returns a multiline +error message that contains the error, a pointer, and an error message showing where the error is in +that line. If the terminal doesn't support ANSI color escape sequences (VT100), then colors are not +displayed. + +The default view in PowerShell 7 is **ConciseView**. The previous default view was **NormalView** +and you can select this by setting the preference variable `$ErrorView`. + +```powershell +$ErrorView = 'NormalView' # Sets the error view to NormalView +$ErrorView = 'ConciseView' # Sets the error view to ConciseView +``` + +> [!NOTE] +> A new property **ErrorAccentColor** is added to `$Host.PrivateData` to support changing +> the accent color of the error message. + +The new `Get-Error`cmdlet provides a complete detailed view of the fully qualified error when +desired. By default the cmdlet displays the full details, including inner exceptions, of the last +error that occurred. + +The `Get-Error` cmdlet supports input from the pipeline using the built-in variable `$Error`. +`Get-Error` displays all piped errors. + +```powershell +$Error | Get-Error +``` + +The `Get-Error` cmdlet supports the **Newest** parameter, allowing you to specify how many errors +from the current session you wish displayed. + +```powershell +Get-Error -Newest 3 # Displays the lst three errors that occurred in the session +``` + +For more information, see [Get-Error][Get-Error]. + ## Cmdlet changes +### Parallel execution added to ForEach-Object + +Beginning in PowerShell 7.0, the `ForEach-Object` cmdlet, which iterates items in a collection, now +has built-in parallelism with the new **Parallel** parameter. + +By default, parallel script blocks use the current working directory of the caller that started the +parallel tasks. + +This example retrieves 50,000 log entries from 5 system logs on a local Windows machine: + +```powershell +$logNames = 'Security','Application','System','Windows PowerShell','Microsoft-Windows-Store/Operational' + +$logEntries = $logNames | ForEach-Object -Parallel { + Get-WinEvent -LogName $_ -MaxEvents 10000 +} -ThrottleLimit 5 + +$logEntries.Count + +50000 +``` + +The **Parallel** parameter specifies the script block that is run in parallel for each input log +name. + +The new **ThrottleLimit** parameter limits the number of script blocks running in parallel at a +given time. The default is 5. + +Use the `$_` variable to represent the current input object in the script block. Use the +`$using:` scope to pass variable references to the running script block. + +For more information, see [ForEach-Object][ForEach-Object]. + ### Check `system32` for compatible built-in modules on Windows In the Windows 10 1809 update and Windows Server 2019, we updated a number of built-in PowerShell @@ -712,8 +981,13 @@ valid single value JSON `null` literal as `$null`. ### Web Cmdlets warn when `-Credential` is sent over unencrypted connections When using HTTP, content including passwords are sent as clear-text. This change is to not allow -this by default and return an error if credentials are being passed in an insecure manner. Users -can bypass this by using the `-AllowUnencryptedAuthentication` switch. +this by default and return an error if credentials are being passed insecurely. Users can bypass +this by using the `-AllowUnencryptedAuthentication` switch. + +### Make `-OutFile` parameter in web cmdlets to work like `-LiteralPath` + +Beginning in PowerShell 7.1, the **OutFile** parameter of the web cmdlets works like **LiteralPath** +and does not process wildcards. ## API changes @@ -733,9 +1007,6 @@ Previously, when creating a PowerShell runspace programmatically using the API, legacy [`RunspaceConfiguration`][runspaceconfig] or the newer [`InitialSessionState`][iss] classes. This change removed support for `RunspaceConfiguration` and only supports `InitialSessionState`. -[runspaceconfig]: /dotnet/api/system.management.automation.runspaces.runspaceconfiguration -[iss]: /dotnet/api/system.management.automation.runspaces.initialsessionstate - ### `CommandInvocationIntrinsics.InvokeScript` bind arguments to `$input` instead of `$args` An incorrect position of a parameter resulted in the args passed as input instead of as args. @@ -794,13 +1065,12 @@ supported for non-Windows platforms. PowerShell also supports PowerShell Remoting (PSRP) over SSH on all platforms (Windows, macOS, and Linux). For more information, see -[SSH remoting in PowerShell](/powershell/scripting/learn/remoting/SSH-Remoting-in-PowerShell-Core). +[SSH remoting in PowerShell][ssh-remote]. ### PowerShell Direct for Containers tries to use `pwsh` first -[PowerShell Direct](/virtualization/hyper-v-on-windows/user-guide/powershell-direct) is a feature of -PowerShell and Hyper-V that allows you to connect to a Hyper-V VM or Container without network -connectivity or other remote management services. +[PowerShell Direct][psdirect] is a feature of PowerShell and Hyper-V that allows you to connect to a +Hyper-V VM or Container without network connectivity or other remote management services. In the past, PowerShell Direct connected using the built-in Windows PowerShell instance on the Container. Now, PowerShell Direct first attempts to connect using any available `pwsh.exe` on the @@ -882,3 +1152,42 @@ where PowerShell is used and enables us to prioritize new features and fixes. To opt-out of this telemetry, set the environment variable `POWERSHELL_TELEMETRY_OPTOUT` to `true`, `yes`, or `1`. We no longer support deletion of the file `DELETE_ME_TO_DISABLE_CONSOLEHOST_TELEMETRY` to disable telemetry. + + +[workflow]: /previous-versions/powershell/scripting/components/workflows-guide +[workflow-foundation]: /dotnet/framework/windows-workflow-foundation/ +[NETStd2]: https://devblogs.microsoft.com/dotnet/introducing-net-standard/ +[about-WinCompat]: /powershell/module/microsoft.powershell.core/about/about_windows_powershell_compatibility +[mod-compat]: https://aka.ms/PSModuleCompat +[WhatsNew73]: What-s-New-in-PowerShell-73.md +[WhatsNew72]: What-s-New-in-PowerShell-72.md +[WhatsNew71]: What-s-New-in-PowerShell-71.md +[WhatsNew70]: What-s-New-in-PowerShell-70.md +[WhatsNew6x]: /previous-versions/powershell/scripting/whats-new/what-s-new-in-powershell-core-62?view=powershell-6&preserve-view=true +[fxcore]: /dotnet/core/compatibility/fx-core +[PSDSC-annouce]: https://devblogs.microsoft.com/powershell/announcing-psdesiredstateconfiguration-on-powershell-gallery/ +[Module Compatibility Table]: https://aka.ms/PSModuleCompat +[NET5-strings]: /dotnet/standard/base-types/string-comparison-net-5-plus +[ssh-remote]: /powershell/scripting/learn/remoting/SSH-Remoting-in-PowerShell-Core +[PowerShell Direct]: /virtualization/hyper-v-on-windows/user-guide/powershell-direct +[runspaceconfig]: /dotnet/api/system.management.automation.runspaces.runspaceconfiguration +[iss]: /dotnet/api/system.management.automation.runspaces.initialsessionstate +[snapin]: /powershell/module/microsoft.powershell.core/about/about_pssnapins +[exp]: /powershell/module/Microsoft.PowerShell.Core/About/about_Experimental_Features +[Disable-ExperimentalFeature]: /powershell/module/Microsoft.PowerShell.Core/Disable-ExperimentalFeature +[Enable-ExperimentalFeature]: /powershell/module/Microsoft.PowerShell.Core/Enable-ExperimentalFeature +[Get-ExperimentalFeature]: /powershell/module/Microsoft.PowerShell.Core/Get-ExperimentalFeature +[Remove-Service]: /powershell/module/Microsoft.PowerShell.Management/Remove-Service +[ConvertFrom-Markdown]: /powershell/module/Microsoft.PowerShell.Utility/ConvertFrom-Markdown +[Get-MarkdownOption]: /powershell/module/Microsoft.PowerShell.Utility/Get-MarkdownOption +[Set-MarkdownOption]: /powershell/module/Microsoft.PowerShell.Utility/Set-MarkdownOption +[Show-Markdown]: /powershell/module/Microsoft.PowerShell.Utility/Show-Markdown +[Remove-Alias]: /powershell/module/Microsoft.PowerShell.Utility/Remote-Alias +[Remove-Service]: /powershell/module/Microsoft.PowerShell.Utility/Remote-Service +[Join-String]: /powershell/module/Microsoft.PowerShell.Utility/Join-String +[Get-Uptime]: /powershell/module/Microsoft.PowerShell.Utility/Get-Uptime +[Test-Json]: /powershell/module/Microsoft.PowerShell.Utility/Test-Json +[Get-Error]: /powershell/module/microsoft.powershell.utility/get-error +[ForEach-Object]: /powershell/module/microsoft.powershell.core/foreach-object +[Import-Module]: /powershell/module/microsoft.powershell.core/import-module +[about_Variables]: /powershell/module/microsoft.powershell.core/about/about_Variables#variable-names-that-include-special-characters From 296cda0ec0eba05ef766c5b4013cc849024637c7 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 16 May 2022 16:13:36 -0500 Subject: [PATCH 3/6] Add info about end-of-parameters token (#8819) --- .../About/about_Parsing.md | 24 +++++++++++++--- .../About/about_Special_Characters.md | 28 +++++++++++++++---- .../About/about_Parsing.md | 24 +++++++++++++--- .../About/about_Special_Characters.md | 28 +++++++++++++++---- .../About/about_Parsing.md | 24 +++++++++++++--- .../About/about_Special_Characters.md | 28 +++++++++++++++---- .../About/about_Parsing.md | 24 +++++++++++++--- .../About/about_Special_Characters.md | 28 +++++++++++++++---- .../About/about_Parsing.md | 24 +++++++++++++--- .../About/about_Special_Characters.md | 28 +++++++++++++++---- .../docs-conceptual/lang-spec/chapter-08.md | 5 +--- 11 files changed, 216 insertions(+), 49 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md index 03047a9323f1..3119abda88fe 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell parses commands. Locale: en-US -ms.date: 09/07/2021 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Parsing @@ -200,10 +200,11 @@ prevent PowerShell from misinterpreting the parentheses. icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ``` -### The stop-parsing token +### The stop-parsing and end-of-parameters tokens -Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to -stop PowerShell from interpreting input as PowerShell commands or expressions. +Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) and +_end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as +PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. @@ -238,6 +239,21 @@ variable the token is passed through as-is. You cannot use stream redirection (like `>file.txt`) because they are passed verbatim as arguments to the target command. +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +This is a convention specified in the POSIX Shell and Utilities specification. + ### Passing arguments that contain quote characters Some native commands expect arguments that contain quote characters. Normally, diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md index 65d6cc82e7d9..53e48d2fccdc 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md @@ -1,7 +1,7 @@ --- description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence. Locale: en-US -ms.date: 02/08/2021 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Special Characters @@ -44,11 +44,12 @@ PowerShell also has a special token to mark where you want parsing to stop. All characters that follow this token are used as literal values that aren't interpreted. -Special parsing token: +Special parsing tokens: -| Sequence | Description | -| -------- | ---------------------------------- | -| `--%` | Stop parsing anything that follows | +| Sequence | Description | +| -------- | ------------------------------------------------------ | +| `--` | Treat the remaining values as arguments not parameters | +| `--%` | Stop parsing anything that follows | ## Null (`0) @@ -180,6 +181,23 @@ There is a vertical tab between the words. ``` +## The end-of-parameters token (`--`) + +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +This is a convention specified in the POSIX Shell and Utilities specification. + ## Stop-parsing token (--%) The stop-parsing (`--%`) token prevents PowerShell from interpreting strings as diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md index f5f5b90640ec..b2449f369041 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell parses commands. Locale: en-US -ms.date: 09/07/2021 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Parsing @@ -200,10 +200,11 @@ prevent PowerShell from misinterpreting the parentheses. icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ``` -### The stop-parsing token +### The stop-parsing and end-of-parameters tokens -Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to -stop PowerShell from interpreting input as PowerShell commands or expressions. +Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) and +_end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as +PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. @@ -238,6 +239,21 @@ variable the token is passed through as-is. You cannot use stream redirection (like `>file.txt`) because they are passed verbatim as arguments to the target command. +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +This is a convention specified in the POSIX Shell and Utilities specification. + ### Passing arguments that contain quote characters Some native commands expect arguments that contain quote characters. Normally, diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Special_Characters.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Special_Characters.md index d49763142d6b..8aa79d027cff 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Special_Characters.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Special_Characters.md @@ -1,7 +1,7 @@ --- description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence. Locale: en-US -ms.date: 02/08/2021 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Special Characters @@ -46,11 +46,12 @@ PowerShell also has a special token to mark where you want parsing to stop. All characters that follow this token are used as literal values that aren't interpreted. -Special parsing token: +Special parsing tokens: -| Sequence | Description | -| -------- | ---------------------------------- | -| `--%` | Stop parsing anything that follows | +| Sequence | Description | +| -------- | ------------------------------------------------------ | +| `--` | Treat the remaining values as arguments not parameters | +| `--%` | Stop parsing anything that follows | ## Null (`0) @@ -222,6 +223,23 @@ There is a vertical tab between the words. ``` +## The end-of-parameters token (`--`) + +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +This is a convention specified in the POSIX Shell and Utilities specification. + ## Stop-parsing token (--%) The stop-parsing (`--%`) token prevents PowerShell from interpreting strings as diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md index c156f5a77be0..9f780839b2e6 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell parses commands. Locale: en-US -ms.date: 09/07/2021 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Parsing @@ -200,10 +200,11 @@ prevent PowerShell from misinterpreting the parentheses. icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ``` -### The stop-parsing token +### The stop-parsing and end-of-parameters tokens -Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to -stop PowerShell from interpreting input as PowerShell commands or expressions. +Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) and +_end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as +PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. @@ -238,6 +239,21 @@ variable the token is passed through as-is. You cannot use stream redirection (like `>file.txt`) because they are passed verbatim as arguments to the target command. +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +This is a convention specified in the POSIX Shell and Utilities specification. + ### Passing arguments that contain quote characters Some native commands expect arguments that contain quote characters. Normally, diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md index edafa833f726..5990104ff9e5 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md @@ -1,7 +1,7 @@ --- description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence. Locale: en-US -ms.date: 02/08/2021 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Special Characters @@ -46,11 +46,12 @@ PowerShell also has a special token to mark where you want parsing to stop. All characters that follow this token are used as literal values that aren't interpreted. -Special parsing token: +Special parsing tokens: -| Sequence | Description | -| -------- | ---------------------------------- | -| `--%` | Stop parsing anything that follows | +| Sequence | Description | +| -------- | ------------------------------------------------------ | +| `--` | Treat the remaining values as arguments not parameters | +| `--%` | Stop parsing anything that follows | ## Null (`0) @@ -222,6 +223,23 @@ There is a vertical tab between the words. ``` +## The end-of-parameters token (`--`) + +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +This is a convention specified in the POSIX Shell and Utilities specification. + ## Stop-parsing token (--%) The stop-parsing (`--%`) token prevents PowerShell from interpreting strings as diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md index 2846e872be8e..6350a22a74d2 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell parses commands. Locale: en-US -ms.date: 09/07/2021 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Parsing @@ -200,10 +200,11 @@ prevent PowerShell from misinterpreting the parentheses. icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ``` -### The stop-parsing token +### The stop-parsing and end-of-parameters tokens -Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to -stop PowerShell from interpreting input as PowerShell commands or expressions. +Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) and +_end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as +PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. @@ -238,6 +239,21 @@ variable the token is passed through as-is. You cannot use stream redirection (like `>file.txt`) because they are passed verbatim as arguments to the target command. +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +This is a convention specified in the POSIX Shell and Utilities specification. + ### Passing arguments that contain quote characters Some native commands expect arguments that contain quote characters. Normally, diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Special_Characters.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Special_Characters.md index 23508280f94f..1570554a4bab 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Special_Characters.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Special_Characters.md @@ -1,7 +1,7 @@ --- description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence. Locale: en-US -ms.date: 02/08/2021 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Special Characters @@ -46,11 +46,12 @@ PowerShell also has a special token to mark where you want parsing to stop. All characters that follow this token are used as literal values that aren't interpreted. -Special parsing token: +Special parsing tokens: -| Sequence | Description | -| -------- | ---------------------------------- | -| `--%` | Stop parsing anything that follows | +| Sequence | Description | +| -------- | ------------------------------------------------------ | +| `--` | Treat the remaining values as arguments not parameters | +| `--%` | Stop parsing anything that follows | ## Null (`0) @@ -222,6 +223,23 @@ There is a vertical tab between the words. ``` +## The end-of-parameters token (`--`) + +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +This is a convention specified in the POSIX Shell and Utilities specification. + ## Stop-parsing token (--%) The stop-parsing (`--%`) token prevents PowerShell from interpreting strings as diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md index 25b8949adc33..f60dab6dafd3 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell parses commands. Locale: en-US -ms.date: 09/07/2021 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Parsing @@ -200,10 +200,11 @@ prevent PowerShell from misinterpreting the parentheses. icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ``` -### The stop-parsing token +### The stop-parsing and end-of-parameters tokens -Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to -stop PowerShell from interpreting input as PowerShell commands or expressions. +Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) and +_end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as +PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. @@ -238,6 +239,21 @@ variable the token is passed through as-is. You cannot use stream redirection (like `>file.txt`) because they are passed verbatim as arguments to the target command. +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +This is a convention specified in the POSIX Shell and Utilities specification. + ### Passing arguments that contain quote characters Some native commands expect arguments that contain quote characters. Normally, diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Special_Characters.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Special_Characters.md index 526136e2da37..4ae3705b38b7 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Special_Characters.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Special_Characters.md @@ -1,7 +1,7 @@ --- description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence. Locale: en-US -ms.date: 02/08/2021 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Special Characters @@ -46,11 +46,12 @@ PowerShell also has a special token to mark where you want parsing to stop. All characters that follow this token are used as literal values that aren't interpreted. -Special parsing token: +Special parsing tokens: -| Sequence | Description | -| -------- | ---------------------------------- | -| `--%` | Stop parsing anything that follows | +| Sequence | Description | +| -------- | ------------------------------------------------------ | +| `--` | Treat the remaining values as arguments not parameters | +| `--%` | Stop parsing anything that follows | ## Null (`0) @@ -222,6 +223,23 @@ There is a vertical tab between the words. ``` +## The end-of-parameters token (`--`) + +The end-of-parameters token (`--`) indicates that all arguments following it +are to be passed in their actual form as though double quotes were placed +around them. For example, using `--` you can output the string `-InputObject` +without using quotes or having it interpreted as a parameter: + +```powershell +Write-Output -- -InputObject +``` + +```Output +-InputObject +``` + +This is a convention specified in the POSIX Shell and Utilities specification. + ## Stop-parsing token (--%) The stop-parsing (`--%`) token prevents PowerShell from interpreting strings as diff --git a/reference/docs-conceptual/lang-spec/chapter-08.md b/reference/docs-conceptual/lang-spec/chapter-08.md index 33053f0ab521..d016a95c3ad9 100644 --- a/reference/docs-conceptual/lang-spec/chapter-08.md +++ b/reference/docs-conceptual/lang-spec/chapter-08.md @@ -1,6 +1,6 @@ --- description: A statement specifies some sort of action that is to be performed. -ms.date: 05/19/2021 +ms.date: 05/16/2022 title: Statements --- # 8. Statements @@ -238,9 +238,6 @@ governing arguments are as follows: - An argument of `--` indicates that all arguments following it are to be passed in their actual form as though double quotes were placed around them. - > [!NOTE] - > Editor's note: The `--` argument was never implemented. - - An argument of `--%` indicates that all arguments following it are to be passed with minimal parsing and processing. This argument is called the verbatim parameter. Arguments after the verbatim parameter are not PowerShell expressions even if they are syntactically valid PowerShell From c3b03065bfc1ff06e2d77ef437bf6f1bffd06248 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 16 May 2022 16:33:56 -0500 Subject: [PATCH 4/6] Fix broken bookmark (#8822) --- .../5.1/Microsoft.PowerShell.Core/About/about_Parsing.md | 6 ++++-- .../7.0/Microsoft.PowerShell.Core/About/about_Parsing.md | 6 ++++-- .../7.1/Microsoft.PowerShell.Core/About/about_Parsing.md | 6 ++++-- .../7.2/Microsoft.PowerShell.Core/About/about_Parsing.md | 6 ++++-- .../7.3/Microsoft.PowerShell.Core/About/about_Parsing.md | 6 ++++-- 5 files changed, 20 insertions(+), 10 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md index 3119abda88fe..4fd68546e9f2 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -200,8 +200,6 @@ prevent PowerShell from misinterpreting the parentheses. icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ``` -### The stop-parsing and end-of-parameters tokens - Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) and _end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as PowerShell commands or expressions. @@ -209,6 +207,8 @@ PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. +### The stop-parsing token + When calling a native command, place the stop-parsing token before the program arguments. This technique is much easier than using escape characters to prevent misinterpretation. @@ -239,6 +239,8 @@ variable the token is passed through as-is. You cannot use stream redirection (like `>file.txt`) because they are passed verbatim as arguments to the target command. +### The end-of-parameters token + The end-of-parameters token (`--`) indicates that all arguments following it are to be passed in their actual form as though double quotes were placed around them. For example, using `--` you can output the string `-InputObject` diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md index b2449f369041..c15fb9099f4b 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -200,8 +200,6 @@ prevent PowerShell from misinterpreting the parentheses. icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ``` -### The stop-parsing and end-of-parameters tokens - Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) and _end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as PowerShell commands or expressions. @@ -209,6 +207,8 @@ PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. +### The stop-parsing token + When calling a native command, place the stop-parsing token before the program arguments. This technique is much easier than using escape characters to prevent misinterpretation. @@ -239,6 +239,8 @@ variable the token is passed through as-is. You cannot use stream redirection (like `>file.txt`) because they are passed verbatim as arguments to the target command. +### The end-of-parameters token + The end-of-parameters token (`--`) indicates that all arguments following it are to be passed in their actual form as though double quotes were placed around them. For example, using `--` you can output the string `-InputObject` diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md index 9f780839b2e6..27673c04cdd4 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -200,8 +200,6 @@ prevent PowerShell from misinterpreting the parentheses. icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ``` -### The stop-parsing and end-of-parameters tokens - Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) and _end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as PowerShell commands or expressions. @@ -209,6 +207,8 @@ PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. +### The stop-parsing token + When calling a native command, place the stop-parsing token before the program arguments. This technique is much easier than using escape characters to prevent misinterpretation. @@ -239,6 +239,8 @@ variable the token is passed through as-is. You cannot use stream redirection (like `>file.txt`) because they are passed verbatim as arguments to the target command. +### The end-of-parameters token + The end-of-parameters token (`--`) indicates that all arguments following it are to be passed in their actual form as though double quotes were placed around them. For example, using `--` you can output the string `-InputObject` diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md index 6350a22a74d2..c989823195a1 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -200,8 +200,6 @@ prevent PowerShell from misinterpreting the parentheses. icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ``` -### The stop-parsing and end-of-parameters tokens - Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) and _end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as PowerShell commands or expressions. @@ -209,6 +207,8 @@ PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. +### The stop-parsing token + When calling a native command, place the stop-parsing token before the program arguments. This technique is much easier than using escape characters to prevent misinterpretation. @@ -239,6 +239,8 @@ variable the token is passed through as-is. You cannot use stream redirection (like `>file.txt`) because they are passed verbatim as arguments to the target command. +### The end-of-parameters token + The end-of-parameters token (`--`) indicates that all arguments following it are to be passed in their actual form as though double quotes were placed around them. For example, using `--` you can output the string `-InputObject` diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md index f60dab6dafd3..f417b8d37541 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -200,8 +200,6 @@ prevent PowerShell from misinterpreting the parentheses. icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ``` -### The stop-parsing and end-of-parameters tokens - Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) and _end-of-parameters_ tokens (`--`) to stop PowerShell from interpreting input as PowerShell commands or expressions. @@ -209,6 +207,8 @@ PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. +### The stop-parsing token + When calling a native command, place the stop-parsing token before the program arguments. This technique is much easier than using escape characters to prevent misinterpretation. @@ -239,6 +239,8 @@ variable the token is passed through as-is. You cannot use stream redirection (like `>file.txt`) because they are passed verbatim as arguments to the target command. +### The end-of-parameters token + The end-of-parameters token (`--`) indicates that all arguments following it are to be passed in their actual form as though double quotes were placed around them. For example, using `--` you can output the string `-InputObject` From a44ebe609c88fa0e7353bec2cbb436839c60b279 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 16 May 2022 16:40:46 -0500 Subject: [PATCH 5/6] Fix formatting and Example #3 description (#8820) --- .../Resolve-Path.md | 20 ++++----- .../Resolve-Path.md | 20 ++++----- .../Resolve-Path.md | 44 +++++++++--------- .../Resolve-Path.md | 45 +++++++++---------- .../Resolve-Path.md | 45 +++++++++---------- 5 files changed, 83 insertions(+), 91 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Resolve-Path.md b/reference/5.1/Microsoft.PowerShell.Management/Resolve-Path.md index 510323bf593e..49ece00091ff 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Resolve-Path.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Resolve-Path.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 03/12/2020 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/resolve-path?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Resolve-Path @@ -31,13 +31,13 @@ Resolve-Path -LiteralPath [-Relative] [-Credential ] [- The `Resolve-Path` cmdlet displays the items and containers that match the wildcard pattern at the location specified. The match can include files, folders, registry keys, or any other object -accessible from a PSDrive provider. +accessible from a **PSDrive** provider. ## EXAMPLES ### Example 1: Resolve the home folder path -The tilde character (~) is shorthand notation for the current user's home folder. This example +The tilde character (`~`) is shorthand notation for the current user's home folder. This example shows `Resolve-Path` returning the fully qualified path value. ```powershell @@ -62,8 +62,8 @@ Path C:\Windows ``` -When run from the root of the C: drive, this command returns the path of the Windows folder in the -C: drive. +When run from the root of the `C:` drive, this command returns the path of the `Windows` folder in +the `C:` drive. ### Example 3: Get all paths in the Windows folder @@ -71,8 +71,8 @@ C: drive. PS C:\> "C:\windows\*" | Resolve-Path ``` -This command returns all of the folders in the C:\Windows folder. The command uses a pipeline -operator (|) to send a path string to `Resolve-Path`. +This command returns all the files and folders in the `C:\Windows` folder. The command uses a +pipeline operator (`|`) to send a path string to `Resolve-Path`. ### Example 4: Resolve a UNC path @@ -94,11 +94,11 @@ PS C:\> Resolve-Path -Path "c:\prog*" -Relative .\programs.txt ``` -This command returns relative paths for the directories at the root of the C: drive. +This command returns relative paths for the directories at the root of the `C:` drive. ### Example 6: Resolve a path containing brackets -This example uses the **LiteralPath** parameter to resolve the path of the Test\[xml\] subfolder. +This example uses the **LiteralPath** parameter to resolve the path of the `Test[xml]` subfolder. Using **LiteralPath** causes the brackets to be treated as normal characters rather than a regular expression. @@ -222,7 +222,7 @@ Returns a **PathInfo** object. Returns a string value for the resolved path if y ## NOTES -The `*-Path` cmdlets work with the FileSystem, Registry, and Certificate providers. +The `*-Path` cmdlets work with the **FileSystem**, **Registry**, and **Certificate** providers. `Resolve-Path` is designed to work with any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see diff --git a/reference/7.0/Microsoft.PowerShell.Management/Resolve-Path.md b/reference/7.0/Microsoft.PowerShell.Management/Resolve-Path.md index ebf3122f2805..b396ac0ea590 100644 --- a/reference/7.0/Microsoft.PowerShell.Management/Resolve-Path.md +++ b/reference/7.0/Microsoft.PowerShell.Management/Resolve-Path.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 03/12/2020 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/resolve-path?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: Resolve-Path @@ -30,13 +30,13 @@ Resolve-Path -LiteralPath [-Relative] [-Credential ] [< The `Resolve-Path` cmdlet displays the items and containers that match the wildcard pattern at the location specified. The match can include files, folders, registry keys, or any other object -accessible from a PSDrive provider. +accessible from a **PSDrive** provider. ## EXAMPLES ### Example 1: Resolve the home folder path -The tilde character (~) is shorthand notation for the current user's home folder. This example +The tilde character (`~`) is shorthand notation for the current user's home folder. This example shows `Resolve-Path` returning the fully qualified path value. ```powershell @@ -61,8 +61,8 @@ Path C:\Windows ``` -When run from the root of the C: drive, this command returns the path of the Windows folder in the -C: drive. +When run from the root of the `C:` drive, this command returns the path of the `Windows` folder in +the `C:` drive. ### Example 3: Get all paths in the Windows folder @@ -70,8 +70,8 @@ C: drive. PS C:\> "C:\windows\*" | Resolve-Path ``` -This command returns all of the folders in the C:\Windows folder. The command uses a pipeline -operator (|) to send a path string to `Resolve-Path`. +This command returns all the files and folders in the `C:\Windows` folder. The command uses a +pipeline operator (`|`) to send a path string to `Resolve-Path`. ### Example 4: Resolve a UNC path @@ -93,11 +93,11 @@ PS C:\> Resolve-Path -Path "c:\prog*" -Relative .\programs.txt ``` -This command returns relative paths for the directories at the root of the C: drive. +This command returns relative paths for the directories at the root of the `C:` drive. ### Example 6: Resolve a path containing brackets -This example uses the **LiteralPath** parameter to resolve the path of the Test\[xml\] subfolder. +This example uses the **LiteralPath** parameter to resolve the path of the `Test[xml]` subfolder. Using **LiteralPath** causes the brackets to be treated as normal characters rather than a regular expression. @@ -204,7 +204,7 @@ Returns a **PathInfo** object. Returns a string value for the resolved path if y ## NOTES -The `*-Path` cmdlets work with the FileSystem, Registry, and Certificate providers. +The `*-Path` cmdlets work with the **FileSystem**, **Registry**, and **Certificate** providers. `Resolve-Path` is designed to work with any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see diff --git a/reference/7.1/Microsoft.PowerShell.Management/Resolve-Path.md b/reference/7.1/Microsoft.PowerShell.Management/Resolve-Path.md index 2150b216f342..ad40913845de 100644 --- a/reference/7.1/Microsoft.PowerShell.Management/Resolve-Path.md +++ b/reference/7.1/Microsoft.PowerShell.Management/Resolve-Path.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 03/12/2020 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/resolve-path?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Resolve-Path @@ -30,13 +30,13 @@ Resolve-Path -LiteralPath [-Relative] [-Credential ] [< The `Resolve-Path` cmdlet displays the items and containers that match the wildcard pattern at the location specified. The match can include files, folders, registry keys, or any other object -accessible from a PSDrive provider. +accessible from a **PSDrive** provider. ## EXAMPLES ### Example 1: Resolve the home folder path -The tilde character (~) is shorthand notation for the current user's home folder. This example +The tilde character (`~`) is shorthand notation for the current user's home folder. This example shows `Resolve-Path` returning the fully qualified path value. ```powershell @@ -61,8 +61,8 @@ Path C:\Windows ``` -When run from the root of the C: drive, this command returns the path of the Windows folder in the -C: drive. +When run from the root of the `C:` drive, this command returns the path of the `Windows` folder in +the `C:` drive. ### Example 3: Get all paths in the Windows folder @@ -70,8 +70,8 @@ C: drive. PS C:\> "C:\windows\*" | Resolve-Path ``` -This command returns all of the folders in the C:\Windows folder. The command uses a pipeline -operator (|) to send a path string to `Resolve-Path`. +This command returns all the files and folders in the `C:\Windows` folder. The command uses a +pipeline operator (`|`) to send a path string to `Resolve-Path`. ### Example 4: Resolve a UNC path @@ -93,11 +93,11 @@ PS C:\> Resolve-Path -Path "c:\prog*" -Relative .\programs.txt ``` -This command returns relative paths for the directories at the root of the C: drive. +This command returns relative paths for the directories at the root of the `C:` drive. ### Example 6: Resolve a path containing brackets -This example uses the **LiteralPath** parameter to resolve the path of the Test\[xml\] subfolder. +This example uses the **LiteralPath** parameter to resolve the path of the `Test[xml]` subfolder. Using **LiteralPath** causes the brackets to be treated as normal characters rather than a regular expression. @@ -109,8 +109,8 @@ PS C:\> Resolve-Path -LiteralPath 'test[xml]' ### -Credential -Specifies a user account that has permission to perform this action. -The default is the current user. +Specifies a user account that has permission to perform this action. The default is the current +user. Type a user name, such as User01 or Domain01\User01, or pass a **PSCredential** object. You can create a **PSCredential** object using the `Get-Credential` cmdlet. If you type a user name, this @@ -132,11 +132,10 @@ Accept wildcard characters: False ### -LiteralPath -Specifies the path to be resolved. -The value of the **LiteralPath** parameter is used exactly as typed. -No characters are interpreted as wildcard characters. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell PowerShell not to interpret any characters as escape sequences. +Specifies the path to be resolved. The value of the **LiteralPath** parameter is used exactly as +typed. No characters are interpreted as wildcard characters. If the path includes escape characters, +enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any +characters as escape sequences. ```yaml Type: System.String[] @@ -152,10 +151,8 @@ Accept wildcard characters: False ### -Path -Specifies the PowerShell path to resolve. -This parameter is required. -You can also pipe a path string to `Resolve-Path`. -Wildcard characters are permitted. +Specifies the PowerShell path to resolve. This parameter is required. You can also pipe a path +string to `Resolve-Path`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -189,13 +186,14 @@ 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](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String -You can pipe a string that contains a path to this cmdlet +You can pipe a string that contains a path to this cmdlet. ## OUTPUTS @@ -206,7 +204,7 @@ Returns a **PathInfo** object. Returns a string value for the resolved path if y ## NOTES -The `*-Path` cmdlets work with the FileSystem, Registry, and Certificate providers. +The `*-Path` cmdlets work with the **FileSystem**, **Registry**, and **Certificate** providers. `Resolve-Path` is designed to work with any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see diff --git a/reference/7.2/Microsoft.PowerShell.Management/Resolve-Path.md b/reference/7.2/Microsoft.PowerShell.Management/Resolve-Path.md index 8ccf106d7c85..d6c8ca3eea48 100644 --- a/reference/7.2/Microsoft.PowerShell.Management/Resolve-Path.md +++ b/reference/7.2/Microsoft.PowerShell.Management/Resolve-Path.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 03/12/2020 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/resolve-path?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Resolve-Path @@ -30,13 +30,13 @@ Resolve-Path -LiteralPath [-Relative] [-Credential ] [< The `Resolve-Path` cmdlet displays the items and containers that match the wildcard pattern at the location specified. The match can include files, folders, registry keys, or any other object -accessible from a PSDrive provider. +accessible from a **PSDrive** provider. ## EXAMPLES ### Example 1: Resolve the home folder path -The tilde character (~) is shorthand notation for the current user's home folder. This example +The tilde character (`~`) is shorthand notation for the current user's home folder. This example shows `Resolve-Path` returning the fully qualified path value. ```powershell @@ -61,8 +61,8 @@ Path C:\Windows ``` -When run from the root of the C: drive, this command returns the path of the Windows folder in the -C: drive. +When run from the root of the `C:` drive, this command returns the path of the `Windows` folder in +the `C:` drive. ### Example 3: Get all paths in the Windows folder @@ -70,8 +70,8 @@ C: drive. PS C:\> "C:\windows\*" | Resolve-Path ``` -This command returns all of the folders in the C:\Windows folder. The command uses a pipeline -operator (|) to send a path string to `Resolve-Path`. +This command returns all the files and folders in the `C:\Windows` folder. The command uses a +pipeline operator (`|`) to send a path string to `Resolve-Path`. ### Example 4: Resolve a UNC path @@ -93,11 +93,11 @@ PS C:\> Resolve-Path -Path "c:\prog*" -Relative .\programs.txt ``` -This command returns relative paths for the directories at the root of the C: drive. +This command returns relative paths for the directories at the root of the `C:` drive. ### Example 6: Resolve a path containing brackets -This example uses the **LiteralPath** parameter to resolve the path of the Test\[xml\] subfolder. +This example uses the **LiteralPath** parameter to resolve the path of the `Test[xml]` subfolder. Using **LiteralPath** causes the brackets to be treated as normal characters rather than a regular expression. @@ -109,8 +109,8 @@ PS C:\> Resolve-Path -LiteralPath 'test[xml]' ### -Credential -Specifies a user account that has permission to perform this action. -The default is the current user. +Specifies a user account that has permission to perform this action. The default is the current +user. Type a user name, such as User01 or Domain01\User01, or pass a **PSCredential** object. You can create a **PSCredential** object using the `Get-Credential` cmdlet. If you type a user name, this @@ -132,11 +132,10 @@ Accept wildcard characters: False ### -LiteralPath -Specifies the path to be resolved. -The value of the **LiteralPath** parameter is used exactly as typed. -No characters are interpreted as wildcard characters. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell PowerShell not to interpret any characters as escape sequences. +Specifies the path to be resolved. The value of the **LiteralPath** parameter is used exactly as +typed. No characters are interpreted as wildcard characters. If the path includes escape characters, +enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any +characters as escape sequences. ```yaml Type: System.String[] @@ -152,10 +151,8 @@ Accept wildcard characters: False ### -Path -Specifies the PowerShell path to resolve. -This parameter is required. -You can also pipe a path string to `Resolve-Path`. -Wildcard characters are permitted. +Specifies the PowerShell path to resolve. This parameter is required. You can also pipe a path +string to `Resolve-Path`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -189,13 +186,14 @@ 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](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String -You can pipe a string that contains a path to this cmdlet +You can pipe a string that contains a path to this cmdlet. ## OUTPUTS @@ -206,7 +204,7 @@ Returns a **PathInfo** object. Returns a string value for the resolved path if y ## NOTES -The `*-Path` cmdlets work with the FileSystem, Registry, and Certificate providers. +The `*-Path` cmdlets work with the **FileSystem**, **Registry**, and **Certificate** providers. `Resolve-Path` is designed to work with any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see @@ -224,4 +222,3 @@ exist yet. [Split-Path](Split-Path.md) [Test-Path](Test-Path.md) - diff --git a/reference/7.3/Microsoft.PowerShell.Management/Resolve-Path.md b/reference/7.3/Microsoft.PowerShell.Management/Resolve-Path.md index de97e1a553da..dc180a71e731 100644 --- a/reference/7.3/Microsoft.PowerShell.Management/Resolve-Path.md +++ b/reference/7.3/Microsoft.PowerShell.Management/Resolve-Path.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 03/12/2020 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/resolve-path?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: Resolve-Path @@ -30,13 +30,13 @@ Resolve-Path -LiteralPath [-Relative] [-Credential ] [< The `Resolve-Path` cmdlet displays the items and containers that match the wildcard pattern at the location specified. The match can include files, folders, registry keys, or any other object -accessible from a PSDrive provider. +accessible from a **PSDrive** provider. ## EXAMPLES ### Example 1: Resolve the home folder path -The tilde character (~) is shorthand notation for the current user's home folder. This example +The tilde character (`~`) is shorthand notation for the current user's home folder. This example shows `Resolve-Path` returning the fully qualified path value. ```powershell @@ -61,8 +61,8 @@ Path C:\Windows ``` -When run from the root of the C: drive, this command returns the path of the Windows folder in the -C: drive. +When run from the root of the `C:` drive, this command returns the path of the `Windows` folder in +the `C:` drive. ### Example 3: Get all paths in the Windows folder @@ -70,8 +70,8 @@ C: drive. PS C:\> "C:\windows\*" | Resolve-Path ``` -This command returns all of the folders in the C:\Windows folder. The command uses a pipeline -operator (|) to send a path string to `Resolve-Path`. +This command returns all the files and folders in the `C:\Windows` folder. The command uses a +pipeline operator (`|`) to send a path string to `Resolve-Path`. ### Example 4: Resolve a UNC path @@ -93,11 +93,11 @@ PS C:\> Resolve-Path -Path "c:\prog*" -Relative .\programs.txt ``` -This command returns relative paths for the directories at the root of the C: drive. +This command returns relative paths for the directories at the root of the `C:` drive. ### Example 6: Resolve a path containing brackets -This example uses the **LiteralPath** parameter to resolve the path of the Test\[xml\] subfolder. +This example uses the **LiteralPath** parameter to resolve the path of the `Test[xml]` subfolder. Using **LiteralPath** causes the brackets to be treated as normal characters rather than a regular expression. @@ -109,8 +109,8 @@ PS C:\> Resolve-Path -LiteralPath 'test[xml]' ### -Credential -Specifies a user account that has permission to perform this action. -The default is the current user. +Specifies a user account that has permission to perform this action. The default is the current +user. Type a user name, such as User01 or Domain01\User01, or pass a **PSCredential** object. You can create a **PSCredential** object using the `Get-Credential` cmdlet. If you type a user name, this @@ -132,11 +132,10 @@ Accept wildcard characters: False ### -LiteralPath -Specifies the path to be resolved. -The value of the **LiteralPath** parameter is used exactly as typed. -No characters are interpreted as wildcard characters. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell PowerShell not to interpret any characters as escape sequences. +Specifies the path to be resolved. The value of the **LiteralPath** parameter is used exactly as +typed. No characters are interpreted as wildcard characters. If the path includes escape characters, +enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any +characters as escape sequences. ```yaml Type: System.String[] @@ -152,10 +151,8 @@ Accept wildcard characters: False ### -Path -Specifies the PowerShell path to resolve. -This parameter is required. -You can also pipe a path string to `Resolve-Path`. -Wildcard characters are permitted. +Specifies the PowerShell path to resolve. This parameter is required. You can also pipe a path +string to `Resolve-Path`. Wildcard characters are permitted. ```yaml Type: System.String[] @@ -189,13 +186,14 @@ 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](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String -You can pipe a string that contains a path to this cmdlet +You can pipe a string that contains a path to this cmdlet. ## OUTPUTS @@ -206,7 +204,7 @@ Returns a **PathInfo** object. Returns a string value for the resolved path if y ## NOTES -The `*-Path` cmdlets work with the FileSystem, Registry, and Certificate providers. +The `*-Path` cmdlets work with the **FileSystem**, **Registry**, and **Certificate** providers. `Resolve-Path` is designed to work with any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see @@ -224,4 +222,3 @@ exist yet. [Split-Path](Split-Path.md) [Test-Path](Test-Path.md) - From 44d1d260902280c53e0522ca49609e9f924669bf Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 16 May 2022 16:52:06 -0500 Subject: [PATCH 6/6] Update description of Start-Sleep (#8821) --- .../Start-Sleep.md | 37 ++++++++++--------- .../Start-Sleep.md | 26 ++++++++----- .../Start-Sleep.md | 27 +++++++++----- .../Start-Sleep.md | 27 +++++++++----- .../Start-Sleep.md | 23 ++++++++---- 5 files changed, 86 insertions(+), 54 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Start-Sleep.md b/reference/5.1/Microsoft.PowerShell.Utility/Start-Sleep.md index 109df7c4bc93..6a43855639fe 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Start-Sleep.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Start-Sleep.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: 03/13/2019 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/start-sleep?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Start-Sleep @@ -29,35 +29,37 @@ Start-Sleep -Milliseconds [] ## DESCRIPTION The `Start-Sleep` cmdlet suspends the activity in a script or session for the specified period of -time. -You can use it for many tasks, such as waiting for an operation to complete or pausing before +time. You can use it for many tasks, such as waiting for an operation to complete or pausing before repeating an operation. ## EXAMPLES -### Example 1: Sleep all commands for 15 seconds +### Example 1: Pause execution for 1.5 seconds + +This example execution of commands for one and one-half of a seconds. ```powershell -Start-Sleep -s 15 +Start-Sleep -Seconds 1.5 ``` -This command makes all commands in the session sleep for 15 seconds. +### Example 2: Pause execution at the command line -### Example 2: Sleep all commands +This example shows that execution is paused for 5 seconds when run from the command line. ```powershell -Start-Sleep -m 500 +PS> Get-Date; Start-Sleep -Seconds 5; Get-Date + +Friday, May 13, 2022 9:38:15 AM +Friday, May 13, 2022 9:38:20 AM ``` -This command makes all the commands in the session sleep for one-half of a second (500 -milliseconds). +PowerShell cannot execute the second `Get-Date` command until the sleep timer expires. ## PARAMETERS ### -Milliseconds -Specifies how long the resource sleeps in milliseconds. -The parameter can be abbreviated as **m**. +Specifies how long the resource sleeps in milliseconds. The parameter can be abbreviated as **m**. ```yaml Type: System.Int32 @@ -73,8 +75,8 @@ Accept wildcard characters: False ### -Seconds -Specifies how long the resource sleeps in seconds. -You can omit the parameter name (**Seconds**), or you can abbreviate it as **s**. +Specifies how long the resource sleeps in seconds. You can omit the parameter name or you can +abbreviate it as **s**. ```yaml Type: System.Int32 @@ -92,7 +94,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](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -111,7 +114,7 @@ This cmdlet does not return any output. - You can also refer to `Start-Sleep` by its built-in alias, `sleep`. For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). - `Ctrl+C` breaks out of `Start-Sleep`. - - `Ctrl+C` does not break out of `[Threading.Thread]::Sleep`. For more information, see - [Thread.Sleep Method](/dotnet/api/system.threading.thread.sleep). +- `Ctrl+C` does not break out of `[Threading.Thread]::Sleep`. For more information, see + [Thread.Sleep Method](/dotnet/api/system.threading.thread.sleep). ## RELATED LINKS diff --git a/reference/7.0/Microsoft.PowerShell.Utility/Start-Sleep.md b/reference/7.0/Microsoft.PowerShell.Utility/Start-Sleep.md index de4dd092d2e2..11603bd61ef2 100644 --- a/reference/7.0/Microsoft.PowerShell.Utility/Start-Sleep.md +++ b/reference/7.0/Microsoft.PowerShell.Utility/Start-Sleep.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: 04/10/2019 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/start-sleep?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: Start-Sleep @@ -34,20 +34,27 @@ repeating an operation. ## EXAMPLES -### Example 1: Sleep all commands for 15 seconds +### Example 1: Pause execution for 1.5 seconds + +This example execution of commands for one and one-half of a seconds. ```powershell -Start-Sleep -s 15 +Start-Sleep -Seconds 1.5 ``` -### Example 2: Sleep all commands for 1.5 seconds +### Example 2: Pause execution at the command line -This example makes all the commands in the session sleep for one and one-half of a seconds. +This example shows that execution is paused for 5 seconds when run from the command line. ```powershell -Start-Sleep -Seconds 1.5 +PS> Get-Date; Start-Sleep -Seconds 5; Get-Date + +Friday, May 13, 2022 9:38:15 AM +Friday, May 13, 2022 9:38:20 AM ``` +PowerShell cannot execute the second `Get-Date` command until the sleep timer expires. + ## PARAMETERS ### -Milliseconds @@ -87,7 +94,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](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -106,7 +114,7 @@ This cmdlet does not return any output. - You can also refer to `Start-Sleep` by its built-in alias, `sleep`. For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). - `Ctrl+C` breaks out of `Start-Sleep`. - - `Ctrl+C` does not break out of `[Threading.Thread]::Sleep`. For more information, see - [Thread.Sleep Method](/dotnet/api/system.threading.thread.sleep). +- `Ctrl+C` does not break out of `[Threading.Thread]::Sleep`. For more information, see + [Thread.Sleep Method](/dotnet/api/system.threading.thread.sleep). ## RELATED LINKS diff --git a/reference/7.1/Microsoft.PowerShell.Utility/Start-Sleep.md b/reference/7.1/Microsoft.PowerShell.Utility/Start-Sleep.md index e42315b2cb2c..007f53d1dfc9 100644 --- a/reference/7.1/Microsoft.PowerShell.Utility/Start-Sleep.md +++ b/reference/7.1/Microsoft.PowerShell.Utility/Start-Sleep.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: 04/10/2019 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/start-sleep?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Start-Sleep @@ -34,20 +34,27 @@ repeating an operation. ## EXAMPLES -### Example 1: Sleep all commands for 15 seconds +### Example 1: Pause execution for 1.5 seconds + +This example execution of commands for one and one-half of a seconds. ```powershell -Start-Sleep -s 15 +Start-Sleep -Seconds 1.5 ``` -### Example 2: Sleep all commands for 1.5 seconds +### Example 2: Pause execution at the command line -This example makes all the commands in the session sleep for one and one-half of a seconds. +This example shows that execution is paused for 5 seconds when run from the command line. ```powershell -Start-Sleep -Seconds 1.5 +PS> Get-Date; Start-Sleep -Seconds 5; Get-Date + +Friday, May 13, 2022 9:38:15 AM +Friday, May 13, 2022 9:38:20 AM ``` +PowerShell cannot execute the second `Get-Date` command until the sleep timer expires. + ## PARAMETERS ### -Milliseconds @@ -87,7 +94,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](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -106,8 +114,7 @@ This cmdlet does not return any output. - You can also refer to `Start-Sleep` by its built-in alias, `sleep`. For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). - `Ctrl+C` breaks out of `Start-Sleep`. - - `Ctrl+C` does not break out of `[Threading.Thread]::Sleep`. For more information, see - [Thread.Sleep Method](/dotnet/api/system.threading.thread.sleep). +- `Ctrl+C` does not break out of `[Threading.Thread]::Sleep`. For more information, see + [Thread.Sleep Method](/dotnet/api/system.threading.thread.sleep). ## RELATED LINKS - diff --git a/reference/7.2/Microsoft.PowerShell.Utility/Start-Sleep.md b/reference/7.2/Microsoft.PowerShell.Utility/Start-Sleep.md index f0cc174dc8ed..0819b8c447d6 100644 --- a/reference/7.2/Microsoft.PowerShell.Utility/Start-Sleep.md +++ b/reference/7.2/Microsoft.PowerShell.Utility/Start-Sleep.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: 04/10/2019 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/start-sleep?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Start-Sleep @@ -34,20 +34,27 @@ repeating an operation. ## EXAMPLES -### Example 1: Sleep all commands for 15 seconds +### Example 1: Pause execution for 1.5 seconds + +This example execution of commands for one and one-half of a seconds. ```powershell -Start-Sleep -s 15 +Start-Sleep -Seconds 1.5 ``` -### Example 2: Sleep all commands for 1.5 seconds +### Example 2: Pause execution at the command line -This example makes all the commands in the session sleep for one and one-half of a seconds. +This example shows that execution is paused for 5 seconds when run from the command line. ```powershell -Start-Sleep -Seconds 1.5 +PS> Get-Date; Start-Sleep -Seconds 5; Get-Date + +Friday, May 13, 2022 9:38:15 AM +Friday, May 13, 2022 9:38:20 AM ``` +PowerShell cannot execute the second `Get-Date` command until the sleep timer expires. + ## PARAMETERS ### -Milliseconds @@ -87,7 +94,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](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -106,8 +114,7 @@ This cmdlet does not return any output. - You can also refer to `Start-Sleep` by its built-in alias, `sleep`. For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). - `Ctrl+C` breaks out of `Start-Sleep`. - - `Ctrl+C` does not break out of `[Threading.Thread]::Sleep`. For more information, see - [Thread.Sleep Method](/dotnet/api/system.threading.thread.sleep). +- `Ctrl+C` does not break out of `[Threading.Thread]::Sleep`. For more information, see + [Thread.Sleep Method](/dotnet/api/system.threading.thread.sleep). ## RELATED LINKS - diff --git a/reference/7.3/Microsoft.PowerShell.Utility/Start-Sleep.md b/reference/7.3/Microsoft.PowerShell.Utility/Start-Sleep.md index e52c5388bd6d..e3e05c0c3576 100644 --- a/reference/7.3/Microsoft.PowerShell.Utility/Start-Sleep.md +++ b/reference/7.3/Microsoft.PowerShell.Utility/Start-Sleep.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/18/2022 +ms.date: 05/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/start-sleep?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: Start-Sleep @@ -40,20 +40,27 @@ repeating an operation. ## EXAMPLES -### Example 1: Sleep all commands for 15 seconds +### Example 1: Pause execution for 1.5 seconds + +This example execution of commands for one and one-half of a seconds. ```powershell -Start-Sleep -s 15 +Start-Sleep -Seconds 1.5 ``` -### Example 2: Sleep all commands for 1.5 seconds +### Example 2: Pause execution at the command line -This example makes all the commands in the session sleep for one and one-half of a seconds. +This example shows that execution is paused for 5 seconds when run from the command line. ```powershell -Start-Sleep -Seconds 1.5 +PS> Get-Date; Start-Sleep -Seconds 5; Get-Date + +Friday, May 13, 2022 9:38:15 AM +Friday, May 13, 2022 9:38:20 AM ``` +PowerShell cannot execute the second `Get-Date` command until the sleep timer expires. + ### Example 3: Sleep commands using a **TimeSpan** This example makes all the commands in the session sleep for 30 seconds. @@ -138,7 +145,7 @@ This cmdlet does not return any output. - You can also refer to `Start-Sleep` by its built-in alias, `sleep`. For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). - `Ctrl+C` breaks out of `Start-Sleep`. - - `Ctrl+C` does not break out of `[Threading.Thread]::Sleep`. For more information, see - [Thread.Sleep Method](/dotnet/api/system.threading.thread.sleep). +- `Ctrl+C` does not break out of `[Threading.Thread]::Sleep`. For more information, see + [Thread.Sleep Method](/dotnet/api/system.threading.thread.sleep). ## RELATED LINKS