Update clarify $using and using thread-safe types (#11284)

Author: sdwheeler

reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md

@@ -1,7 +1,7 @@
 ---
 description: Explains the concept of scope in PowerShell and shows how to set and change the scope of elements.
 Locale: en-US
-ms.date: 06/07/2024
+ms.date: 07/22/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_scopes?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Scopes
@@ -60,7 +60,7 @@ hierarchy of child scopes whose root scope is the global scope.
 > Modules have their own session state that's linked to the scope in which the
 > module was imported. All module code runs in a module-specific hierarchy of
 > scopes that has its own root scope. For more information, see the
-> [Modules][02] section of this article.
+> [Modules][03] section of this article.
 
 When a child scope is created, it includes all the aliases and variables that
 have the **AllScope** option, and some automatic variables. This option is
@@ -90,7 +90,7 @@ When a reference is made to a variable, alias, or function, PowerShell searches
 the current scope. If the item isn't found, the parent scope is searched. This
 search is repeated all they way up to the global scope. If a variable is
 private in a parent scope, the search through continues through the scope
-chain. [Example 4][01] shows the effect of a private variable in a scope
+chain. [Example 4][02] shows the effect of a private variable in a scope
 search.
 
 ## PowerShell scopes names
@@ -128,14 +128,14 @@ optional scope modifiers:
   current scope.
 
   > [!NOTE]
-  > `private:` isn't a scope. It's an [option][03] that changes the
+  > `private:` isn't a scope. It's an [option][04] that changes the
   > accessibility of an item outside of the scope in which it's defined.
 
 - `script:` - Specifies that the name exists in the **Script** scope.
   **Script** scope is the nearest ancestor script file's scope or **Global** if
   there is no nearest ancestor script file.
 - `using:` - Used to access variables defined in another scope while running
-  scripts via cmdlets like `Start-Job` and `Invoke-Command`.
+  in remote sessions, background jobs, or thread jobs.
 - `workflow:` - Specifies that the name exists within a workflow. Note:
   Workflows aren't supported in PowerShell v6 and higher.
 - `<variable-namespace>` - A modifier created by a PowerShell **PSDrive**
@@ -266,16 +266,34 @@ Depending on the context, embedded variable values are either independent
 copies of the data in the caller's scope or references to it. In remote and
 out-of-process sessions, they're always independent copies.
 
-For more information, see [about_Remote_Variables][07].
+For more information, see [about_Remote_Variables][08].
 
-In thread sessions, they're passed by reference. This means it's possible to
-modify child scope variables in a different thread. To safely modify variables
-requires thread synchronization.
+A `$using:` reference only expands to a variable's value. If you want to change
+the value of a variable in the caller's scope, you must have a reference to the
+variable itself. You can create a reference to a variable by getting the
+**PSVariable** instance of the variable. The following example show how to
+create a reference and make changes in a thread job.
 
-For more information see:
+```powershell
+$Count = 1
+$refOfCount = Get-Variable Count
+
+Start-ThreadJob {
+    ($using:refOfCount).Value = 2
+} | Receive-Job -Wait -AutoRemoveJob
+
+$Count
+```
 
-- [Start-ThreadJob][11]
-- [ForEach-Object][10]
+```Output
+2
+```
+
+> [!NOTE]
+> This is not a thread-safe operation. You can cause data corruption if you try
+> to change the value from multiple threads at the same time. You should use
+> thread-safe data types or synchronization primitives to protect shared data.
+> For more information, see [Thread-Safe collections][01].
 
 ### Serialization of variable values
 
@@ -387,7 +405,7 @@ Using the call operator is no different than running the script by name.
 & c:\scripts\sample.ps1
 ```
 
-You can read more about the call operator in [about_Operators][06].
+You can read more about the call operator in [about_Operators][07].
 
 To run the `Sample.ps1` script in the local scope type a dot and a space (`. `)
 before the path to the script:
@@ -736,21 +754,21 @@ The `using` scope modifier was introduced in PowerShell 3.0.
 
 ## See also
 
-- [about_Variables][09]
-- [about_Environment_Variables][04]
-- [about_Functions][05]
-- [about_Script_Blocks][08]
-- [Start-ThreadJob][11]
+- [about_Environment_Variables][05]
+- [about_Functions][06]
+- [about_Script_Blocks][09]
+- [about_Variables][10]
+- [Start-ThreadJob][12]
 
 <!-- link references -->
-[01]: #example-4-creating-a-private-variable
-[02]: #modules
-[03]: #private-option
-[04]: about_Environment_Variables.md
-[05]: about_Functions.md
-[06]: about_Operators.md
-[07]: about_Remote_Variables.md
-[08]: about_Script_Blocks.md
-[09]: about_Variables.md
-[10]: xref:Microsoft.PowerShell.Core.ForEach-Object
-[11]: xref:ThreadJob.Start-ThreadJob
+[01]: /dotnet/standard/collections/thread-safe/
+[02]: #example-4-creating-a-private-variable
+[03]: #modules
+[04]: #private-option
+[05]: about_Environment_Variables.md
+[06]: about_Functions.md
+[07]: about_Operators.md
+[08]: about_Remote_Variables.md
+[09]: about_Script_Blocks.md
+[10]: about_Variables.md
+[12]: xref:ThreadJob.Start-ThreadJob

reference/7.2/Microsoft.PowerShell.Core/About/about_Scopes.md

@@ -1,7 +1,7 @@
 ---
 description: Explains the concept of scope in PowerShell and shows how to set and change the scope of elements.
 Locale: en-US
-ms.date: 06/07/2024
+ms.date: 07/22/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_scopes?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Scopes
@@ -60,7 +60,7 @@ hierarchy of child scopes whose root scope is the global scope.
 > Modules have their own session state that's linked to the scope in which the
 > module was imported. All module code runs in a module-specific hierarchy of
 > scopes that has its own root scope. For more information, see the
-> [Modules][02] section of this article.
+> [Modules][03] section of this article.
 
 When a child scope is created, it includes all the aliases and variables that
 have the **AllScope** option, and some automatic variables. This option is
@@ -90,7 +90,7 @@ When a reference is made to a variable, alias, or function, PowerShell searches
 the current scope. If the item isn't found, the parent scope is searched. This
 search is repeated all they way up to the global scope. If a variable is
 private in a parent scope, the search through continues through the scope
-chain. [Example 4][01] shows the effect of a private variable in a scope
+chain. [Example 4][02] shows the effect of a private variable in a scope
 search.
 
 ## PowerShell scopes names
@@ -128,14 +128,14 @@ optional scope modifiers:
   current scope.
 
   > [!NOTE]
-  > `private:` isn't a scope. It's an [option][03] that changes the
+  > `private:` isn't a scope. It's an [option][04] that changes the
   > accessibility of an item outside of the scope in which it's defined.
 
 - `script:` - Specifies that the name exists in the **Script** scope.
   **Script** scope is the nearest ancestor script file's scope or **Global** if
   there is no nearest ancestor script file.
 - `using:` - Used to access variables defined in another scope while running
-  scripts via cmdlets like `Start-Job` and `Invoke-Command`.
+  in remote sessions, background jobs, or thread jobs.
 - `workflow:` - Specifies that the name exists within a workflow. Note:
   Workflows aren't supported in PowerShell v6 and higher.
 - `<variable-namespace>` - A modifier created by a PowerShell **PSDrive**
@@ -266,16 +266,34 @@ Depending on the context, embedded variable values are either independent
 copies of the data in the caller's scope or references to it. In remote and
 out-of-process sessions, they're always independent copies.
 
-For more information, see [about_Remote_Variables][07].
+For more information, see [about_Remote_Variables][08].
 
-In thread sessions, they're passed by reference. This means it's possible to
-modify child scope variables in a different thread. To safely modify variables
-requires thread synchronization.
+A `$using:` reference only expands to a variable's value. If you want to change
+the value of a variable in the caller's scope, you must have a reference to the
+variable itself. You can create a reference to a variable by getting the
+**PSVariable** instance of the variable. The following example show how to
+create a reference and make changes in a thread job.
 
-For more information see:
+```powershell
+$Count = 1
+$refOfCount = Get-Variable Count
+
+Start-ThreadJob {
+    ($using:refOfCount).Value = 2
+} | Receive-Job -Wait -AutoRemoveJob
+
+$Count
+```
 
-- [Start-ThreadJob][11]
-- [ForEach-Object][10]
+```Output
+2
+```
+
+> [!NOTE]
+> This is not a thread-safe operation. You can cause data corruption if you try
+> to change the value from multiple threads at the same time. You should use
+> thread-safe data types or synchronization primitives to protect shared data.
+> For more information, see [Thread-Safe collections][01].
 
 ### Serialization of variable values
 
@@ -387,7 +405,7 @@ Using the call operator is no different than running the script by name.
 & c:\scripts\sample.ps1
 ```
 
-You can read more about the call operator in [about_Operators][06].
+You can read more about the call operator in [about_Operators][07].
 
 To run the `Sample.ps1` script in the local scope type a dot and a space (`. `)
 before the path to the script:
@@ -736,21 +754,23 @@ The `using` scope modifier was introduced in PowerShell 3.0.
 
 ## See also
 
-- [about_Variables][09]
-- [about_Environment_Variables][04]
-- [about_Functions][05]
-- [about_Script_Blocks][08]
-- [Start-ThreadJob][11]
+- [about_Environment_Variables][05]
+- [about_Functions][06]
+- [about_Script_Blocks][09]
+- [about_Variables][10]
+- [ForEach-Object][11]
+- [Start-ThreadJob][12]
 
 <!-- link references -->
-[01]: #example-4-creating-a-private-variable
-[02]: #modules
-[03]: #private-option
-[04]: about_Environment_Variables.md
-[05]: about_Functions.md
-[06]: about_Operators.md
-[07]: about_Remote_Variables.md
-[08]: about_Script_Blocks.md
-[09]: about_Variables.md
-[10]: xref:Microsoft.PowerShell.Core.ForEach-Object
-[11]: xref:ThreadJob.Start-ThreadJob
+[01]: /dotnet/standard/collections/thread-safe/
+[02]: #example-4-creating-a-private-variable
+[03]: #modules
+[04]: #private-option
+[05]: about_Environment_Variables.md
+[06]: about_Functions.md
+[07]: about_Operators.md
+[08]: about_Remote_Variables.md
+[09]: about_Script_Blocks.md
+[10]: about_Variables.md
+[11]: xref:Microsoft.PowerShell.Core.ForEach-Object
+[12]: xref:ThreadJob.Start-ThreadJob