Fix #4508 - update docs for -ShellId (#4509)

* Fix #4508 - update docs for -ShellId

* Update reference/3.0/Microsoft.PowerShell.Core/About/about_Requires.md

Co-Authored-By: Steve Lee <[email protected]>

* review feedback

reference/3.0/Microsoft.PowerShell.Core/About/about_Requires.md

@@ -1,5 +1,5 @@
 ---
-ms.date:  01/03/2018
+ms.date:  07/01/2019
 schema:  2.0.0
 locale:  en-us
 keywords:  powershell,cmdlet
@@ -8,58 +8,57 @@ title:  about_Requires
 # About Requires
 
 ## Short description
-
 Prevents a script from running without the required elements.
 
 ## Long description
 
-The `#Requires` statement prevents a script from running unless the Windows
-PowerShell version, modules, snap-ins, and module and snap-in version
-prerequisites are met. If the prerequisites are not met, Windows PowerShell
+The `#Requires` statement prevents a script from running unless the
+PowerShell version, modules (and version), or snap-ins (and version)
+prerequisites are met. If the prerequisites are not met, PowerShell
 does not run the script.
 
 ### Syntax
 
-```powershell
+```
 #Requires -Version <N>[.<n>]
 #Requires -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
 #Requires -Modules { <Module-Name> | <Hashtable> }
-#Requires -ShellId <ShellId>
+#Requires -ShellId <ShellId> -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
 ```
 
 ### Rules for use
 
-- A script can include more than one `#Requires` statement.
-- The `#Requires` statements can appear on any line in a script.
-  
-  Placing a `#Requires` statement inside a function does NOT limit its scope.
-  All `#Requires` statements are always applied globally, and must be met,
-  before the script can execute.
-  > [!WARNING]
-  > Even though a `#Requires` statement can appear on any line in a script,
-  > its position in a script does not affect the sequence of its application.
-  >
-  > The global state the `#Requires` statement presents must be met before
-  > script execution.
-  
-  Example:
+A script can include more than one `#Requires` statement. The `#Requires`
+statements can appear on any line in a script.
+
+Placing a `#Requires` statement inside a function does NOT limit its scope. All
+`#Requires` statements are always applied globally, and must be met, before the
+script can execute.
+
+> [!WARNING]
+> Even though a `#Requires` statement can appear on any line in a script, its
+> position in a script does not affect the sequence of its application. The
+> global state the `#Requires` statement presents must be met before script
+> execution.
+
+Example:
 
   ```powershell
   Get-Module Hyper-V | Remove-Module
   #Requires -Modules Hyper-V
   ```
 
-  You might think that the above code should not run because the required
-  module was removed before the `#Requires` statement. However, the `#Requires`
-  state had to be met before the script could even execute. Then the first line
-  of the script invalidated the required state.
+You might think that the above code should not run because the required module
+was removed before the `#Requires` statement. However, the `#Requires` state
+had to be met before the script could even execute. Then the first line of the
+script invalidated the required state.
 
 ### Parameters
 
 #### -Version \<N\>[.\<n\>]
 
-Specifies the minimum version of Windows PowerShell that the script requires.
-Enter a major version number and optional minor version number.
+Specifies the minimum version of PowerShell that the script requires. Enter a
+major version number and optional minor version number.
 
 For example:
 
@@ -69,8 +68,8 @@ For example:
 
 #### -PSSnapin \<PSSnapin-Name\> [-Version \<N\>[.\<n\>]]
 
-Specifies a Windows PowerShell snap-in that the script requires. Enter the
-snap-in name and an optional version number.
+Specifies a PowerShell snap-in that the script requires. Enter the snap-in name
+and an optional version number.
 
 For example:
 
@@ -80,45 +79,48 @@ For example:
 
 #### -Modules \<Module-Name\> | \<Hashtable\>
 
-Specifies Windows PowerShell modules that the script requires. Enter the
-module name and an optional version number. The Modules parameter is
-introduced in Windows PowerShell 3.0.
+Specifies PowerShell modules that the script requires. Enter the module name
+and an optional version number.
+
+If the required modules are not in the current session, PowerShell imports
+them. If the modules cannot be imported, PowerShell throws a terminating error.
 
-If the required modules are not in the current session, Windows PowerShell
-imports them. If the modules cannot be imported, Windows PowerShell throws a
-terminating error.
+For each module, type the module name (\<String\>) or a hash table. The value
+can be a combination of strings and hash tables. The hash table has the
+following keys.
 
