Document pipeline chain operators (&&/||) #4856

rjmholt · 2019-09-30T22:23:01Z

Resolves #4853.

Document pipeline chain operators (&&/||), which are added to PowerShell 7 by PowerShell/PowerShell#9849.

See also: PowerShell/PowerShell-RFC#192.

Version(s) of document impacted

Reason(s) for not updating all version of documents

The documented feature was introduced in version (list version here) of PowerShell
This issue only shows up in version (list version(s) here) of the document
This PR partially fixes the issue, and issue # tracks the remaining work

opbld30 · 2019-09-30T22:33:35Z

Docs Build status updates of commit 2f31955:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/7/Microsoft.PowerShell.Core/About/about_Operators.md	⚠️Warning	View (powershell-7)	Details
reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md	⚠️Warning	View (powershell-7)	Details

reference/7/Microsoft.PowerShell.Core/About/about_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

opbld31 · 2019-09-30T22:43:29Z

Docs Build status updates of commit 741e1af:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/7/Microsoft.PowerShell.Core/About/about_Operators.md	⚠️Warning	View (powershell-7)	Details
reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md	⚠️Warning	View (powershell-7)	Details

reference/7/Microsoft.PowerShell.Core/About/about_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

opbld32 · 2019-09-30T23:07:10Z

Docs Build status updates of commit 118a564:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/7/Microsoft.PowerShell.Core/About/about_Operators.md	⚠️Warning	View (powershell-7)	Details
reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md	⚠️Warning	View (powershell-7)	Details

reference/7/Microsoft.PowerShell.Core/About/about_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

opbld34 · 2019-09-30T23:30:02Z

Docs Build status updates of commit 3c5eb02:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/7/Microsoft.PowerShell.Core/About/about_Operators.md	⚠️Warning	View (powershell-7)	Details
reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md	⚠️Warning	View (powershell-7)	Details

reference/7/Microsoft.PowerShell.Core/About/about_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

rjmholt · 2019-09-30T23:30:24Z

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

+succeeded. Conversely, the `||` operator executes the right-hand pipeline if
+the left-hand pipeline failed.
+
+This can be use for conditional execution of software deployments. For example:


use -> used.

The language here feels too specific for an operator to me.

If this example demands language like that, we should change the example.

I want to be able to emphasise that this works with native commands based on $?/$LASTEXITCODE and not just with cmdlets/functions.

rjmholt · 2019-09-30T23:31:46Z

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

+In this example the `npm run deploy` command only runs if the build command
+succeeds.
+
+> [!NOTE]


I would put this note immediately under the Long Description

opbld33 · 2019-10-01T16:19:05Z

Docs Build status updates of commit ab5ef75:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/7/Microsoft.PowerShell.Core/About/about_Operators.md	⚠️Warning	View (powershell-7)	Details
reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md	⚠️Warning	View (powershell-7)	Details

reference/7/Microsoft.PowerShell.Core/About/about_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

opbld31 · 2019-10-01T16:28:44Z

Docs Build status updates of commit 9bbf66a:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/7/Microsoft.PowerShell.Core/About/about_Operators.md	⚠️Warning	View (powershell-7)	Details
reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md	⚠️Warning	View (powershell-7)	Details

reference/7/Microsoft.PowerShell.Core/About/about_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

opbld32 · 2019-10-01T16:45:34Z

Docs Build status updates of commit 211ba99:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/7/Microsoft.PowerShell.Core/About/about_Operators.md	⚠️Warning	View (powershell-7)	Details
reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md	⚠️Warning	View (powershell-7)	Details

reference/7/Microsoft.PowerShell.Core/About/about_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

rjmholt · 2019-10-02T00:03:08Z

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

+
+These operators use the `$?` and `$LASTEXITCODE` variables to determine if a
+pipeline failed. This allows you to use them with native command and not just
+with cmdlets or functions. For example, this could be used for conditional


I want to stay away from the specifics of the example this early in the doc. I'll give a better example below

See my updates

rjmholt · 2019-10-02T00:20:43Z

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

