WIP: add more information about 'using' scope modifier to about_Remote_Variables.md #5497
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
My energy is very low at the moment. This is what I have been able to put together for now. I would love some help finishing this. Thank you. |
|
Docs Build status updates of commit 611b55f:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md | View (powershell-5.1) | Details | |
| reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md | View (powershell-6) | Details | |
| reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md | View (powershell-7) | Details | |
| reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md | View (powershell-7.x) | Details |
reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.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/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.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.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.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.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.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.
* corrects info about -NoEnumerate * Update reference/6/Microsoft.PowerShell.Utility/Write-Output.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/7.0/Microsoft.PowerShell.Utility/Write-Output.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/7.1/Microsoft.PowerShell.Utility/Write-Output.md Co-Authored-By: Sean Wheeler <[email protected]> Co-authored-by: Sean Wheeler <[email protected]>
* sync platyps changes * fix typos
* add docker article * uopdate TOC * Update reference/docs-conceptual/install/PowerShell-in-Docker.md Co-Authored-By: Steve Lee <[email protected]> * Update reference/docs-conceptual/install/PowerShell-in-Docker.md Co-Authored-By: Steve Lee <[email protected]> * Feedback edits * Update TOC Co-authored-by: Steve Lee <[email protected]>
* added [wip] Whats new PowerShell 7.0 * fixed format issue line 268 * fixed format issue line 268 * removed Whats NEw from Staging * [wip] Whats New in PowerShell 7 * [wip] Added word and example * update * updated Ternary/Null * Added version notification * update to notifications * update to format * update * update - Intro added, Win Compat added * update * update * updated with Migration section * update * update links localization * word correction * need to validate upgrade path * added note about winrm remoting on debian 10 * update * updated supported os's * Typo corrections thanks to @alexandair * added new language in running powershell * removed bad link en-us * Corrections thank to @alexandair * update to TOC for Whats New * updated with images * updated list with bullets * Update post Sean review * link update * Added link * added link * Release date update Co-authored-by: Sean Wheeler <[email protected]>
* Adds note about scope for persisting drive * updates to use CIministance * Update reference/5.1/Microsoft.PowerShell.Management/New-PSDrive.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/5.1/Microsoft.PowerShell.Management/New-PSDrive.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/7.0/Microsoft.PowerShell.Management/New-PSDrive.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/7.1/Microsoft.PowerShell.Management/New-PSDrive.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/7.1/Microsoft.PowerShell.Management/New-PSDrive.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/7.0/Microsoft.PowerShell.Management/New-PSDrive.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/6/Microsoft.PowerShell.Management/New-PSDrive.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/6/Microsoft.PowerShell.Management/New-PSDrive.md Co-Authored-By: Sean Wheeler <[email protected]> Co-authored-by: Sean Wheeler <[email protected]>
* Rename image folders * update image link * Update Infographic
* added [wip] Whats new PowerShell 7.0 * fixed format issue line 268 * fixed format issue line 268 * removed Whats NEw from Staging * [wip] Whats New in PowerShell 7 * [wip] Added word and example * update * updated Ternary/Null * Added version notification * update to notifications * update to format * update * update - Intro added, Win Compat added * update * update * updated with Migration section * update * update links localization * word correction * need to validate upgrade path * added note about winrm remoting on debian 10 * update * added running PowerShell 7
Typo in the description for the -InputObject parameter. Should say "remove" not "stop"
There are a few places that tripped me up while reading. These changes should improve readability and clarity.
* Fixes MicrosoftDocs#5520 - throw out the "throw" * Add module compatibilty list * fix formatting * feedback edits
* Fixes MicrosoftDocs#5520 - throw out the "throw" * Fixes MicrosoftDocs#5528 - typo
* Updates to about_module * Updates for about_EnvironmentVariables * Adds link for about_module * updates modifying the psmodulepath * Adds link to about Modules * Remove double backslash in code spans * Update about_Environment_Variables.md * Update about_Modules.md * Update about_Modules.md * Update about_Environment_Variables.md * Update about_Modules.md * Update about_Environment_Variables.md * Update about_Modules.md * Update modifying-the-psmodulepath-installation-path.md Co-authored-by: Sean Wheeler <[email protected]>
* Fixes MicrosoftDocs#5520 - throw out the "throw" * Add install instructions and repo link
Co-authored-by: Sean Wheeler <[email protected]>
* Adds PowerShell 7 lifecyle and updates doc * Fixes broken link issue * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Sean Wheeler <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Joey Aiello <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Joey Aiello <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Joey Aiello <[email protected]> * Update reference/docs-conceptual/PowerShell-Support-Lifecycle.md Co-Authored-By: Joey Aiello <[email protected]> * Updates for PR comments * Fixes bookmark Co-authored-by: Sean Wheeler <[email protected]> Co-authored-by: Joey Aiello <[email protected]>
|
@PaulHigin Can you review this PR? |
…rosoftDocs#5580) * Added clarifying statement and example * Added clarifying statement and example * Added clarifying statement and example * Update about_Remote_Variables.md * Update about_Remote_Variables.md * Update about_Remote_Variables.md * Update about_Remote_Variables.md Co-authored-by: Sean Wheeler <[email protected]>
* Adds info about difference between XML and CLI XML * updates dates * Updates fpr formatting common parameters
…Docs#5583) * Fixes MicrosoftDocs#3194 - impact of culture on parameters * update v5.1 error message * fix error message
* Fixes MicrosoftDocs#5530 - proxy support * fix typo
|
@Jawz84 Thanks for providing this! I'll review it first thing tomorrow. |
|
Thank you @PaulHigin |
PaulHigin
suggested changes
Mar 13, 2020
| ## Using local variables in PowerShell 2.0 | ||
| ### Other situations where the 'Using' scope modifier is needed | ||
|
|
||
| For anything that executes out-of-runspace, doesn't execute directly in the |
There was a problem hiding this comment.
Most users don't understand 'runspace', so I think we should use 'session'. Something like:
'For any script or command that executes out of session, you need the Using scope modifier to embed variable values from the calling session scope,
so that out of session code can access them. The Using scope modifier is supported in the following contexts:'
There was a problem hiding this comment.
@PaulHigin, I agree; just for context: the language comes from https://stackoverflow.com/a/60012780/45375, which @Jawz84 was kind enough to turn into this PR. In the SO answer, I was aiming for technical accuracy, but I do understand that the official documentation is (also) aimed at a less technical audience.
| can access it. (Conversely, all other contexts neither require nor support the | ||
| 'Using' scope modifier.) Specifically, this includes the following contexts: | ||
|
|
||
| - Remotely executed commands, started with Invoke-Command's `-ComputerName` or |
There was a problem hiding this comment.
Again, I feel we should not use 'runspace':
...(remote session)
...(out-of-process session)
...(separate thread session)
| - InlineScript in Workflows (out-of-process) | ||
|
|
||
| > [!NOTE] | ||
| > Note that out-of-runspace code can never modify variables in the caller's |
There was a problem hiding this comment.
Good note. This is a difficult concept for some users. I would write it:
'Depending on the context, embedded variables will be either copies of or references to the caller's scope variables. Out-of-process sessions (remote, background jobs, workflows) embed copies of variables through the PowerShell serialization system (see Serialization of variable values section below). But for thread jobs [and ForEach-Object -Parallel in 7.0+ versions], references to variables are passed to each thread session. This means it is possible to modify call scope variables in a different thread, but to do this safely requires thread synchronization.'
There was a problem hiding this comment.
"reference to variables" is precisely the terminology I suggest we avoid; it's a reference to an instance of a reference type, not to the variable - I know that the distinction is a subtle one, but if you phrase it that way, user may expect that passing variable $foo with a value-type instance such as 42 can be assigned to via $using:foo = 43, which isn't true.
$using:foo is the value of a variable, and if that value happens to be a reference (to a mutable object), other threads can modify it.
I know that the value-type / reference-type dichotomy is an advanced topic, but I don't think we should gloss over the distinction here, because it will ultimately cause more confusion.
| Remotely executed commands and background jobs run out-of-process. For values | ||
| in variables to cross these process boundaries they undergo XML-based | ||
| serialization and deserialization. This typically involves loss of type fidelity | ||
| \- both on input and output. --> todo: example needed |
There was a problem hiding this comment.
We may want to mention that most types (except for special types such as Version, PSCredential, SecureString, etc.) are deserialized to a PSObject, which is 'property bag' general type that contains the original type properties but not its methods.
| serialization and deserialization. This typically involves loss of type fidelity | ||
| \- both on input and output. --> todo: example needed | ||
|
|
||
| Thread jobs, by contrast, because they run in a different runspace (thread) in |
There was a problem hiding this comment.
Should use 'session' instead of 'runspace', and 'variable reference' to be consistent.
* Freshen up VS Code doc a bit * rob's comments * Fixed a rendering problem in the TIP block Co-authored-by: Sean Wheeler <[email protected]>
…softDocs#5592) * Fixes MicrosoftDocs#5398 - explain dotnet tool install results * fix typo
mklement0
reviewed
Mar 13, 2020
| \- both on input and output. --> todo: example needed | ||
|
|
||
| Thread jobs, by contrast, because they run in a different runspace (thread) in | ||
| the same process receive $using: variable values as their original, live objects |
There was a problem hiding this comment.
Missing comma: "process>>,<< receive ..."
* Updates all versions * updated info - unavailablity in powershell.exe * updated info - unavailablity in powershell.exe
…84/PowerShell-Docs into 5068_remote_variables_using
|
@PaulHigin @Jawz84 @mklement0 I made some changes based on the feedback. Let me know how this looks. |
|
Closing this PR. The original branch was too stale. |
17 tasks
|
Docs Build status updates of commit c31496f:
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
PR Summary
Fixes #5068
@mklement0 opened this issue because information about 'Using' scope modifier was very limited in the documentation. I have taken his raw material and tried to put it into a more coherent shape that may be suitable for publication.
The information differs from version to version. I have taken this into account in the variations for each version.
I have simplified Michael's original information.
PR Context
Select the type(s) of documents being changed.
Cmdlet reference & about_ topics
Conceptual articles
PR Checklist
WIP:or[ WIP ]to the beginning of thetitle and remove the prefix when the PR is ready.