-For each module, type the module name (\<String\>) or a hash table with the
-following keys. The value can be a combination of strings and hash tables.
+- `ModuleName` - **Required** Specifies the module name.
+- `ModuleVersion` - Specifies a minimum acceptable version of the module.
+- `GUID` - **Optional** Specifies the GUID of the module.
 
-- `ModuleName` - __[Required]__ Specifies the module name.
-- `ModuleVersion` - __[Required]__ Specifies a minimum acceptable version of the module.
-- `GUID` - __[Optional]__ Specifies the GUID of the module.
+For example:
 
-For example,
+Require that `Hyper-V` (version `1.1` or greater) is installed.
 
 ```powershell
 #Requires -Modules @{ ModuleName="Hyper-V"; ModuleVersion="1.1" }
 ```
 
-Requires that `Hyper-V` (version `1.1` or greater) is installed.
+Require that any version of `PSScheduledJob` and `PSWorkflow` are installed.
 
 ```powershell
 #Requires -Modules PSWorkflow, PSScheduledJob
 ```
 
-Requires that any version of `PSScheduledJob` and `PSWorkflow` are installed.
-
 #### -ShellId
 
-Specifies the shell that the script requires. Enter the shell ID.
+Specifies the shell that the script requires. Enter the shell ID. If you use
+the **ShellId** parameter you must also include the **PSSnapin** parameter. You
+can find current ShellId by querying `$ShellId` automatic variable.
 
-For example,
+For example:
 
 ```powershell
-#Requires -ShellId MyLocalShell
+#Requires -ShellId MyLocalShell -PSSnapin Microsoft.PowerShell.Core
 ```
 
+> [!NOTE]
+> This parameter is intended for use in mini-shells, which have been deprecated.
 You can find current ShellId by querying `$ShellId` automatic variable.
 
 ### Examples
@@ -155,4 +157,4 @@ always a snap-in.
 
 [about_PSSnapins](about_PSSnapins.md)
 
-[Get-PSSnapin](../Get-PSSnapin.md)
+[Get-PSSnapin](../Get-PSSnapin.md)

reference/4.0/Microsoft.PowerShell.Core/About/about_Requires.md

@@ -1,5 +1,5 @@
 ---
-ms.date:  01/03/2018
+ms.date:  07/01/2019
 schema:  2.0.0
 locale:  en-us
 keywords:  powershell,cmdlet
@@ -8,70 +8,69 @@ title:  about_Requires
 # About Requires
 
 ## Short description
-
 Prevents a script from running without the required elements.
 
 ## Long description
 
-The `#Requires` statement prevents a script from running unless the Windows
-PowerShell version, modules, snap-ins, and module and snap-in version
-prerequisites are met. If the prerequisites are not met, Windows PowerShell
+The `#Requires` statement prevents a script from running unless the
+PowerShell version, modules (and version), or snap-ins (and version)
+prerequisites are met. If the prerequisites are not met, PowerShell
 does not run the script.
 
 ### Syntax
 
-```powershell
+```
 #Requires -Version <N>[.<n>]
 #Requires -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
 #Requires -Modules { <Module-Name> | <Hashtable> }
-#Requires -ShellId <ShellId>
+#Requires -ShellId <ShellId> -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
 #Requires -RunAsAdministrator
 ```
 
 ### Rules for use
 
-- A script can include more than one `#Requires` statement.
-- The `#Requires` statements can appear on any line in a script.
-  
-  Placing a `#Requires` statement inside a function does NOT limit its scope.
-  All `#Requires` statements are always applied globally, and must be met,
-  before the script can execute.
-  > [!WARNING]
-  > Even though a `#Requires` statement can appear on any line in a script,
-  > its position in a script does not affect the sequence of its application.
-  >
-  > The global state the `#Requires` statement presents must be met before
-  > script execution.
-  
-  Example:
+A script can include more than one `#Requires` statement. The `#Requires`
+statements can appear on any line in a script.
+
+Placing a `#Requires` statement inside a function does NOT limit its scope. All
+`#Requires` statements are always applied globally, and must be met, before the
+script can execute.
+
+> [!WARNING]
+> Even though a `#Requires` statement can appear on any line in a script, its
+> position in a script does not affect the sequence of its application. The
+> global state the `#Requires` statement presents must be met before script
+> execution.
+
+Example:
 
   ```powershell
   Get-Module Hyper-V | Remove-Module
   #Requires -Modules Hyper-V
   ```
 