+execution of a software deployment:
+
+```powershell
+npm run build && npm run deploy


A better example might be this:

# Create a new SSH key pair and if successful, copy the public key to the clipboard ssh-keygen -t rsa -b 2048 && Get-Content -Raw ~\.ssh\id_rsa.pub | clip

See my updates

opbld32 · 2019-10-02T00:41:20Z

Docs Build status updates of commit fae3c77:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/7/Microsoft.PowerShell.Core/About/about_Operators.md	⚠️Warning	View (powershell-7)	Details
reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md	⚠️Warning	View (powershell-7)	Details

reference/7/Microsoft.PowerShell.Core/About/about_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

rjmholt

LGTM

rjmholt · 2019-10-02T00:44:35Z

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

+assigned to variables, or separated as statements.
+
+To use lower precedence syntax within a pipeline chain, consider the use of
+parentheses `(...)` or a subexpression `$(...)`.


I omitted a thing here about && and || being left associative (so cmd1 && cmd2 && cmd3 is the same as [cmd1 && cmd2] && cmd3), but wasn't sure if that's too technical here.

It's relevant if you do something like:

Get-Item ./file.txt || Write-Error 'File not found' && Get-Content -Raw ./file.txt

The associativity means that Get-Content will be executed based on the result of Get-Item || Write-Error, so if Get-Item succeeds it is executed, but if it doesn't Write-Error runs, which by definition does not succeed, so Get-Content does not succeed.

I think it would be good to a note about associativity. Can associativity be altered using paretheses or braces? For example:

(Get-Item ./file.txt || Write-Error 'File not found') && Get-Content -Raw ./file.txt {Get-Item ./file.txt || Write-Error 'File not found'} && Get-Content -Raw ./file.txt

Parentheses currently don't work nicely because they always set $? to $true... That's always been the case unfortunately, although this feature has many people talking about changing it.

Unfortunately the dot-sourced scriptblock also suffers from this.

Ok, I've added a note about associativity, plus a bit about (...) etc setting $?

Looks good. Thanks

opbld33 · 2019-10-03T16:37:53Z

Docs Build status updates of commit 8a14926:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/7/Microsoft.PowerShell.Core/About/about_Operators.md	⚠️Warning	View (powershell-7)	Details
reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md	⚠️Warning	View (powershell-7)	Details

reference/7/Microsoft.PowerShell.Core/About/about_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

opbld31 · 2019-10-18T19:57:51Z

Docs Build status updates of commit cc4c93c:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/7/Microsoft.PowerShell.Core/About/about_Operators.md	⚠️Warning	View (powershell-7)	Details
reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md	⚠️Warning	View (powershell-7)	Details

reference/7/Microsoft.PowerShell.Core/About/about_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

reference/7/Microsoft.PowerShell.Core/About/about_Pipeline_Chain_Operators.md

[Warning] Metadata with following name(s) are not allowed to be set in Yaml header, or as file level metadata in docfx.json, or as global metadata in docfx.json: locale. They are generated by Docs platform, so the values set in these 3 places will be ignored. Please remove them from all 3 places to resolve the warning.

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

rjmholt requested review from daxian-dbw, SteveL-MSFT and sdwheeler September 30, 2019 22:23

sdwheeler added this to the 7.0.0 milestone Sep 30, 2019

sdwheeler approved these changes Sep 30, 2019

View reviewed changes

rjmholt commented Sep 30, 2019

View reviewed changes

Rob Holt and others added 6 commits October 1, 2019 09:31

Add pipeline chain doc, add to operators doc

e1e3c74

Improve see also links

9e5c5ee

Add titles for clarity

e0e8d99

Edit for style, etc.

9e43a44

Review feedback

0a5282c

fix typo

211ba99

sdwheeler force-pushed the pipeline-chain-operators branch from 9bbf66a to 211ba99 Compare October 1, 2019 16:35

sdwheeler added the hold-for-pr Waiting - for PR merge label Oct 1, 2019

rjmholt commented Oct 2, 2019

View reviewed changes

changed example

fae3c77

rjmholt commented Oct 2, 2019

View reviewed changes

Add note about associativity

8a14926

sdwheeler approved these changes Oct 3, 2019

View reviewed changes

DCtheGeek modified the milestones: 7.0.0, Future Oct 17, 2019

sdwheeler added area-language Area - PowerShell syntax and keywords and removed hold-for-pr Waiting - for PR merge labels Oct 18, 2019

sdwheeler modified the milestones: Future, 7.0.0 Oct 18, 2019

Merge branch 'staging' into pipeline-chain-operators

cc4c93c

sdwheeler merged commit ec886a1 into MicrosoftDocs:staging Oct 18, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document pipeline chain operators (&&/||) #4856

Document pipeline chain operators (&&/||) #4856

rjmholt commented Sep 30, 2019 •

edited

Loading

opbld30 commented Sep 30, 2019

opbld31 commented Sep 30, 2019

opbld32 commented Sep 30, 2019

opbld34 commented Sep 30, 2019

rjmholt Sep 30, 2019

sdwheeler Oct 1, 2019

rjmholt Sep 30, 2019

sdwheeler Oct 1, 2019

opbld33 commented Oct 1, 2019

opbld31 commented Oct 1, 2019

opbld32 commented Oct 1, 2019

rjmholt Oct 2, 2019

sdwheeler Oct 2, 2019

rjmholt Oct 2, 2019

sdwheeler Oct 2, 2019

opbld32 commented Oct 2, 2019

rjmholt left a comment

rjmholt Oct 2, 2019

sdwheeler Oct 2, 2019

rjmholt Oct 2, 2019

rjmholt Oct 3, 2019

sdwheeler Oct 3, 2019

opbld33 commented Oct 3, 2019

opbld31 commented Oct 18, 2019

Document pipeline chain operators (&&/||) #4856

Document pipeline chain operators (&&/||) #4856

Conversation

rjmholt commented Sep 30, 2019 • edited Loading

Version(s) of document impacted

Reason(s) for not updating all version of documents

opbld30 commented Sep 30, 2019

⚠️ Validation status: warnings

opbld31 commented Sep 30, 2019

⚠️ Validation status: warnings

opbld32 commented Sep 30, 2019

⚠️ Validation status: warnings

opbld34 commented Sep 30, 2019

⚠️ Validation status: warnings

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

opbld33 commented Oct 1, 2019

⚠️ Validation status: warnings

opbld31 commented Oct 1, 2019

⚠️ Validation status: warnings

opbld32 commented Oct 1, 2019

⚠️ Validation status: warnings

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

opbld32 commented Oct 2, 2019

⚠️ Validation status: warnings

rjmholt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

opbld33 commented Oct 3, 2019

⚠️ Validation status: warnings

opbld31 commented Oct 18, 2019

⚠️ Validation status: warnings

rjmholt commented Sep 30, 2019 •

edited

Loading