-  You might think that the above code should not run because the required
-  module was removed before the `#Requires` statement. However, the `#Requires`
-  state had to be met before the script could even execute. Then the first line
-  of the script invalidated the required state.
+You might think that the above code should not run because the required module
+was removed before the `#Requires` statement. However, the `#Requires` state
+had to be met before the script could even execute. Then the first line of the
+script invalidated the required state.
 
 ### Parameters
 
 #### -Version \<N\>[.\<n\>]
 
-Specifies the minimum version of Windows PowerShell that the script requires.
-Enter a major version number and optional minor version number.
+Specifies the minimum version of PowerShell that the script requires. Enter a
+major version number and optional minor version number.
 
 For example:
 
 ```powershell
-#Requires -Version 3.0
+#Requires -Version 4.0
 ```
 
 #### -PSSnapin \<PSSnapin-Name\> [-Version \<N\>[.\<n\>]]
 
-Specifies a Windows PowerShell snap-in that the script requires. Enter the
-snap-in name and an optional version number.
+Specifies a PowerShell snap-in that the script requires. Enter the snap-in name
+and an optional version number.
 
 For example:
 
@@ -81,46 +80,48 @@ For example:
 
 #### -Modules \<Module-Name\> | \<Hashtable\>
 
-Specifies Windows PowerShell modules that the script requires. Enter the
-module name and an optional version number. The Modules parameter is
-introduced in Windows PowerShell 3.0.
+Specifies PowerShell modules that the script requires. Enter the module name
+and an optional version number.
 
-If the required modules are not in the current session, Windows PowerShell
-imports them. If the modules cannot be imported, Windows PowerShell throws a
-terminating error.
+If the required modules are not in the current session, PowerShell imports
+them. If the modules cannot be imported, PowerShell throws a terminating error.
 
-For each module, type the module name (\<String\>) or a hash table with the
-following keys. The value can be a combination of strings and hash tables.
+For each module, type the module name (\<String\>) or a hash table. The value
+can be a combination of strings and hash tables. The hash table has the
+following keys.
 
-- `ModuleName` - __[Required]__ Specifies the module name.
-- `ModuleVersion` - __[Required]__ Specifies a minimum acceptable version of the module.
-- `GUID` - __[Optional]__ Specifies the GUID of the module.
+- `ModuleName` - **Required** Specifies the module name.
+- `ModuleVersion` - Specifies a minimum acceptable version of the module.
+- `GUID` - **Optional** Specifies the GUID of the module.
 
-For example,
+For example:
+
+Require that `Hyper-V` (version `1.1` or greater) is installed.
 
 ```powershell
 #Requires -Modules @{ ModuleName="Hyper-V"; ModuleVersion="1.1" }
 ```
 
-Requires that `Hyper-V` (version `1.1` or greater) is installed.
+Require that any version of `PSScheduledJob` and `PSWorkflow` are installed.
 
 ```powershell
 #Requires -Modules PSWorkflow, PSScheduledJob
 ```
 
-Requires that any version of `PSScheduledJob` and `PSWorkflow` are installed.
-
 #### -ShellId
 
-Specifies the shell that the script requires. Enter the shell ID.
+Specifies the shell that the script requires. Enter the shell ID. If you use
+the **ShellId** parameter you must also include the **PSSnapin** parameter. You
+can find current ShellId by querying `$ShellId` automatic variable.
 
-For example,
+For example:
 
 ```powershell
-#Requires -ShellId MyLocalShell
+#Requires -ShellId MyLocalShell -PSSnapin Microsoft.PowerShell.Core
 ```
 
-You can find current ShellId by querying `$ShellId` automatic variable.
+> [!NOTE]
+> This parameter is intended for use in mini-shells, which have been deprecated.
 
 #### -RunAsAdministrator
 
@@ -129,7 +130,7 @@ that the Windows PowerShell session in which you are running the script must
 be started with elevated user rights (Run as Administrator).
 The RunAsAdministrator parameter is introduced in Windows PowerShell 4.0.
 
-For example,
+For example:
 
 ```powershell
 #Requires -RunAsAdministrator
@@ -153,14 +154,6 @@ Param
 ...
 ```
 
-### Notes
-
-In Windows PowerShell 3.0, the Windows PowerShell Core packages appear as
-modules in sessions started by using the InitialSessionState.CreateDefault2
-method, such as sessions started in the Windows PowerShell console. Otherwise,
-they appear as snap-ins. The exception is Microsoft.PowerShell.Core, which is
-always a snap-in.
-
 ## See also
 
 [about_Automatic_Variables](about_Automatic_Variables.md)