diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/About.md b/reference/5.1/Microsoft.PowerShell.Core/About/About.md index e691c9239bd1..b00906ae222e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/About.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/About.md @@ -145,7 +145,8 @@ Describes the PowerShell debugger. ### [about_DesiredStateConfiguration](about_DesiredStateConfiguration.md) -Provides a brief introduction to the PowerShell Desired State Configuration (DSC) feature. +Provides a brief introduction to the PowerShell Desired State Configuration +(DSC) feature. ### [about_Do](about_Do.md) @@ -221,7 +222,8 @@ Describes the attribute that makes a function work like a compiled cmdlet. ### [about_Functions_OutputTypeAttribute](about_Functions_OutputTypeAttribute.md) -Describes an attribute that reports the type of object that the function returns. +Describes an attribute that reports the type of object that the function +returns. ### [about_Functions](about_Functions.md) @@ -370,7 +372,8 @@ Combining commands into pipelines in the PowerShell ### [about_PowerShell_exe](about_PowerShell_exe.md) -Explains how to use the `powershell.exe` command-line interface. Displays the command-line parameters and describes the syntax. +Explains how to use the `powershell.exe` command-line interface. Displays the +command-line parameters and describes the syntax. ### [about_PowerShell_Ise_exe](about_PowerShell_Ise_exe.md) @@ -630,7 +633,8 @@ Describes new features that are included in Windows PowerShell 5.1. ### [about_Windows_PowerShell_ISE](about_Windows_PowerShell_ISE.md) -Describes the features and system requirements of Windows PowerShell Integrated Scripting Environment (ISE). +Describes the features and system requirements of Windows PowerShell Integrated +Scripting Environment (ISE). ### [about_Windows_RT](about_Windows_RT.md) @@ -638,12 +642,16 @@ Explains limitations of Windows PowerShell 4.0 on Windows RT 8.1. ### [about_WMI_Cmdlets](about_WMI_Cmdlets.md) -Provides background information about Windows Management Instrumentation (WMI) and Windows PowerShell. +Provides background information about Windows Management Instrumentation (WMI) +and Windows PowerShell. ### [about_WMI](about_WMI.md) -Windows Management Instrumentation (WMI) uses the Common Information Model (CIM) to represent systems, applications, networks, devices, and other manageable components of the modern enterprise. +Windows Management Instrumentation (WMI) uses the Common Information Model +(CIM) to represent systems, applications, networks, devices, and other +manageable components of the modern enterprise. ### [about_WQL](about_WQL.md) -Describes WMI Query Language (WQL), which can be used to get WMI objects in Windows PowerShell. +Describes WMI Query Language (WQL), which can be used to get WMI objects in +Windows PowerShell. diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSession_Details.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSession_Details.md index 566a5d6f1c22..3ed6b5c6fdb2 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSession_Details.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSession_Details.md @@ -11,80 +11,77 @@ title: about_PSSession_Details ## Short description -Provides detailed information about Windows PowerShell sessions and the +Provides detailed information about PowerShell sessions and the role they play in remote commands. ## Long description -A session is an environment in which Windows PowerShell runs. A session is -created for you whenever you start Windows PowerShell. You can create -additional sessions, called "Windows PowerShell sessions" or "PSSessions" -on your computer or another computer. +A session is an environment in which PowerShell runs. A session is created for +you whenever you start PowerShell. You can create additional sessions, called +"PowerShell sessions" or "PSSessions" on your computer or another computer. -Unlike the sessions that Windows PowerShell creates for you, you control -and manage the PSSessions that you create. +Unlike the sessions that PowerShell creates for you, you control and manage the +PSSessions that you create. PSSessions play an important role in remote computing. When you create a -PSSession that is connected to a remote computer, Windows PowerShell -establishes a persistent connection to the remote computer to support the -PSSession. You can use the PSSession to run a series of commands, -functions, and scripts that share data. +PSSession that is connected to a remote computer, PowerShell establishes a +persistent connection to the remote computer to support the PSSession. You can +use the PSSession to run a series of commands, functions, and scripts that +share data. -This topic provides detailed information about sessions and PSSessions -in Windows PowerShell. For basic information about the tasks that you -can perform with sessions, see [about_PSSessions](about_PSSessions.md). +This topic provides detailed information about sessions and PSSessions in +PowerShell. For basic information about the tasks that you can perform with +sessions, see [about_PSSessions][01]. ## About Sessions -Technically, a session is an execution environment in which Windows -PowerShell runs. Each session includes an instance of the -System.Management.Automation engine and a host program in which Windows -PowerShell runs. The host can be the familiar Windows PowerShell console -or another program that runs commands, such as Cmd.exe, or a program built -to host Windows PowerShell, such as Windows PowerShell Integrated Scripting -Environment (ISE). From a Windows perspective, a session is a Windows +Technically, a session is an execution environment in which PowerShell runs. +Each session includes an instance of the System.Management.Automation engine +and a host program in which PowerShell runs. The host can be the familiar +PowerShell console or another program that runs commands, such as Cmd.exe, or +a program built to host PowerShell, such as Windows PowerShell Integrated +Scripting Environment (ISE). From a Windows perspective, a session is a Windows process on the target computer. -Each session is configured independently. It includes its own properties, -its own execution policy, and its own profiles. The environment that exists -when the session is created persists for its lifetime even if you change -the environment on the computer. All sessions are created in a global -scope, even sessions that you create in a script. +Each session is configured independently. It includes its own properties, its +own execution policy, and its own profiles. The environment that exists when +the session is created persists for its lifetime even if you change the +environment on the computer. All sessions are created in a global scope, even +sessions that you create in a script. -You can run only one command (or command pipeline) in a session at one -time. A second command run synchronously (one at a time) waits up to four -minutes for the first command to be completed. A second command run -asynchronously (concurrently) fails. +You can run only one command (or command pipeline) in a session at one time. +A second command run synchronously (one at a time) waits up to four minutes for +the first command to be completed. A second command run asynchronously +(concurrently) fails. ## About PSSessions -A session is created each time that you start Windows PowerShell. And, -Windows PowerShell creates temporary sessions to run individual commands. -However, you can also create sessions (called "Windows PowerShell sessions" -or "PSSessions") that you control and manage. +A session is created each time that you start PowerShell. And, PowerShell +creates temporary sessions to run individual commands. However, you can also +create sessions (called "PowerShell sessions" or "PSSessions") that you control +and manage. PSSessions are critical to remote commands. If you use the **ComputerName** -parameter of the `Invoke-Command` or `Enter-PSSession` cmdlets, Windows -PowerShell establishes a temporary session to run the command and then -closes the session as soon as the command or the interactive session -is complete. +parameter of the `Invoke-Command` or `Enter-PSSession` cmdlets, PowerShell +establishes a temporary session to run the command and then closes the session +as soon as the command or the interactive session is complete. -However, if you use the `New-PSSession` cmdlet to create a PSSession, Windows -PowerShell establishes a persistent session on the remote computer in which -you can run multiple commands or interactive sessions. The PSSessions that -you create remain open and available for use until you delete them or until -you close the session in which they were created. +However, if you use the `New-PSSession` cmdlet to create a PSSession, +PowerShell establishes a persistent session on the remote computer in which you +can run multiple commands or interactive sessions. The PSSessions that you +create remain open and available for use until you delete them or until you +close the session in which they were created. When you create a PSSession on a remote computer, the system creates a -PowerShell process on the remote computer and establishes a connection -from the local computer to the process on the remote computer. When you -create a PSSession on the local computer, both the new process and the -connections are created on the local computer. +PowerShell process on the remote computer and establishes a connection from the +local computer to the process on the remote computer. When you create a +PSSession on the local computer, both the new process and the connections are +created on the local computer. ## When Do I Need a PSSession? -The `Invoke-Command` and `Enter-PSSession` cmdlets have both **ComputerName** and -**Session** parameters. You can use either to run a remote command. +The `Invoke-Command` and `Enter-PSSession` cmdlets have both **ComputerName** +and **Session** parameters. You can use either to run a remote command. Use the **ComputerName** parameter to run a single command or a series of unrelated commands on one or many computers. @@ -93,12 +90,11 @@ To run commands that share data, you need a persistent connection to the remote computer. In that case, create a PSSession, and then use the **Session** parameter to run commands in the PSSession. -Many other cmdlets that get data from remote computers, such as -`Get-Process`, `Get-Service`, `Get-EventLog`, and `Get-WmiObject` have only a -**ComputerName** parameter. They use technologies other than Windows PowerShell -remoting to gather data remotely. These cmdlets do not have a **Session** -parameter, but you can use the `Invoke-Command` cmdlet to run these commands -in a PSSession. +Many other cmdlets that get data from remote computers, such as `Get-Process`, +`Get-Service`, `Get-EventLog`, and `Get-WmiObject` have only a **ComputerName** +parameter. They use technologies other than PowerShell remoting to gather data +remotely. These cmdlets do not have a **Session** parameter, but you can use +the `Invoke-Command` cmdlet to run these commands in a PSSession. ## How Do I Create a PSSession? @@ -108,115 +104,101 @@ To create a PSSession, use the `New-PSSession` cmdlet. You can use ## Can I Create a PSSession on Any Computer? To create a PSSession that is connected to a remote computer, the computer -must be configured for remoting in Windows PowerShell. The current user -must be a member of the Administrators group on the remote computer, or -the current user must be able to supply the credentials of a member of -the Administrators group. For more information, -see [about_Remote_Requirements](about_Remote_Requirements.md). +must be configured for remoting in PowerShell. The current user must be a +member of the Administrators group on the remote computer, or the current user +must be able to supply the credentials of a member of the Administrators group. +For more information, see [about_Remote_Requirements][02]. ## Can I See My PSSessions in Other Sessions? -Beginning in Windows PowerShell 3.0, the **ComputerName** -parameter of the `Get-PSSession` cmdlet gets PSSessions -that you created on the specified remote computers. +Beginning in Windows PowerShell 3.0, the **ComputerName** parameter of the +`Get-PSSession` cmdlet gets PSSessions that you created on the specified +remote computers. -Active PSSessions are maintained on the remote computer -(the "server-side" of a connection) and you can get them -from any session on any computer. +Active PSSessions are maintained on the remote computer (the "server-side" of +a connection) and you can get them from any session on any computer. -For example, if you create a PSSession from the Server01 -computer to the Server02 computer, and then switch to the -Server03 computer, you can use a command like the following -one to get the session. +For example, if you create a PSSession from the Server01 computer to the +Server02 computer, and then switch to the Server03 computer, you can use a +command like the following one to get the session. ```powershell Get-PSSession -ComputerName Server02 ``` -Even if you disconnect from the session, the session is -maintained on the remote computer until you delete it or it -times out. +Even if you disconnect from the session, the session is maintained on the +remote computer until you delete it or it times out. -In Windows PowerShell 2.0, you can get only the PSSessions -that you have created in the current session. You cannot get -PSSessions that you created in other sessions. - -For more information, see [Get-PSSession](xref:Microsoft.PowerShell.Core.Get-PSSession). +In Windows PowerShell 2.0, you can get only the PSSessions that you have +created in the current session. You cannot get PSSessions that you created in +other sessions. For more information, see [Get-PSSession][03]. ## Can I See the PSSessions That Others Have Created on My Computer? -You can get and manage only the PSSessions that others have created -only if you can supply the credentials of the user who created the -PSSession or the session configuration that the PSSession uses -includes RunAs credentials. Otherwise, you can get, connect to, use, -and manage only the PSSessions that you created. +You can get and manage only the PSSessions that others have created only if you +can supply the credentials of the user who created the PSSession or the session +configuration that the PSSession uses includes RunAs credentials. Otherwise, +you can get, connect to, use, and manage only the PSSessions that you created. ## Can I Connect to a PSSession From a Different Computer? -Beginning in Windows PowerShell 3.0, PSSessions are independent -of the sessions in which they were created. Active PSSessions -are maintained on the computer at the remote or "server-side" of -a connection. +Beginning in Windows PowerShell 3.0, PSSessions on Windows computers are +independent of the sessions in which they were created. Active PSSessions +are maintained on the computer at the remote or "server-side" of a connection. -You can use the `Disconnect-PSSession` cmdlet to disconnect -from a PSSession. The PSSession is disconnected from the +On a Windows computer, you can use the `Disconnect-PSSession` cmdlet to +disconnect from a PSSession. The PSSession is disconnected from the local session, but is maintained on the remote computer. -Commands continue to run in the disconnected PSSession. You -can close Windows PowerShell and shut down the originating computer -without interrupting the PSSession. - -Then, even hours later, you can use the `Get-PSSession` cmdlet to -get the PSSession and the `Connect-PSSession` cmdlet to connect to the -PSSession from a new session on a different computer. +Commands continue to run in the disconnected PSSession. You can close +PowerShell and shut down the originating computer without interrupting the +PSSession. -For more information, see [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md). +Then, even hours later, you can use the `Get-PSSession` cmdlet to get the +PSSession and the `Connect-PSSession` cmdlet to connect to the PSSession from +a new session on a different Windows computer. For more information, see +[about_Remote_Disconnected_Sessions][04]. ## What Happens to My PSSession if My Computer Stops? -Disconnected PSSessions are independent of the sessions -in which they were created. If you disconnect a PSSession -and then close the originating computer, the PSSession is -maintained on the remote computer. - -In addition, Windows PowerShell attempts to recover active -PSSessions that are disconnected unintentionally, such as -by a computer reboot, a temporary power outage or network -disruption. Windows PowerShell attempts to maintain or recover -the PSSession to an Opened state, if the originating session -is still available, or to a disconnected state if it is not. +Disconnected PSSessions are independent of the sessions in which they were +created. If you disconnect a PSSession and then close the originating computer, +the PSSession is maintained on the remote computer. -An "active" PSSession is one that is running commands. If -a PSSession is connected (not disconnected) and commands are -running in the PSSession when the connected session closes, -Windows PowerShell attempts to maintain the PSSession on the -remote computer. However, if no commands are running in the -PSSession, Windows PowerShell closes the PSSession when the -connected session closes. +In addition, PowerShell attempts to recover active PSSessions that are +disconnected unintentionally, such as by a computer reboot, a temporary power +outage or network disruption. PowerShell attempts to maintain or recover the +PSSession to an Opened state, if the originating session is still available, or +to a disconnected state if it is not. -For more information, see [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md). +An "active" PSSession is one that is running commands. If a PSSession is +connected (not disconnected) and commands are running in the PSSession when the +connected session closes, PowerShell attempts to maintain the PSSession on the +remote computer. However, if no commands are running in the PSSession, +PowerShell closes the PSSession when the connected session closes. For more +information, see [about_Remote_Disconnected_Sessions][04]. ## Can I Run a Background Job in a PSSession? -Yes. A background job is a command that runs asynchronously in the -background without interacting with the current session. When you submit -a command to start a job, the command returns a job object, but the job -continues to run in the background until it is complete. +Yes. A background job is a command that runs asynchronously in the background +without interacting with the current session. When you submit a command to +start a job, the command returns a job object, but the job continues to run in +the background until it is complete. To start a background job on a local computer, use the `Start-Job` command. You can run the background job in a temporary connection (by using the -**ComputerName** parameter) or in a PSSession (by using the **Session** parameter). +**ComputerName** parameter) or in a PSSession (by using the **Session** +parameter). To start a background job on a remote computer, use the `Invoke-Command` -cmdlet with its **AsJob** parameter, or use the `Invoke-Command` cmdlet to run a -`Start-Job` command on a remote computer. When using the **AsJob** parameter, +cmdlet with its **AsJob** parameter, or use the `Invoke-Command` cmdlet to run +a `Start-Job` command on a remote computer. When using the **AsJob** parameter, you can use the **ComputerName** or **Session** parameters. When using `Invoke-Command` to run a `Start-Job` command, you must run the -command in a PSSession. If you use the **ComputerName** parameter, Windows -PowerShell ends the connection when the job object returns, and the job is -interrupted. +command in a PSSession. If you use the **ComputerName** parameter, PowerShell +ends the connection when the job object returns, and the job is interrupted. -For more information, see [about_Jobs](about_Jobs.md). +For more information, see [about_Jobs][05]. ## Can I Run an Interactive Session? @@ -226,15 +208,15 @@ type run on the remote computer, just as if you typed them directly on the remote computer. You can run an interactive session in a temporary session (by using the -**ComputerName** parameter) or in a PSSession (by using the **Session** parameter). -If you use a PSSession, the PSSession retains the data from previous -commands, and the PSSession retains any data generated during the +**ComputerName** parameter) or in a PSSession (by using the **Session** +parameter). If you use a PSSession, the PSSession retains the data from +previous commands, and the PSSession retains any data generated during the interactive session for use in later commands. When you end the interactive session, the PSSession remains open and available for use. -For more information, see [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) and [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession). +For more information, see [Enter-PSSession][06] and [Exit-PSSession][07]. ## Must I Delete the PSSessions? @@ -247,9 +229,9 @@ in use. To delete PSSessions, use the `Remove-PSSession` cmdlet. It deletes the PSSessions and releases all of the resources that they were using. -You can also use the **IdleTimeOut** parameter of `New-PSSessionOption` to close -an idle PSSession after an interval that you specify. For more information, -see [New-PSSessionOption](xref:Microsoft.PowerShell.Core.New-PSSessionOption). +You can also use the **IdleTimeOut** parameter of `New-PSSessionOption` to +close an idle PSSession after an interval that you specify. For more +information, see [New-PSSessionOption][08]. If you save a PSSession object in a variable and then delete the PSSession or let it time out, the variable still contains the PSSession object, but @@ -258,19 +240,33 @@ the PSSession is not active and cannot be used or repaired. ## Are All Sessions and PSSessions Alike? No. Developers can create custom sessions that include only selected -providers and cmdlets. If a command works in one session but not in -another, it might be because the session is restricted. +providers and cmdlets. If a command works in one session but not in another, +it might be because the session is restricted. ## See also -- [about_Jobs](about_Jobs.md) -- [about_PSSessions](about_PSSessions.md) -- [about_Remote](about_Remote.md) -- [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md) -- [about_Remote_Requirements](about_Remote_Requirements.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) -- [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) -- [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession) -- [Get-PSSession](xref:Microsoft.PowerShell.Core.Get-PSSession) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) -- [Remove-PSSession](xref:Microsoft.PowerShell.Core.Remove-PSSession) +- [about_Jobs][05] +- [about_PSSessions][01] +- [about_Remote][09] +- [about_Remote_Disconnected_Sessions][04] +- [about_Remote_Requirements][02] +- [Invoke-Command][10] +- [Enter-PSSession][06] +- [Exit-PSSession][07] +- [Get-PSSession][03] +- [New-PSSession][11] +- [Remove-PSSession][12] + + +[01]: about_PSSessions.md +[02]: about_Remote_Requirements.md +[03]: xref:Microsoft.PowerShell.Core.Get-PSSession +[04]: about_Remote_Disconnected_Sessions.md +[05]: about_Jobs.md +[06]: xref:Microsoft.PowerShell.Core.Enter-PSSession +[07]: xref:Microsoft.PowerShell.Core.Exit-PSSession +[08]: xref:Microsoft.PowerShell.Core.New-PSSessionOption +[09]: about_Remote.md +[10]: xref:Microsoft.PowerShell.Core.Invoke-Command +[11]: xref:Microsoft.PowerShell.Core.New-PSSession +[12]: xref:Microsoft.PowerShell.Core.Remove-PSSession diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSessions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSessions.md index 6eb7e615f5b0..3164c96a966d 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSessions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSessions.md @@ -11,78 +11,75 @@ title: about_PSSessions ## Short description -Describes Windows PowerShell sessions (PSSessions) and explains how to -establish a persistent connection to a remote computer. +Describes PowerShell sessions (PSSessions) and explains how to establish a +persistent connection to a remote computer. ## Long description -To run Windows PowerShell commands on a remote computer, you can use the -**ComputerName** parameter of a cmdlet, or you can create a Windows PowerShell -session (PSSession) and run commands in the PSSession. +To run PowerShell commands on a remote computer, you can use the +**ComputerName** parameter of a cmdlet, or you can create a PowerShell session +(PSSession) and run commands in the PSSession. -When you create a PSSession, Windows PowerShell establishes a persistent -connection to the remote computer. Use a PSSession to run a series of related -commands on a remote computer. Commands that run in the same PSSession can -share data, such as the values of variables, aliases, and functions. +When you create a PSSession, PowerShell establishes a persistent connection to +the remote computer. Use a PSSession to run a series of related commands on a +remote computer. Commands that run in the same PSSession can share data, such +as the values of variables, aliases, and functions. You can also create a PSSession on the local computer and run commands in it. -A local PSSession uses the Windows PowerShell remoting infrastructure to -create and maintain the PSSession. +A local PSSession uses the PowerShell remoting infrastructure to create and +maintain the PSSession. -Beginning in Windows PowerShell 3.0, PSSessions are independent of the -sessions in which they are created. Active PSSessions are maintained on the -remote computer (or the computer at the remote end or "server-side" of the -connection). As a result, you can disconnect from the PSSession and reconnect -to it at a later time from the same computer or from a different computer. +Beginning in Windows PowerShell 3.0, PSSessions on Windows are independent +of the sessions in which they are created. Active PSSessions are maintained +on the remote computer (or the computer at the remote end or "server-side" +of the connection). As a result, on Windows you can disconnect from a PSSession +on a remote Windows computer and reconnect to it at a later time from the +same computer or from a different Windows computer. This topic explains how to create, use, get, and delete PSSessions. For more -advanced information, see -[about_PSSession_Details](about_PSSession_Details.md). +advanced information, see [about_PSSession_Details][01]. -Note: PSSessions use the Windows PowerShell remoting infrastructure. To use -PSSessions, the local and remote computers must be configured for remoting. -For more information, see -[about_Remote_Requirements](about_Remote_Requirements.md). +Note: PSSessions use the PowerShell remoting infrastructure. To use PSSessions, +the local and remote computers must be configured for remoting. For more +information, see [about_Remote_Requirements][02]. In Windows Vista and later versions of Windows, to create a PSSession on a -local computer, you must start Windows PowerShell with the "Run as -administrator" option. +local computer, you must start PowerShell with the "Run as administrator" +option. ## What Is a Session? -A session is an environment in which Windows PowerShell runs. +A session is an environment in which PowerShell runs. -Each time you start Windows PowerShell, a session is created for you, and you -can run commands in the session. You can also add items to your session, such -as modules and snap-ins, and you can create items, such as variables, -functions, and aliases. These items exist only in the session and are deleted -when the session ends. +Each time you start PowerShell, a session is created for you, and you can run +commands in the session. You can also add items to your session, such as +modules and snap-ins, and you can create items, such as variables, functions, +and aliases. These items exist only in the session and are deleted when the +session ends. -You can also create user-managed sessions, known as " Windows PowerShell -sessions" or "PSSessions," on the local computer or on a remote computer. Like -the default session, you can run commands in a PSSession and add and create -items. However, unlike the session that starts automatically, you can control -the PSSessions that you create. You can get, create, configure, and remove -them, disconnect and reconnect to them, and run multiple commands in the same -PSSession. The PSSession remains available until you delete it or it times -out. +You can also create user-managed sessions, known as "PowerShell sessions" or +"PSSessions," on the local computer or on a remote computer. Like the default +session, you can run commands in a PSSession and add and create items. +However, unlike the session that starts automatically, you can control the +PSSessions that you create. You can get, create, configure, and remove them, +disconnect and reconnect to them, and run multiple commands in the same +PSSession. The PSSession remains available until you delete it or it times out. Typically, you create a PSSession to run a series of related commands on a -remote computer. When you create a PSSession on a remote computer, Windows -PowerShell establishes a persistent connection to the remote computer to -support the session. +remote computer. When you create a PSSession on a remote computer, PowerShell +establishes a persistent connection to the remote computer to support the +session. If you use the **ComputerName** parameter of the `Invoke-Command` or `Enter-PSSession` cmdlet to run a remote command or to start an interactive -session, Windows PowerShell creates a temporary session on the remote computer -and closes the session as soon as the command is complete or as soon as the +session, PowerShell creates a temporary session on the remote computer and +closes the session as soon as the command is complete or as soon as the interactive session ends. You cannot control these temporary sessions, and you -cannot use them for more than a single command or a single interactive -session. +cannot use them for more than a single command or a single interactive session. -In Windows PowerShell, the "current session" is the session that you are -working in. The "current session" can refer to any session, including a -temporary session or a PSSession. +In PowerShell, the "current session" is the session that you are working in. +The "current session" can refer to any session, including a temporary session +or a PSSession. ## Why Use a PSSession? @@ -96,10 +93,9 @@ You can run remote commands without creating a PSSession. Use the or a series of unrelated commands on one or many computers. When you use the **ComputerName** parameter of `Invoke-Command` or -`Enter-PSSession`, Windows PowerShell establishes a temporary connection to -the remote computer and then closes the connection as soon as the command is -complete. Any data elements that you create are lost when the connection is -closed. +`Enter-PSSession`, PowerShell establishes a temporary connection to the remote +computer and then closes the connection as soon as the command is complete. +Any data elements that you create are lost when the connection is closed. Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` and `Get-WmiObject`, use different remoting technologies to gather data. None @@ -108,8 +104,8 @@ create a persistent connection like a PSSession. ## How to Create a PSSession To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession -on a remote computer, use the **ComputerName** parameter of the -`New-PSSession` cmdlet. +on a remote computer, use the **ComputerName** parameter of the `New-PSSession` +cmdlet. For example, the following command creates a new PSSession on the Server01 computer. @@ -151,7 +147,8 @@ To get the PSSessions that were created in your current session, use the `Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` returns the same type of object that `New-PSSession` returns. -The following command gets all the PSSessions that were created in the current session. +The following command gets all the PSSessions that were created in the current +session. ```powershell Get-PSSession @@ -239,7 +236,7 @@ until it times out. You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` cmdlet to set an expiration time for an idle PSSession. For more information, -see [New-PSSessionOption](xref:Microsoft.PowerShell.Core.New-PSSessionOption). +see [New-PSSessionOption][03]. ## The PSSession Cmdlets @@ -261,18 +258,33 @@ Get-Help *-PSSession ## For More Information -For more information about PSSessions, see [about_PSSession_Details](about_PSSession_Details.md). +For more information about PSSessions, see [about_PSSession_Details][01]. ## See also -- [about_Remote](about_Remote.md) -- [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md) -- [about_Remote_Requirements](about_Remote_Requirements.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) -- [Connect-PSSession](xref:Microsoft.PowerShell.Core.Connect-PSSession) -- [Disconnect-PSSession](xref:Microsoft.PowerShell.Core.Disconnect-PSSession) -- [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) -- [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession) -- [Get-PSSession](xref:Microsoft.PowerShell.Core.Get-PSSession) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) -- [Remove-PSSession](xref:Microsoft.PowerShell.Core.Remove-PSSession) +- [about_Remote][05] +- [about_Remote_Disconnected_Sessions][04] +- [about_Remote_Requirements][02] +- [Invoke-Command][06] +- [Connect-PSSession][07] +- [Disconnect-PSSession][08] +- [Enter-PSSession][09] +- [Exit-PSSession][10] +- [Get-PSSession][11] +- [New-PSSession][12] +- [Remove-PSSession][13] + + +[01]: about_PSSession_Details.md +[02]: about_Remote_Requirements.md +[03]: xref:Microsoft.PowerShell.Core.New-PSSessionOption +[04]: about_Remote_Disconnected_Sessions.md +[05]: about_Remote.md +[06]: xref:Microsoft.PowerShell.Core.Invoke-Command +[07]: xref:Microsoft.PowerShell.Core.Connect-PSSession +[08]: xref:Microsoft.PowerShell.Core.Disconnect-PSSession +[09]: xref:Microsoft.PowerShell.Core.Enter-PSSession +[10]: xref:Microsoft.PowerShell.Core.Exit-PSSession +[11]: xref:Microsoft.PowerShell.Core.Get-PSSession +[12]: xref:Microsoft.PowerShell.Core.New-PSSession +[13]: xref:Microsoft.PowerShell.Core.Remove-PSSession diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 84761cc8a9f0..00a7b4cbcb63 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -9,6 +9,7 @@ title: about_Quoting_Rules # about_Quoting_Rules ## Short description + Describes rules for using single and double quotation marks in PowerShell. ## Long description @@ -464,7 +465,7 @@ For more information about this behavior, see the [about_Parsing][03] article. [01]: #including-quote-characters-in-a-string [02]: about_Parsing.md#argument-mode [03]: about_Parsing.md#passing-arguments-that-contain-quote-characters -[04]: about_preference_variables.md#ofs +[04]: about_Preference_Variables.md#ofs [05]: about_Special_Characters.md [06]: https://en.wikipedia.org/wiki/Quotation_marks_in_English#Smart_quotes [07]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md index 8390db10d20b..a9e449650c1a 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -9,13 +9,14 @@ title: about_Redirection # about_Redirection ## Short description + Explains how to redirect output from PowerShell to text files. ## Long description By default, PowerShell sends output to the PowerShell host. Usually this is the -console application. However, you can redirect the output to a text file and you -can redirect error output to the regular output stream. +console application. However, you can redirect the output to a text file and +you can redirect error output to the regular output stream. You can use the following methods to redirect output: @@ -26,9 +27,11 @@ You can use the following methods to redirect output: - Use the `Tee-Object` cmdlet, which sends command output to a text file and then sends it to the pipeline. -- Use the PowerShell redirection operators. Using the redirection operator with - a file target is functionally equivalent to piping to `Out-File` with no - extra parameters. +- Use the PowerShell redirection operators. Redirecting the output of a + PowerShell command (cmdlet, function, script) using the redirection operator + (`>`) is functionally equivalent to piping to `Out-File` with no extra + parameters. + For more information about streams, see [about_Output_Streams][04]. @@ -142,27 +145,27 @@ particular stream. The script in this example shows how the value of ```powershell $ErrorActionPreference = 'Continue' $ErrorActionPreference > log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'SilentlyContinue' $ErrorActionPreference >> log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'Stop' $ErrorActionPreference >> log.txt Try { - get-item /not-here 2>&1 >> log.txt + Get-Item /not-here 2>&1 >> log.txt } catch { "`tError caught!" >> log.txt } $ErrorActionPreference = 'Ignore' $ErrorActionPreference >> log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'Inquire' $ErrorActionPreference >> log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'Continue' ``` @@ -340,7 +343,7 @@ used. For more information, see the `-gt` operator in [03]: about_Operators.md [04]: about_Output_Streams.md [05]: about_Path_Syntax.md -[06]: about_preference_variables.md#psdefaultparametervalues +[06]: about_Preference_Variables.md#psdefaultparametervalues [07]: xref:Microsoft.PowerShell.Utility.Out-File [08]: xref:Microsoft.PowerShell.Utility.Tee-Object [09]: xref:Microsoft.PowerShell.Utility.Write-Debug diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Ref.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Ref.md index d3144b572ddb..6c3e9fb2f5f7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Ref.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Ref.md @@ -42,7 +42,7 @@ Test -data $var $var ``` -```output +```Output 10 ``` @@ -64,7 +64,7 @@ Test -data $var $var ``` -```output +```Output Name Value ---- ----- Test New Text @@ -101,21 +101,21 @@ Test -data ([ref]$var) $var ``` -```output +```Output 3 ``` ## Passing references to .NET methods -Some .NET methods may require you to pass a variable as a reference. When -the method's definition uses the keywords `in`, `out`, or `ref` on a -parameter, it expects a reference. +Some .NET methods may require you to pass a variable as a reference. When the +method's definition uses the keywords `in`, `out`, or `ref` on a parameter, it +expects a reference. ```powershell [int] | Get-Member -Static -Name TryParse ``` -```output +```Output Name MemberType Definition ---- ---------- ---------- TryParse Method static bool TryParse(string s, [ref] int result) @@ -149,7 +149,7 @@ $iRef = [ref]0 "`$i = $i;`$iRef = $($iRef.Value)" ``` -```output +```Output $i = 0;$iRef = 1 ``` @@ -188,8 +188,8 @@ specifying the `[System.Management.Automation.PSReference]` type directly. Even though `[ref]` is a type accelerator for `[System.Management.Automation.PSReference]`, they behave differently. -- When you use `[ref]` to cast a variable, PowerShell creates a reference object - that contains a reference to the original instance of the variable. +- When you use `[ref]` to cast a variable, PowerShell creates a reference + object that contains a reference to the original instance of the variable. - When you use `[System.Management.Automation.PSReference]` to cast a variable, PowerShell creates a reference object that contains a copy of the variable, rather than a reference to the original instance. @@ -243,7 +243,7 @@ Value [01]: about_Environment_Variables.md [02]: about_Functions.md -[03]: about_scopes.md +[03]: about_Scopes.md [04]: about_Script_Blocks.md [05]: about_Type_Accelerators.md [06]: about_Variables.md diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md index 26dbb021e901..f28f722ebf2b 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md @@ -26,8 +26,8 @@ Provides access to the registry keys, entries, and values in PowerShell. ## Detailed description -The PowerShell **Registry** provider lets you get, add, change, -clear, and delete registry keys, entries, and values in PowerShell. +The PowerShell **Registry** provider lets you get, add, change, clear, and +delete registry keys, entries, and values in PowerShell. The **Registry** drives are a hierarchical namespace containing the registry keys and subkeys on your computer. Registry entries and values aren't diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 6ddd47998d97..99c6e1f5bd35 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -9,6 +9,7 @@ title: about_Regular_Expressions # about_Regular_Expressions ## Short description + Describes regular expressions in PowerShell. ## Long description @@ -36,7 +37,7 @@ shown above has a different way to force case sensitivity. - For `Select-String`, use the **CaseSensitive** parameter. - For operators that use regular expressions, use the case-sensitive version: `-cmatch`, `-creplace`, or `-csplit` -- For the `switch` statement, use the `-casesensitive` option +- For the `switch` statement, use the `-CaseSensitive` option ## Character literals @@ -353,7 +354,7 @@ The provided regular expression extracts the username and domain from the message and stores them under the keys:**N** for name and **D** for domain. ```powershell -$log = (Get-EventLog -LogName Security -Newest 1 -InstanceId 4689).message +$log = (Get-EventLog -LogName Security -Newest 1 -InstanceId 4689).Message $r = '(?s).*Account Name:\s*(?.*).*Account Domain:\s*(?[A-Z,0-9]*)' $log -match $r ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md index 59a9ac3c085b..4bbe8a919558 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md @@ -37,7 +37,8 @@ The following cmdlets support the Disconnected Sessions feature: - `Connect-PSSession`: Connects to a disconnected PSSession. - `Disconnect-PSSession`: Disconnects a PSSession. -- `Get-PSSession`: Gets PSSessions on the local computer or on remote computers. +- `Get-PSSession`: Gets PSSessions on the local computer or on remote + computers. - `Receive-PSSession`: Gets the results of commands that ran in disconnected sessions. - `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and @@ -56,7 +57,7 @@ created ends. When you disconnect a PSSession, the PSSession remains active and is maintained on the remote computer. The session state changes from **Running** to -**Disconnected**. You can reconnect to a disconnected PSSession from +**Disconnected**. You can reconnect to a disconnected PSSession from: - The current session on the same computer - A different session on the same computer diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md index 3c2b90fd4fe5..16eb63440c33 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md @@ -9,7 +9,8 @@ title: about_Remote_Jobs # about_Remote_Jobs ## Short description -Describes how to run jobs on remote computers. + +Describes how to run background jobs on remote computers. ## Detailed Description @@ -85,7 +86,7 @@ all of the operations occur on the remote computer, not the local computer. The following command starts an interactive session on the Server01 computer. ```powershell - C:\PS> Enter-PSSession -computername Server01 + C:\PS> Enter-PSSession -ComputerName Server01 ``` The command prompt changes to show that you are now connected to the @@ -103,8 +104,8 @@ all of the operations occur on the remote computer, not the local computer. This command saves the job object in the `$job` variable. ```powershell - Server01\C:> $job = Start-Job -scriptblock { - Get-Eventlog "Windows PowerShell" + Server01\C:> $job = Start-Job -ScriptBlock { + Get-EventLog "Windows PowerShell" } ``` @@ -122,7 +123,7 @@ all of the operations occur on the remote computer, not the local computer. SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 1 Job1 Complete True localhost Get-Eventlog "Windows... + 1 Job1 Complete True localhost Get-EventLog "Windows... ``` The `Get-Job` output shows that job is running on the "localhost" computer @@ -161,8 +162,8 @@ all of the operations occur on the remote computer, not the local computer. view the contents of the file. ```powershell - $s = New-PSSession -computername Server01 - Invoke-Command -session $s -scriptblock { + $s = New-PSSession -ComputerName Server01 + Invoke-Command -Session $s -ScriptBlock { Get-Content c:\logs\pslog.txt} ``` @@ -188,8 +189,8 @@ requirements for remoting. assign a display name to the job. ```powershell - Invoke-Command -computername Server01 -scriptblock { - Get-Eventlog system} -AsJob + Invoke-Command -Computername Server01 -ScriptBlock { + Get-EventLog system} -AsJob ``` The results of the command resemble the following sample output. @@ -197,7 +198,7 @@ requirements for remoting. ```Output SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 1 Job1 Running True Server01 Get-Eventlog system + 1 Job1 Running True Server01 Get-EventLog system ``` When the **AsJob** parameter is used, `Invoke-Command` returns the same type @@ -227,7 +228,7 @@ requirements for remoting. ```Output SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 1 Job1 Completed True Server01 Get-Eventlog system + 1 Job1 Completed True Server01 Get-EventLog system ``` 1. To get the results of the job, use the `Receive-Job` cmdlet. Because the job @@ -240,7 +241,7 @@ requirements for remoting. file. ```powershell - $results = Receive-Job -id 1 + $results = Receive-Job -Id 1 ``` ### Start a remote job that keeps the results on the remote computer @@ -269,7 +270,7 @@ commands remotely to manage a local job on the remote computer. in the `$s` variable. ```powershell - $s = New-PSSession -computername Server01 + $s = New-PSSession -ComputerName Server01 ``` The next command uses the `Invoke-Command` cmdlet to run a `Start-Job` @@ -277,8 +278,8 @@ commands remotely to manage a local job on the remote computer. command are enclosed in braces. ```powershell - Invoke-Command -session $s -scriptblock { - Start-Job -scriptblock {Get-Eventlog system}} + Invoke-Command -Session $s -ScriptBlock { + Start-Job -ScriptBlock {Get-EventLog system}} ``` The results resemble the following sample output. @@ -286,7 +287,7 @@ commands remotely to manage a local job on the remote computer. ```Output Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- - 2 Job2 Running True Localhost Get-Eventlog system + 2 Job2 Running True Localhost Get-EventLog system ``` When you run a `Start-Job` command remotely, `Invoke-Command` returns the @@ -308,7 +309,7 @@ commands remotely to manage a local job on the remote computer. computer. ```powershell - Invoke-Command -session $s -scriptblock {Get-Job} + Invoke-Command -Session $s -ScriptBlock {Get-Job} ``` The command returns a job object. The **State** property of the job object @@ -317,7 +318,7 @@ commands remotely to manage a local job on the remote computer. ```Output SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 2 Job2 Completed True LocalHost Get-Eventlog system + 2 Job2 Completed True LocalHost Get-EventLog system ``` 1. To get the results of the job, use the `Invoke-Command` cmdlet to run a @@ -330,7 +331,7 @@ commands remotely to manage a local job on the remote computer. `Receive-Job` to keep the result in the job cache on the remote computer. ```powershell - $results = Invoke-Command -session $s -scriptblock { + $results = Invoke-Command -Session $s -ScriptBlock { Receive-Job -SessionId 2 -Keep } ``` @@ -340,7 +341,7 @@ commands remotely to manage a local job on the remote computer. file on the Server01 computer. ```powershell - Invoke-Command -session $s -command { + Invoke-Command -Session $s -Command { Receive-Job -SessionId 2 > c:\logs\pslog.txt } ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md index 4aa31abeb7c5..1ed9cf106b71 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md @@ -9,6 +9,7 @@ title: about_Remote_Troubleshooting # about_Remote_Troubleshooting ## Short description + Describes how to troubleshoot remote operations in PowerShell. ## Long description @@ -76,8 +77,8 @@ For errors: > - ERROR: ACCESS IS DENIED > - ERROR: The connection to the remote host was refused. Verify that the -> WS-Management service is running on the remote host and configured to listen -> for requests on the correct port and HTTP URL. +> WS-Management service is running on the remote host and configured to +> listen for requests on the correct port and HTTP URL. Enable the **Allow automatic configuration of listeners** policy to configure the listeners for all computers in a domain. @@ -136,7 +137,6 @@ The `Set-NetFirewallRule` cmdlet is exported by the **NetSecurity** module. For errors: > - ERROR: ACCESS IS DENIED - > - ERROR: The connection to the remote host was refused. Verify that the > WS-Management service is running on the remote host and configured to > listen for requests on the correct port and HTTP URL. diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index f3993c622ec1..2b4987e85ce8 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -77,10 +77,11 @@ $ps = "*PowerShell*" Invoke-Command -Session $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} ``` -A variable reference such as `$using:var` expands to the value of variable `$var` -from the caller's context. You do not get access to the caller's variable object. -The `Using` scope modifier cannot be used to modify a local variable within the -**PSSession**. For example, the following code does not work: +A variable reference such as `$using:var` expands to the value of variable +`$var` from the caller's context. You do not get access to the caller's +variable object. The `Using` scope modifier cannot be used to modify a local +variable within the **PSSession**. For example, the following code does not +work: ```powershell $s = New-PSSession -ComputerName S1 diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md index a6dd2017f77f..d3896d96ae3d 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md @@ -16,9 +16,9 @@ Prevents a script from running without the required elements. ## Long description The `#Requires` statement prevents a script from running unless the PowerShell -version, modules (and version), or snap-ins (and version), and edition -prerequisites are met. If the prerequisites aren't met, PowerShell doesn't run -the script or provide other runtime features, such as tab completion. +version, modules (and version), and edition prerequisites are met. If the +prerequisites aren't met, PowerShell doesn't run the script or provide other +runtime features, such as tab completion. ### Syntax diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Return.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Return.md index 365a61ca1012..3aecbec85660 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Return.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Return.md @@ -28,8 +28,8 @@ return only the value or values that are specified by the `return` keyword. > [!NOTE] > Beginning in PowerShell 5.0, PowerShell added language for defining > classes, by using formal syntax. In the context of a PowerShell class, -> nothing is output from a method except what you specify using a -> `return` statement. You can read more about PowerShell classes in +> nothing is output from a method except what you specify using a `return` +> statement. You can read more about PowerShell classes in > [about_Classes](about_Classes.md). ### Syntax @@ -67,7 +67,7 @@ function MultiplyEven 1..10 | ForEach-Object {MultiplyEven -Number $_} ``` -```output +```Output 1 is not even 4 3 is not even @@ -125,7 +125,7 @@ by the function and assigned to the `$a` variable. If you would like to display a message within your function, beginning in PowerShell 5.0, you can use the `Information` stream. The code below corrects the above example using the `Write-Information` cmdlet with a -`InformationAction` of **Continue**. +**InformationAction** set to `Continue`. ```powershell function calculation { @@ -135,13 +135,15 @@ function calculation { $value += 73 return $value } - -$a = calculation 14 ``` -```output +Now the information message to display in the host and not assigned to the +variable. + +```powershell +PS> $a = calculation 14 Please wait. Working on calculation... -C:\PS> $a +PS> $a 87 ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md index c7233bbe6494..f85e4df0d933 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md @@ -28,8 +28,8 @@ To use the **Run with PowerShell** feature: In File Explorer (or Windows Explorer), right-click the script filename and then select **Run with PowerShell**. -The **Run with PowerShell** feature starts a Windows PowerShell session that has -an execution policy of Bypass, runs the script, and closes the session. +The **Run with PowerShell** feature starts a Windows PowerShell session that +has an execution policy of Bypass, runs the script, and closes the session. It runs a command that has the following format: diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md index fabcbf312158..50b088a7405b 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md @@ -9,6 +9,7 @@ title: about_Script_Internationalization # about_Script_Internationalization ## Short description + Describes the script internationalization features that make it easy for scripts to display messages and instructions to users in their user interface (UI) language. @@ -30,8 +31,7 @@ To support international Help text, PowerShell includes the following features: - A Data section that separates text strings from code instructions. For more - information about the Data section, see - [about_Data_Sections](about_Data_Sections.md). + information about the Data section, see [about_Data_Sections][01]. - New automatic variables, `$PSCulture` and `$PSUICulture`. `$PSCulture` stores the name of the UI language used on the system for elements such as the date, @@ -41,7 +41,7 @@ features: - A cmdlet, `ConvertFrom-StringData`, that converts text strings into dictionary-like hash tables to facilitate translation. For more information, - see [ConvertFrom-StringData](xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData). + see [ConvertFrom-StringData][02]. - A new file type, `.psd1`, that stores translated text strings. The `.psd1` files are stored in language-specific subdirectories of the script directory. @@ -49,7 +49,7 @@ features: - A cmdlet, `Import-LocalizedData`, that imports translated text strings for a specified language into a script at runtime. This cmdlet recognizes and imports strings in any Windows-supported language. For more information see - [Import-LocalizedData](xref:Microsoft.PowerShell.Utility.Import-LocalizedData). + [Import-LocalizedData][03]. ### The Data Section: Storing Default Strings @@ -78,8 +78,7 @@ $msgTable = Data { } ``` -For more information about here-strings, see -[about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see [about_Quoting_Rules][04]. ### PSD1 Files: Storing Translated Strings @@ -241,9 +240,18 @@ Heute ist Freitag ## See also -- [about_Data_Sections](about_Data_Sections.md) -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_Quoting_Rules](about_Quoting_Rules.md) -- [Import-LocalizedData](xref:Microsoft.PowerShell.Utility.Import-LocalizedData) -- [ConvertFrom-StringData](xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData) +- [about_Data_Sections][01] +- [about_Automatic_Variables][05] +- [about_Hash_Tables][06] +- [about_Quoting_Rules][07] +- [Import-LocalizedData][03] +- [ConvertFrom-StringData][02] + + +[01]: about_Data_Sections.md +[02]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData +[03]: xref:Microsoft.PowerShell.Utility.Import-LocalizedData +[04]: about_Quoting_Rules.md +[05]: about_Automatic_Variables.md +[06]: about_Hash_Tables.md +[07]: about_Quoting_Rules.md diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scripts.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scripts.md index 0b834989b2b4..9e6b514c8818 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scripts.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scripts.md @@ -9,6 +9,7 @@ title: about_Scripts # about_Scripts ## Short description + Describes how to run and write scripts in PowerShell. ## Long description @@ -37,7 +38,7 @@ running on non-Windows platforms. The default execution policy, `Restricted`, prevents all scripts from running, including scripts that you write on the local computer. For more information, -see [about_Execution_Policies](about_Execution_Policies.md). +see [about_Execution_Policies][01]. The execution policy is saved in the registry, so you need to change it only once on each computer. @@ -78,7 +79,7 @@ For example, to run the ServicesLog.ps1 script in the local directory, type: ``` If the script has parameters, type the parameters and parameter values after -the script file name. +the script filename. For example, the following command uses the ServiceName parameter of the Get-ServiceLog script to request a log of WinRM service activity. @@ -91,7 +92,7 @@ As a security feature, PowerShell does not run scripts when you double-click the script icon in File Explorer or when you type the script name without a full path, even when the script is in the current directory. For more information about running commands and scripts in PowerShell, see -[about_Command_Precedence](about_Command_Precedence.md). +[about_Command_Precedence][02]. ### Run with PowerShell @@ -105,12 +106,12 @@ PowerShell". The "Run with PowerShell" feature is designed to run scripts that do not have required parameters and do not return output to the command prompt. -For more information, see [about_Run_With_PowerShell](about_Run_With_PowerShell.md). +For more information, see [about_Run_With_PowerShell][03]. ### Running scripts on other computers -To run a script on one or more remote computers, use the **FilePath** parameter of -the `Invoke-Command` cmdlet. +To run a script on one or more remote computers, use the **FilePath** parameter +of the `Invoke-Command` cmdlet. Enter the path and filename of the script as the value of the **FilePath** parameter. The script must reside on the local computer or in a directory that @@ -120,8 +121,11 @@ The following command runs the `Get-ServiceLog.ps1` script on the remote computers named Server01 and Server02. ```powershell -Invoke-Command -ComputerName Server01,Server02 -FilePath ` - C:\Scripts\Get-ServiceLog.ps1 +$invokeCommandSplat = @{ + ComputerName = 'Server01', 'Server02' + FilePath = 'C:\Scripts\Get-ServiceLog.ps1' +} +Invoke-Command @invokeCommandSplat ``` ## Get help for scripts @@ -134,7 +138,7 @@ path is in your `Path` environment variable, you can omit the path. For example, to get help for the ServicesLog.ps1 script, type: ```powershell -get-help C:\admin\scripts\ServicesLog.ps1 +Get-Help C:\admin\scripts\ServicesLog.ps1 ``` ## How to write a script @@ -151,8 +155,8 @@ running on the current system and saves them to a log file. The log filename is created from the current date. ```powershell -$date = (get-date).dayofyear -get-service | out-file "$date.log" +$date = (Get-Date).DayOfYear +Get-Service | Out-File "$date.log" ``` To create this script, open a text editor or a script editor, type these @@ -180,22 +184,22 @@ The following example shows a `Test-Remote.ps1` script that has a param ($ComputerName = $(throw "ComputerName parameter is required.")) function CanPing { - $error.clear() - $tmp = test-connection $computername -erroraction SilentlyContinue + $error.Clear() + $tmp = Test-Connection $computername -ErrorAction SilentlyContinue if (!$?) - {write-host "Ping failed: $ComputerName."; return $false} + {Write-Host "Ping failed: $ComputerName."; return $false} else - {write-host "Ping succeeded: $ComputerName"; return $true} + {Write-Host "Ping succeeded: $ComputerName"; return $true} } function CanRemote { - $s = new-pssession $computername -erroraction SilentlyContinue + $s = New-PSSession $computername -ErrorAction SilentlyContinue if ($s -is [System.Management.Automation.Runspaces.PSSession]) - {write-host "Remote test succeeded: $ComputerName."} + {Write-Host "Remote test succeeded: $ComputerName."} else - {write-host "Remote test failed: $ComputerName."} + {Write-Host "Remote test failed: $ComputerName."} } if (CanPing $computername) {CanRemote $computername} @@ -204,15 +208,14 @@ if (CanPing $computername) {CanRemote $computername} To run this script, type the parameter name after the script name. For example: ```powershell -C:\PS> .\test-remote.ps1 -computername Server01 +C:\PS> .\test-remote.ps1 -ComputerName Server01 Ping succeeded: Server01 Remote test failed: Server01 ``` For more information about the Param statement and the function parameters, see -[about_Functions](about_Functions.md) and -[about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md). +[about_Functions][04] and [about_Functions_Advanced_Parameters][05]. ### Writing help for scripts @@ -224,7 +227,7 @@ methods: Create a Help topic by using special keywords in the comments. To create comment-based Help for a script, the comments must be placed at the beginning or end of the script file. For more information about comment-based Help, see - [about_Comment_Based_Help](about_Comment_Based_Help.md). + [about_Comment_Based_Help][06]. - XML-Based Help for Scripts @@ -234,8 +237,8 @@ methods: To associate the script with the XML-based Help topic, use the .ExternalHelp Help comment keyword. For more information about the ExternalHelp keyword, see -[about_Comment_Based_Help](about_Comment_Based_Help.md). For more information -about XML-based help, see +[about_Comment_Based_Help][06]. For more information about XML-based help, see +[How to Write Cmdlet Help][07]. [How to Write Cmdlet Help](/powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets). ### Returning an exit value @@ -299,12 +302,12 @@ function and the `$ProfileName` variable. function New-Profile { Write-Host "Running New-Profile function" - $profileName = split-path $profile -leaf + $profileName = Split-Path $profile -Leaf - if (test-path $profile) - {write-error "Profile $profileName already exists on this computer."} + if (Test-Path $profile) + {Write-Error "Profile $profileName already exists on this computer."} else - {new-item -type file -path $profile -force } + {New-Item -Type file -Path $profile -Force } } ``` @@ -348,7 +351,7 @@ C:\PS> $profileName Microsoft.PowerShellISE_profile.ps1 ``` -For more information about scope, see [about_Scopes](about_Scopes.md). +For more information about scope, see [about_Scopes][08]. ## Scripts in modules @@ -362,7 +365,7 @@ which is a module that consists entirely or primarily of a script and supporting resources. A script module is just a script with a .psm1 file extension. -For more information about modules, see [about_Modules](about_Modules.md). +For more information about modules, see [about_Modules][09]. ## Other script features @@ -370,7 +373,7 @@ PowerShell has many useful features that you can use in scripts. - `#Requires` - You can use a `#Requires` statement to prevent a script from running without specified modules or snap-ins and a specified version of - PowerShell. For more information, see [about_Requires](about_Requires.md). + PowerShell. For more information, see [about_Requires][10]. - `$PSCommandPath` - Contains the full path and name of the script that is being run. This parameter is valid in all scripts. This automatic variable is @@ -393,11 +396,11 @@ PowerShell has many useful features that you can use in scripts. script. The values of these properties are populated only when the invoker or caller is a script. - - **PSCommandPath** contains the full path and name of the script that called or - invoked the current script. + - **PSCommandPath** contains the full path and name of the script that called + or invoked the current script. - - **PSScriptRoot** contains the directory of the script that called or invoked - the current script. + - **PSScriptRoot** contains the directory of the script that called or + invoked the current script. Unlike the `$PSCommandPath` and `$PSScriptRoot` automatic variables, which contain information about the current script, the **PSCommandPath** and @@ -406,26 +409,43 @@ PowerShell has many useful features that you can use in scripts. - Data sections - You can use the `Data` keyword to separate data from logic in scripts. Data sections can also make localization easier. For more - information, see [about_Data_Sections](about_Data_Sections.md) and - [about_Script_Internationalization](about_Script_Internationalization.md). + information, see [about_Data_Sections][11] and + [about_Script_Internationalization][12]. - Script Signing - You can add a digital signature to a script. Depending on the execution policy, you can use digital signatures to restrict the running of scripts that could include unsafe commands. For more information, see - [about_Execution_Policies](about_Execution_Policies.md) and - [about_Signing](about_Signing.md). + [about_Execution_Policies][01] and [about_Signing][13]. ## See also -- [about_Command_Precedence](about_Command_Precedence.md) -- [about_Comment_Based_Help](about_Comment_Based_Help.md) -- [about_Execution_Policies](about_Execution_Policies.md) -- [about_Functions](about_Functions.md) -- [about_Modules](about_Modules.md) -- [about_Profiles](about_Profiles.md) -- [about_Requires](about_Requires.md) -- [about_Run_With_PowerShell](about_Run_With_PowerShell.md) -- [about_Scopes](about_Scopes.md) -- [about_Script_Blocks](about_Script_Blocks.md) -- [about_Signing](about_Signing.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) +- [about_Command_Precedence][02] +- [about_Comment_Based_Help][06] +- [about_Execution_Policies][01] +- [about_Functions][04] +- [about_Modules][09] +- [about_Profiles][14] +- [about_Requires][10] +- [about_Run_With_PowerShell][03] +- [about_Scopes][08] +- [about_Script_Blocks][15] +- [about_Signing][13] +- [Invoke-Command][16] + + +[01]: about_Execution_Policies.md +[02]: about_Command_Precedence.md +[03]: about_Run_With_PowerShell.md +[04]: about_Functions.md +[05]: about_Functions_Advanced_Parameters.md +[06]: about_Comment_Based_Help.md +[07]: /powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets +[08]: about_Scopes.md +[09]: about_Modules.md +[10]: about_Requires.md +[11]: about_Data_Sections.md +[12]: about_Script_Internationalization.md +[13]: about_Signing.md +[14]: about_Profiles.md +[15]: about_Script_Blocks.md +[16]: xref:Microsoft.PowerShell.Core.Invoke-Command diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md index 5e504368a16f..a6a74e07aab2 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md @@ -20,8 +20,8 @@ sessions that use the session configuration. A "session configuration file" is a text file with a .pssc file name extension that contains a hash table of session configuration properties and values. You can use a session configuration file to set the properties of a session -configuration. Doing so defines the environment of any Windows PowerShell -sessions that use that session configuration. +configuration. Doing so defines the environment of any PowerShell sessions that +use that session configuration. Session configuration files make it easy to create custom session configurations without using complex C# assemblies or scripts. @@ -30,7 +30,7 @@ A "session configuration" or "endpoint" is a collection of local computer settings that determine such things as which users can create sessions on the computer; which commands users can run in those sessions; and whether the session should run as a privileged virtual account. For more information about -session configurations, see [about_Session_Configurations](about_Session_Configurations.md). +session configurations, see [about_Session_Configurations][01]. Session configurations were introduced in Windows PowerShell 2.0, and session configuration files were introduced in Windows PowerShell 3.0. You must use @@ -40,9 +40,9 @@ affected by the settings in the session configuration. ## Creating Custom Sessions -You can customize many features of a Windows PowerShell session by specifying -session properties in a session configuration. You can customize a session by -writing a C# program that defines a custom runspace, or you can use a session +You can customize many features of a PowerShell session by specifying session +properties in a session configuration. You can customize a session by writing a +C# program that defines a custom runspace, or you can use a session configuration file to define the properties of sessions created by using the session configuration. As a general rule, it is easier to use the session configuration file than to write a C# program. @@ -54,25 +54,25 @@ the modules required for those tasks; and sessions where unprivileged users can only run specific commands as a privileged account. In addition to that, you can manage whether users of the session can use -Windows PowerShell language elements such as script blocks, or whether they -can only run commands. You can manage the version of Windows PowerShell users -can run in the session; manage which modules are imported into the session; -and manage which cmdlets, functions, and aliases session users can run. When -using the RoleDefinitions field, you can give users different capabilities in -the session based on group membership. +PowerShell language elements such as script blocks, or whether they can only +run commands. You can manage the version of PowerShell users can run in the +session; manage which modules are imported into the session; and manage which +cmdlets, functions, and aliases session users can run. When using the +RoleDefinitions field, you can give users different capabilities in the session +based on group membership. For more information about RoleDefinitions and how to define this Value, see -the help topic for the New-PSRoleCapabilityFile Cmdlet. +the help topic for the `New-PSRoleCapabilityFile` Cmdlet. ## Creating a Session Configuration File The easiest way to create a session configuration file is by using the -New-PSSessionConfigurationFile cmdlet. This cmdlet generates a file that uses +`New-PSSessionConfigurationFile` cmdlet. This cmdlet generates a file that uses the correct syntax and format, and that automatically verifies many of the configuration file property values. For detailed descriptions of the properties that you can set in a session -configuration file, see the help topic for the New-PSSessionConfigurationFile +configuration file, see the help topic for the `New-PSSessionConfigurationFile` cmdlet. The following command creates a session configuration file that uses the @@ -92,7 +92,7 @@ Invoke-Item -Path .\Defaults.pssc ``` To create a session configuration for sessions in which user can run commands, -but not use other elements of the Windows PowerShell language, type: +but not use other elements of the PowerShell language, type: ```powershell New-PSSessionConfigurationFile -LanguageMode NoLanguage @@ -107,8 +107,7 @@ To create a session configuration for sessions in which users can use only Get cmdlets, type: ```powershell -New-PSSessionConfigurationFile -VisibleCmdlets Get-* --Path .\GetSessions.pssc +New-PSSessionConfigurationFile -VisibleCmdlets Get-* -Path .\GetSessions.pssc ``` In the preceding example, setting the VisibleCmdlets parameter to Get-* limits @@ -118,8 +117,7 @@ To create a session configuration for sessions that run under a privileged virtual account instead of the user's credentials, type: ```powershell -New-PSSessionConfigurationFile -RunAsVirtualAccount --Path .\VirtualAccount.pssc +New-PSSessionConfigurationFile -RunAsVirtualAccount -Path .\VirtualAccount.pssc ``` To create a session configuration for sessions in which the commands visible @@ -138,7 +136,7 @@ configuration or add you can add a file to the session configuration at a later time. To include a session configuration file when creating a session configuration, -use the Path parameter of the Register-PSSessionConfiguration cmdlet. +use the Path parameter of the `Register-PSSessionConfiguration` cmdlet. For example, the following command uses the NoLanguage.pssc file when it creates a NoLanguage session configuration. @@ -148,45 +146,43 @@ Register-PSSessionConfiguration -Name NoLanguage -Path .\NoLanguage.pssc ``` -When a new NoLanguage session starts, users will only have access to Windows -PowerShell commands. +When a new NoLanguage session starts, users will only have access to PowerShell +commands. To add a session configuration file to an existing session configuration, use the Set-PSSessionConfiguration cmdlet and the Path parameter. This affects any new sessions created with the specified session configuration. Note that the -Set-PSSessionConfiguration cmdlet changes the session itself and does not +`Set-PSSessionConfiguration` cmdlet changes the session itself and does not modify the session configuration file. For example, the following command adds the NoLanguage.pssc file to the LockedDown session configuration. ```powershell -Set-PSSessionConfiguration -Name LockedDown --Path .\NoLanguage.pssc +Set-PSSessionConfiguration -Name LockedDown -Path .\NoLanguage.pssc ``` When users use the LockedDown session configuration to create a session, they will be able to run cmdlets but they will not be able to create or use -variables, assign values, or use other Windows PowerShell language elements. +variables, assign values, or use other PowerShell language elements. -The following command uses the New-PSSession cmdlet to create a session on the -computer Srv01 that uses the LockedDown session configuration, saving an +The following command uses the `New-PSSession` cmdlet to create a session on +the computer Srv01 that uses the LockedDown session configuration, saving an object reference to the session in the $s variable. The ACL (access control list) of the session configuration determines who can use it to create a session. ```powershell -$s = New-PSSession -ComputerName Srv01 --ConfigurationName LockedDown +$s = New-PSSession -ComputerName Srv01 -ConfigurationName LockedDown ``` Because the NoLanguage constraints were added to the LockedDown session -configuration, users in LockedDown sessions will only be able to run Windows -PowerShell commands and cmdlets. For example, the following two commands use -the Invoke-Command cmdlet to run commands in the session referenced in the $s -variable. The first command, which runs the Get-UICulture cmdlet and does not +configuration, users in LockedDown sessions will only be able to run PowerShell +commands and cmdlets. For example, the following two commands use the +`Invoke-Command` cmdlet to run commands in the session referenced in the $s +variable. The first command, which runs the `Get-UICulture` cmdlet and does not use any variables, succeeds. The second command, which gets the value of the -$PSUICulture variable, fails. +`$PSUICulture` variable, fails. ``` Invoke-Command -Session $s {Get-UICulture} @@ -207,7 +203,7 @@ RunAsVirtualAccountGroups can be modified by editing the session configuration file used by the session configuration. To do this, begin by locating the active copy of the session configuration file. -When you use a session configuration file in a session configuration, Windows +When you use a session configuration file in a session configuration, PowerShell creates an active copy of the session configuration file and stores it in the \$pshome\\SessionConfig directory on the local computer. @@ -252,12 +248,12 @@ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc ``` If the syntax and values in the configuration file are valid -Test-PSSessionConfigurationFile returns True. If the syntax and values are not -valid then the cmdlet returns False. +`Test-PSSessionConfigurationFile` returns True. If the syntax and values are +not valid then the cmdlet returns False. -You can use Test-PSSessionConfigurationFile to test any session configuration +You can use `Test-PSSessionConfigurationFile` to test any session configuration file, including files that the New-PSSessionConfiguration cmdlet creates. For -more information, see the help topic for the Test-PSSessionConfigurationFile +more information, see the help topic for the `Test-PSSessionConfigurationFile` cmdlet. ## Removing a Session Configuration File @@ -268,7 +264,7 @@ settings. This effectively cancels the settings used by the original configuration file. To replace a session configuration file, create a new session configuration -file that uses the default settings, then use the Set-PSSessionConfiguration +file that uses the default settings, then use the `Set-PSSessionConfiguration` cmdlet to replace the custom session configuration file with the new file. For example, the following commands create a Default session configuration @@ -290,8 +286,8 @@ objects that represent session configurations using session configuration files have additional properties that make it easy to discover and analyze the session configuration. (Note that the type name shown below includes a formatted view definition.) You can view the properties by running the -Get-PSSessionConfiguration cmdlet and piping the returned data to the -Get-Member cmdlet: +`Get-PSSessionConfiguration` cmdlet and piping the returned data to the +`Get-Member` cmdlet: ```powershell Get-PSSessionConfiguration NoLanguage | Get-Member @@ -354,20 +350,18 @@ use session configuration files, the command might not return all qualifying session configurations. ```powershell -Get-PSSessionConfiguration | -where {$_.ExecutionPolicy -eq "RemoteSigned"} +Get-PSSessionConfiguration | Where-Object {$_.ExecutionPolicy -eq "RemoteSigned"} ``` The following command gets session configurations in which the RunAsUser is the Exchange administrator. ```powershell - Get-PSSessionConfiguration | -where {$_.RunAsUser -eq "Exchange01\Admin01"} + Get-PSSessionConfiguration | Where-Object {$_.RunAsUser -eq "Exchange01\Admin01"} ``` To view information about the role definitions associated with a configuration -use the Get-PSSessionCapability cmdlet. This cmdlet enables you to determine +use the `Get-PSSessionCapability` cmdlet. This cmdlet enables you to determine the commands and environment available to specific users in specific endpoints. @@ -382,15 +376,29 @@ working with an empty session. ## See also -- [about_Session_Configurations](about_Session_Configurations.md) -- [New-PSRoleCapabilityFile](xref:Microsoft.PowerShell.Core.New-PSRoleCapabilityFile) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) -- [Get-PSSessionCapability](xref:Microsoft.PowerShell.Core.Get-PSSessionCapability) -- [Disable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Disable-PSSessionConfiguration) -- [Enable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Enable-PSSessionConfiguration) -- [Get-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Get-PSSessionConfiguration) -- [Register-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Register-PSSessionConfiguration) -- [Set-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Set-PSSessionConfiguration) -- [Unregister-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Unregister-PSSessionConfiguration) -- [New-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.New-PSSessionConfigurationFile) -- [Test-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.Test-PSSessionConfigurationFile) +- [about_Session_Configurations][01] +- [New-PSRoleCapabilityFile][02] +- [New-PSSession][03] +- [Get-PSSessionCapability][04] +- [Disable-PSSessionConfiguration][05] +- [Enable-PSSessionConfiguration][06] +- [Get-PSSessionConfiguration][07] +- [Register-PSSessionConfiguration][08] +- [Set-PSSessionConfiguration][09] +- [Unregister-PSSessionConfiguration][10] +- [New-PSSessionConfigurationFile][11] +- [Test-PSSessionConfigurationFile][12] + + +[01]: about_Session_Configurations.md +[02]: xref:Microsoft.PowerShell.Core.New-PSRoleCapabilityFile +[03]: xref:Microsoft.PowerShell.Core.New-PSSession +[04]: xref:Microsoft.PowerShell.Core.Get-PSSessionCapability +[05]: xref:Microsoft.PowerShell.Core.Disable-PSSessionConfiguration +[06]: xref:Microsoft.PowerShell.Core.Enable-PSSessionConfiguration +[07]: xref:Microsoft.PowerShell.Core.Get-PSSessionConfiguration +[08]: xref:Microsoft.PowerShell.Core.Register-PSSessionConfiguration +[09]: xref:Microsoft.PowerShell.Core.Set-PSSessionConfiguration +[10]: xref:Microsoft.PowerShell.Core.Unregister-PSSessionConfiguration +[11]: xref:Microsoft.PowerShell.Core.New-PSSessionConfigurationFile +[12]: xref:Microsoft.PowerShell.Core.Test-PSSessionConfigurationFile diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configurations.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configurations.md index e37a6b7405fb..56c7d7a517fc 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configurations.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configurations.md @@ -9,6 +9,7 @@ title: about_Session_Configurations # about_Session_Configurations ## Short description + Describes session configurations, which determine the users who can connect to the computer remotely and the commands they can run. @@ -16,7 +17,8 @@ the computer remotely and the commands they can run. A session configuration, also known as an "endpoint" is a group of settings on the local computer that define the environment for the PowerShell sessions that -are created when remote or local users connect to PowerShell on the local computer. +are created when remote or local users connect to PowerShell on the local +computer. Administrators of the computer can use session configurations to protect the computer and to define custom environments for users who connect to the @@ -32,25 +34,23 @@ Beginning in PowerShell 3.0, you can use a session configuration file to define the elements of a session configuration. This feature makes it easy to customize sessions without writing code and to discover the properties of a session configuration. To create a session configuration file, use the -New-PSSessionConfiguration cmdlet. For more information about session -configuration files, see -[about_Session_Configuration_Files](about_Session_Configuration_Files.md). +`New-PSSessionConfiguration` cmdlet. For more information about session +configuration files, see [about_Session_Configuration_Files][01]. -Session configurations are a feature of Web Services for Management -(WS-Management) based PowerShell remoting. They are used only when you use the -New-PSSession, Invoke-Command, or Enter-PSSession cmdlets to connect to a -remote computer. +Session configurations are a feature of WSMAN-based PowerShell remoting. They +are used only when you use the `New-PSSession`, `Invoke-Command`, or +`Enter-PSSession` cmdlets to connect to a remote Windows computer. -Note: To manage the session configurations, start PowerShell with the -"Run as administrator" option. +To manage the session configurations on a Windows computer, start +PowerShell with the **Run as administrator** option. -About Session Configurations +### About Session Configurations Every PowerShell session uses a session configuration. This includes -persistent sessions that you create by using the New-PSSession or -Enter-PSSession cmdlets, and the temporary sessions that PowerShell creates +persistent sessions that you create by using the `New-PSSession` or +`Enter-PSSession` cmdlets, and the temporary sessions that PowerShell creates when you use the ComputerName parameter of a cmdlet that uses -WS-Management-based remoting technology, such as Invoke-Command. +WS-Management-based remoting technology, such as `Invoke-Command`. Administrators can use session configurations to protect the resources of the computer and to create custom environments for users who connect to the @@ -71,7 +71,7 @@ default session configurations. But, you can change the security descriptors to allow everyone, no one, or only selected users to use the session configurations on your computer. -Built-in Session Configurations +### Built-in Session Configurations PowerShell 3.0 includes built-in session configurations named Microsoft.PowerShell and Microsoft.PowerShell.Workflow. On computers running @@ -80,8 +80,8 @@ Microsoft.PowerShell and Microsoft.PowerShell.Workflow. On computers running The Microsoft.PowerShell session configuration is used for sessions by default, that is, when a command to create a session does not include the -ConfigurationName parameter of the New-PSSession, Enter-PSSession, or -Invoke-Command cmdlet. +ConfigurationName parameter of the `New-PSSession`, `Enter-PSSession`, or +`Invoke-Command` cmdlet. The security descriptors for the default session configurations allow only members of the Administrators group on the local computer to use them. As @@ -89,13 +89,13 @@ such, only members of the Administrators group can connect to the computer remotely unless you change the default settings. You can change the default session configurations by using the -$PSSessionConfigurationName preference variable. For more information, see -about_Preference_Variables. +`$PSSessionConfigurationName` preference variable. For more information, see +[about_Preference_Variables][02]. -Viewing Session Configurations on the Local Computer +### Viewing Session Configurations on the Local Computer To get the session configurations on your local computer, use the -Get-PSSessionConfiguration cmdlet. +`Get-PSSessionConfiguration` cmdlet. For example, type: @@ -145,11 +145,12 @@ Container {Name=microsoft.powershell.wor... microsoft.powershell.workflow Container {Name=microsoft.powershell32} microsoft.powershell32 ``` -Viewing Session Configurations on a Remote Computer +### Viewing Session Configurations on a Remote Computer -To view the session configurations on a remote computer, use the Connect-WSMan -cmdlet to add a note for the remote computer to the WSMAN: drive on your local -computer, and then use the WSMAN: drive to view the session configurations. +To view the session configurations on a remote computer, use the +`Connect-WSMan` cmdlet to add a note for the remote computer to the +WSMAN: drive on your local computer, and then use the WSMAN: drive to view the +session configurations. For example, the following command adds a node for the Server01 remote computer to the WSMAN: drive on the local computer. @@ -185,7 +186,7 @@ Container {Name=microsoft.powershell.wor... microsoft.powershell.workflow Container {Name=microsoft.powershell32} microsoft.powershell32 ``` -Changing the Security Descriptor of a Session Configuration +### Changing the Security Descriptor of a Session Configuration In Windows Server 2012 and newer releases of Windows Server, the built-in session configurations are enabled for remote users by default. In other @@ -193,7 +194,7 @@ supported versions of Windows, you must change the security descriptors of the session configurations to allow remote access. To enable remote access to the session configurations on the computer, use the -Enable-PSRemoting cmdlet. +`Enable-PSRemoting` cmdlet. Also, by default, only members of the Administrators group on the computer have Execute permission to the default session configurations, but you can @@ -210,12 +211,11 @@ the security descriptor for the Microsoft.PowerShell default session configuration. ```powershell -Set-PSSessionConfiguration -name Microsoft.PowerShell ` - -ShowSecurityDescriptorUI +Set-PSSessionConfiguration -Name Microsoft.PowerShell -ShowSecurityDescriptorUI ``` To deny everyone permission to all the session configurations on the computer, -use the Disable-PSSessionConfiguration cmdlet. For example, the following +use the `Disable-PSSessionConfiguration` cmdlet. For example, the following command disables the default session configurations on the computer. ```powershell @@ -223,7 +223,7 @@ PS C:> Disable-PSSessionConfiguration -Name Microsoft.PowerShell ``` To prevent remote users from connecting to the computer, but allow local users -to connect, use the Disable-PSRemoting cmdlet. Disable-PSRemoting adds a +to connect, use the `Disable-PSRemoting` cmdlet. `Disable-PSRemoting` adds a "Network_Deny_All" entry to all session configurations on the computer. ```powershell @@ -231,16 +231,16 @@ PS C:> Disable-PSRemoting ``` To allow remote users to use all session configurations on the computer, use -the Enable-PSRemoting or Enable-PSSessionConfiguration cmdlet. For example, +the `Enable-PSRemoting` or `Enable-PSSessionConfiguration` cmdlet. For example, the following command enables remote access to the built-in session configurations. ```powershell -PS C:> Enable-PSSessionConfiguration -name Microsoft.Power* +PS C:> Enable-PSSessionConfiguration -Name Microsoft.Power* ``` To make other changes to the security descriptor of a session configuration, -use the Set-PSSessionConfiguration cmdlet. Use the SecurityDescriptorSDDL +use the `Set-PSSessionConfiguration` cmdlet. Use the SecurityDescriptorSDDL parameter to submit an SDDL string value. Use the ShowSecurityDescriptorUI parameter to display a user interface property sheet that helps you to create a new SDDL. @@ -248,16 +248,15 @@ a new SDDL. For example: ```powershell -Set-PSSessionConfiguration -Name Microsoft.PowerShell ` - -ShowSecurityDescriptorUI +Set-PSSessionConfiguration -Name Microsoft.PowerShell -ShowSecurityDescriptorUI ``` -Creating a New Session Configuration +### Creating a New Session Configuration To create a new session configuration on the local computer, use the -Register-PSSessionConfiguration cmdlet. To define the new session +`Register-PSSessionConfiguration` cmdlet. To define the new session configuration, you can use a C# assembly, a PowerShell script, and the -parameters of the Register-PSSessionConfiguration cmdlet. +parameters of the `Register-PSSessionConfiguration` cmdlet. For example, the following command creates a session configuration that is identical the Microsoft.PowerShell session configuration, except that it @@ -265,52 +264,55 @@ limits the data received from a remote command to 20 megabytes (MB). (The default is 50 MB). ```powershell -Register-PSSessionConfiguration -Name NewConfig ` - -MaximumReceivedDataSizePerCommandMB 20 +$registerPSSessionConfigurationSplat = @{ + Name = 'NewConfig' + MaximumReceivedDataSizePerCommandMB = 20 +} +Register-PSSessionConfiguration @registerPSSessionConfigurationSplat ``` When you create a session configuration, you can manage it by using the other session configuration cmdlets, and it appears in the WSMAN: drive. -For more information, see Register-PSSessionConfiguration. +For more information, see `Register-PSSessionConfiguration`. -Removing a Session Configuration +### Removing a Session Configuration To remove a session configuration from the local computer, use the -Unregister-PSSessionConfiguration cmdlet. For example, the following command +`Unregister-PSSessionConfiguration` cmdlet. For example, the following command removes the NewConfig session configuration from the computer. ```powershell -PS C:> Unregister-PSSessionConfiguration -Name NewConfig +Unregister-PSSessionConfiguration -Name NewConfig ``` -For more information, see Unregister-PSSessionConfiguration. +For more information, see `Unregister-PSSessionConfiguration`. -Restoring a Session Configuration +### Restoring a Session Configuration To restore a default session configuration that was deleted (unregistered) -accidentally, use the Enable-PSRemoting cmdlet. +accidentally, use the `Enable-PSRemoting` cmdlet. -The Enable-PSRemoting cmdlet recreates all default sessions configurations +The `Enable-PSRemoting` cmdlet recreates all default sessions configurations that do not exist on the computer. It does not overwrite or change the property values of existing session configurations. To restore the original property values of a default session configuration, -use the Unregister-PSSessionConfiguration to delete the session configuration -and then use the Enable-PSRemoting cmdlet to recreate it. +use the `Unregister-PSSessionConfiguration` to delete the session configuration +and then use the `Enable-PSRemoting` cmdlet to recreate it. -Selecting a Session Configuration +### Selecting a Session Configuration To select a particular session configuration for a session, use the -ConfigurationName parameter of New-PSSession, Enter-PSSession, or -Invoke-Command. +ConfigurationName parameter of `New-PSSession`, `Enter-PSSession`, or +`Invoke-Command`. -For example, this command uses the New-PSSession cmdlet to start a PSSession +For example, this command uses the `New-PSSession` cmdlet to start a PSSession on the Server01 computer. The command uses the ConfigurationName parameter to select the WithProfile configuration on the Server01 computer. ```powershell -PS C:> New-PSSession -ComputerName Server01 -ConfigurationName WithProfile +New-PSSession -ComputerName Server01 -ConfigurationName WithProfile ``` This command will succeed only if the current user has permission to use the @@ -320,7 +322,7 @@ has the required permissions. You can also use the $PSSessionConfigurationName preference variable to change the default session configuration on the computer. For more information about the $PSSessionConfigurationName preference variable, see -about_Preference_Variables. +[about_Preference_Variables][02]. ## KEYWORDS @@ -329,10 +331,10 @@ about_SessionConfigurations ## See also -- [about_Preference_Variables](about_Preference_Variables.md) +- [about_Preference_Variables][02] - [about_PSSessions](about_PSSessions.md) - [about_Remote](about_Remote.md) -- [about_Session_Configuration_Files](about_Session_Configuration_Files.md) +- [about_Session_Configuration_Files][01] - [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) - [Disable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Disable-PSSessionConfiguration) - [Enable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Enable-PSSessionConfiguration) @@ -342,3 +344,7 @@ about_SessionConfigurations - [Unregister-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Unregister-PSSessionConfiguration) - [New-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.New-PSSessionConfigurationFile) - [Test-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.Test-PSSessionConfigurationFile) + + +[01]: about_Session_Configuration_Files.md +[02]: about_Preference_Variables.md diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md index bc636bc57d27..9cc9ad56d46c 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md @@ -9,6 +9,7 @@ title: about_Simplified_Syntax # about_Simplified_Syntax ## Short description + Describes easier, more natural-language ways of scripting filters for collections of objects. @@ -60,7 +61,7 @@ commands: ```powershell dir Cert:\LocalMachine\Root | Where FriendlyName -EQ 'Verisign' -dir Cert:\ -Recurse | ForEach GetKeyAlgorithm +dir Cert:\ -Recurse | foreach GetKeyAlgorithm ``` While both syntaxes work, the simplified syntax returns results without @@ -96,5 +97,5 @@ Get-ChildItem /home -Directory | foreach GetFiles .* - [about_Comparison_Operators](about_Comparison_Operators.md) - [about_Foreach](about_Foreach.md) -- [Foreach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) +- [ForEach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) - [Where-Object](xref:Microsoft.PowerShell.Core.Where-Object) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md index 20c53f92c7f3..a5406a7cc01c 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -69,7 +69,8 @@ table of parameter-name and parameter-value pairs and stores it in the variable in a command with splatting. The At symbol (`@HashArguments`) replaces the dollar sign (`$HashArguments`) in the command. -To provide a value for the **WhatIf** switch parameter, use `$True` or `$False`. +To provide a value for the **WhatIf** switch parameter, use `$True` or +`$False`. ```powershell $HashArguments = @{ diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md index 6e5be6210427..37ffcbe5e376 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md @@ -9,6 +9,7 @@ title: about_Split # about_Split ## Short description + Explains how to use the Split operator to split one or more strings into substrings. diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md index ccf7bac47058..4c76dd96dd27 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md @@ -9,6 +9,7 @@ title: about_Switch # about_Switch ## Short description + Explains how to use a switch to handle multiple `if` statements. ## Long description @@ -191,10 +192,10 @@ examples evaluates 4 and then 2. ```powershell switch (4, 2) { - 1 {"It is one." } - 2 {"It is two." } - 3 {"It is three." } - 4 {"It is four." } + 1 {"It is one."} + 2 {"It is two."} + 3 {"It is three."} + 4 {"It is four."} 3 {"Three again."} } ``` @@ -212,9 +213,9 @@ statement in the condition of value 4. switch (4, 2) { 1 {"It is one."; Break} - 2 {"It is two." ; Break } - 3 {"It is three." ; Break } - 4 {"It is four." ; Break } + 2 {"It is two." ; Break} + 3 {"It is three." ; Break} + 4 {"It is four." ; Break} 3 {"Three again."} } ``` @@ -369,7 +370,7 @@ the beginning of the year 2022. ```powershell switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { { $_.Year -eq 2021 } { - $days = ((Get-Date 1/1/2022) - $_).days + $days = ((Get-Date 1/1/2022) - $_).Days "There are $days days until 2022." } { $_.Year -eq 2022 } { 'Welcome to 2022!' } diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md index b640dd05a2e9..f3a94e9cb991 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md @@ -10,6 +10,7 @@ title: About_tab_expansion # about_Tab_Expansion ## Short description + PowerShell provides completions on input to provide hints, enable discovery, and speed up input entry. Command names, parameter names, argument values and file paths can all be completed by pressing the Tab key. @@ -26,7 +27,8 @@ feature of the PSReadLine module. For more information, see The Tab key is the default key binding on Windows. You can change the keybinding using the PSReadLine module or the application that's hosting -PowerShell. For more information, see [about_PSReadLine][02]. +PowerShell. The keybinding is different on non-Windows platforms. For more +information, see [about_PSReadLine][02]. > [!NOTE] > One limitation of the tab expansion process is that tabs are always @@ -42,6 +44,9 @@ part of the name and press the Tab key. PowerShell automatically expands the name to the first match that it finds. Pressing the Tab key repeatedly cycles through all the available choices. + +## Cmdlet name completion + The tab expansion of cmdlet names is slightly different. To use tab expansion on a cmdlet name, type the entire first part of the name (the verb) and the hyphen that follows it. You can fill in more of the name for a partial match. @@ -104,8 +109,9 @@ keys to select the value you want. Tab completion can also work to complete parameter arguments. You can use the Tab key to cycle through a list of possible values that are valid -for some parameter. For more information, see -[about_Functions_Argument_Completion][04]. +for some parameter. + +For more information, see [about_Functions_Argument_Completion][04]. ## See also diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md index f43f8ac0abe0..4b27cd924d85 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md @@ -231,7 +231,7 @@ At line:5 char:1 + FullyQualifiedErrorId : CommandNotFoundException ``` -Because PowerShell doesn't recognize "nonsenseString" as a cmdlet or other +Because PowerShell doesn't recognize `nonsenseString` as a cmdlet or other item, it returns a **CommandNotFoundException** error. The specific `trap` statement traps this terminating error. @@ -386,8 +386,8 @@ however, the `trap` statement is outside the function. PowerShell doesn't go back into the function after the `trap` statement runs. > [!CAUTION] -> When multiple traps are defined for the same error condition, the first `trap` -> defined lexically (highest in the script block) is used. +> When multiple traps are defined for the same error condition, the first +> `trap` defined lexically (highest in the script block) is used. In the following example, only the `trap` with `whoops 1` runs. diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md index 4b56d0ef5aa3..4247d6f94e8a 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md @@ -255,7 +255,7 @@ try { "An error occurred that could not be resolved." } finally { $wc.Dispose() - if (Test-Path $tempPath) { Remove-item $tempFile } + if (Test-Path $tempPath) { Remove-Item $tempFile } } ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Conversion.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Conversion.md index 9cb6529b2480..708e77980e91 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Conversion.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Conversion.md @@ -528,8 +528,8 @@ For more information, see [about_Comparison_Operators][05]. [05]: about_Comparison_Operators.md [06]: about_Functions_Advanced.md [07]: about_Numeric_Literals.md -[08]: about_parameter_binding.md -[09]: about_preference_variables.md#ofs +[08]: about_Parameter_Binding.md +[09]: about_Preference_Variables.md#ofs [10]: about_Types.ps1xml.md [11]: https://stackoverflow.com/questions/76241804/how-does-powershell-split-consecutive-strings-not-a-single-letter [12]: xref:Microsoft.PowerShell.Utility.Update-TypeData diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index 5f286c031290..dd637a418b96 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -9,6 +9,7 @@ title: about_Types.ps1xml # about_Types.ps1xml ## Short description + Explains how to use `Types.ps1xml` files to extend the types of objects that are used in PowerShell. @@ -24,8 +25,7 @@ data to a PowerShell session. This topic describes `Types.ps1xml` files. For more information about using the `Update-TypeData` cmdlet to add dynamic extended type data to the current -session see -[Update-TypeData](xref:Microsoft.PowerShell.Utility.Update-TypeData). +session see [Update-TypeData][01]. ## About extended type data @@ -46,8 +46,8 @@ Sunday, January 29, 2012 9:43:57 AM ``` You won't find the **DateTime** property in the description of the -[System.DateTime](/dotnet/api/system.datetime) structure, because PowerShell -adds the property and it is visible only in PowerShell. +[System.DateTime][02] structure, because PowerShell adds the property and it is +visible only in PowerShell. PowerShell internally defines a default set of extended types. This type information is loaded in every PowerShell session at startup. The **DateTime** @@ -60,7 +60,8 @@ directory (`$PSHOME`). There are three sources of extended type data in PowerShell sessions. - Extended type data is defined by PowerShell and loaded automatically into - every PowerShell session. + every PowerShell session. Beginning with PowerShell 6, this information is + compiled into PowerShell and is no longer shipped in a `Types.ps1xml` file. - The `Types.ps1xml` files that modules export are loaded when the module is imported into the current session. @@ -140,12 +141,12 @@ As a result, you can use either the **Count** property or the **Length** property of arrays in PowerShell. For example: ```powershell -(1, 2, 3, 4).count +(1, 2, 3, 4).Count 4 ``` ```powershell -(1, 2, 3, 4).length +(1, 2, 3, 4).Length 4 ``` @@ -175,9 +176,7 @@ the `Update-TypeData` command to your PowerShell profile. The `Types.ps1xml` files add properties and methods to all the instances of the objects of the specified .NET type in the affected PowerShell session. However, if you need to add properties or methods only to one instance of an object, use -the `Add-Member` cmdlet. - -For more information, see [Add-Member](xref:Microsoft.PowerShell.Utility.Add-Member). +the `Add-Member` cmdlet. For more information, see [Add-Member][03]. ## Example: Adding an Age member to FileInfo objects @@ -209,13 +208,11 @@ Save the follow XML code to the file `$PSHOME\MyTypes.ps1xml`. Run `Update-TypeData` to add the new `Types.ps1xml` file to the current session. The command uses the **PrependData** parameter to place the new file -in a precedence order higher than the original definitions. - -For more information about `Update-TypeData`, see -[Update-TypeData](xref:Microsoft.PowerShell.Utility.Update-TypeData). +in a precedence order higher than the original definitions. For more +information about `Update-TypeData`, see [Update-TypeData][01]. ```powershell -Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml +Update-TypeData -PrependPath $PSHOME\MyTypes.ps1xml ``` To test the change, run a `Get-ChildItem` command to get the PowerShell.exe @@ -233,9 +230,8 @@ Get-ChildItem $PSHOME\pwsh.exe | Select-Object Age ## The XML in Types.ps1xml files -The full schema definition can be found in -[Types.xsd](https://github.com/PowerShell/PowerShell/blob/master/src/Schemas/Types.xsd) -in the PowerShell source code repository on GitHub. +The full schema definition can be found in [Types.xsd][04] in the PowerShell +source code repository on GitHub. The `` tag encloses all of the types that are defined in the file. There should be only one `` tag. @@ -516,7 +512,7 @@ objects. ``` For more information, see the -[Windows PowerShell Software Development Kit (SDK)](/powershell/scripting/developer/windows-powershell). +[Windows PowerShell Software Development Kit (SDK)][05]. ## Update-TypeData @@ -544,15 +540,27 @@ are added by running the `Update-TypeData` cmdlet cannot use method syntax. ## Signing a Types.ps1xml file To protect users of your `Types.ps1xml` file, you can sign the file using a -digital signature. For more information, see -[about_Signing](about_Signing.md). +digital signature. For more information, see [about_Signing][06]. ## See also -- [about_Signing](about_Signing.md) -- [Copy-Item](xref:Microsoft.PowerShell.Management.Copy-Item) -- [Copy-ItemProperty](xref:Microsoft.PowerShell.Management.Copy-ItemProperty) -- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) -- [Get-TypeData](xref:Microsoft.PowerShell.Utility.Get-TypeData) -- [Remove-TypeData](xref:Microsoft.PowerShell.Utility.Remove-TypeData) -- [Update-TypeData](xref:Microsoft.PowerShell.Utility.Update-TypeData) +- [about_Signing][06] +- [Copy-Item][07] +- [Copy-ItemProperty][08] +- [Get-Member][09] +- [Get-TypeData][10] +- [Remove-TypeData][11] +- [Update-TypeData][01] + + +[01]: xref:Microsoft.PowerShell.Utility.Update-TypeData +[02]: /dotnet/api/system.datetime +[03]: xref:Microsoft.PowerShell.Utility.Add-Member +[04]: https://github.com/PowerShell/PowerShell/blob/master/src/Schemas/Types.xsd +[05]: /powershell/scripting/developer/windows-powershell +[06]: about_Signing.md +[07]: xref:Microsoft.PowerShell.Management.Copy-Item +[08]: xref:Microsoft.PowerShell.Management.Copy-ItemProperty +[09]: xref:Microsoft.PowerShell.Utility.Get-Member +[10]: xref:Microsoft.PowerShell.Utility.Get-TypeData +[11]: xref:Microsoft.PowerShell.Utility.Remove-TypeData diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index f3246f3c29b3..aeb391b578fa 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -9,6 +9,7 @@ title: about_Updatable_Help # about_Updatable_Help ## Short description + Describes the updatable help system in PowerShell. ## Long description @@ -390,8 +391,7 @@ to specify a different filesystem location, but they can't exclude the > only the policy setting under **Computer Configuration** is effective. The > policy setting under **User Configuration** is ignored. -For more information, see -[about_Group_Policy_Settings][04]. +For more information, see [about_Group_Policy_Settings][04]. ## How to update help for non-standard modules diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Variable_Provider.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Variable_Provider.md index dfb40333ecef..87daa068c640 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Variable_Provider.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Variable_Provider.md @@ -39,31 +39,31 @@ objects. The variables have no child items. The **Variable** provider supports the following cmdlets, which are covered in this article. -- [Get-Location](xref:Microsoft.PowerShell.Management.Get-Location) -- [Set-Location](xref:Microsoft.PowerShell.Management.Set-Location) -- [Get-Item](xref:Microsoft.PowerShell.Management.Get-Item) -- [New-Item](xref:Microsoft.PowerShell.Management.New-Item) -- [Remove-Item](xref:Microsoft.PowerShell.Management.Remove-Item) -- [Clear-Item](xref:Microsoft.PowerShell.Management.Clear-Item) +- [Get-Location][01] +- [Set-Location][02] +- [Get-Item][03] +- [New-Item][04] +- [Remove-Item][05] +- [Clear-Item][06] PowerShell also includes a set of cmdlets designed especially to view and to change variables. When you use **Variable** cmdlets, you do not need to specify the `Variable:` drive in the name. This article does not cover working with **Variable** cmdlets. -- [Get-Variable](xref:Microsoft.PowerShell.Utility.Get-Variable) -- [New-Variable](xref:Microsoft.PowerShell.Utility.New-Variable) -- [Set-Variable](xref:Microsoft.PowerShell.Utility.Set-Variable) -- [Remove-Variable](xref:Microsoft.PowerShell.Utility.Remove-Variable) -- [Clear-Variable](xref:Microsoft.PowerShell.Utility.Clear-Variable) +- [Get-Variable][07] +- [New-Variable][08] +- [Set-Variable][09] +- [Remove-Variable][10] +- [Clear-Variable][11] > [!NOTE] > You can also use the PowerShell expression parser to create, view, and change -> the values of variables without using the cmdlets. When working with variables -> directly, use a dollar sign (`$`) to identify the name as a variable and the -> assignment operator (`=`)to establish and change its value. For example, -> `$p = Get-Process` creates the `p` variable and stores the results of a -> `Get-Process` command in it. +> the values of variables without using the cmdlets. When working with +> variables directly, use a dollar sign (`$`) to identify the name as a +> variable and the assignment operator (`=`)to establish and change its value. +> For example, `$p = Get-Process` creates the `p` variable and stores the +> results of a `Get-Process` command in it. ## Types exposed by this provider @@ -109,9 +109,8 @@ drive. To reference a variable from another location, use the drive name > [!NOTE] > PowerShell uses aliases to allow you a familiar way to work with provider > paths. Commands such as `dir` and `ls` are now aliases for -> [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem), -> `cd` is an alias for [Set-Location](xref:Microsoft.PowerShell.Management.Set-Location). and `pwd` is -> an alias for [Get-Location](xref:Microsoft.PowerShell.Management.Get-Location). +> [Get-ChildItem][12], `cd` is an alias for [Set-Location][13]. and `pwd` is +> an alias for [Get-Location][14]. ## Displaying the value of variables @@ -126,9 +125,9 @@ Get-ChildItem -Path Variable: ### Get a variable using its provider path -This command retrieves a variables value using its provider path prefixed by the -dollar sign (`$`). This has the same effect as prefixing the variables name with -the dollar sign (`$`). +This command retrieves a variables value using its provider path prefixed by +the dollar sign (`$`). This has the same effect as prefixing the variables name +with the dollar sign (`$`). ```powershell $variable:home @@ -145,14 +144,13 @@ Get-ChildItem -Path Variable:max* ### Get the value of the ? variable -This command uses the `-LiteralPath` parameter of -[Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) to get +This command uses the `-LiteralPath` parameter of [Get-ChildItem][12] to get the value of the `?` variable from within the `Variable:` drive. The `?` is a wildcard in paths, but `Get-ChildItem` does not attempt to resolve any wildcards in the values of the `-LiteralPath` parameter. ```powershell -Get-ChildItem -Literalpath ? +Get-ChildItem -LiteralPath ? ``` ### Get ReadOnly and Constant variables @@ -162,8 +160,8 @@ This command gets the variables that have the values of `ReadOnly` or ```powershell Get-ChildItem -Path Variable: | Where-Object { - $_.options -Match "Constant" ` - -or $_.options -Match "ReadOnly" + $_.options -match "Constant" ` + -or $_.options -match "ReadOnly" } | Format-List -Property name, value, options ``` @@ -267,8 +265,8 @@ Beginning in Windows PowerShell 3.0, you can get customized help topics for provider cmdlets that explain how those cmdlets behave in a file system drive. To get the help topics that are customized for the file system drive, run a -[Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) command in a file system drive or use the `-Path` -parameter of [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) to specify a file system drive. +[Get-Help][15] command in a file system drive or use the `-Path` parameter of +[Get-Help][15] to specify a file system drive. ```powershell Get-Help Get-ChildItem @@ -280,6 +278,26 @@ Get-Help Get-ChildItem -Path variable: ## See also -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_Providers](about_Providers.md) -- [about_Variables](about_Variables.md) +- [about_Automatic_Variables][16] +- [about_Providers][17] +- [about_Variables][18] + + +[01]: xref:Microsoft.PowerShell.Management.Get-Location +[02]: xref:Microsoft.PowerShell.Management.Set-Location +[03]: xref:Microsoft.PowerShell.Management.Get-Item +[04]: xref:Microsoft.PowerShell.Management.New-Item +[05]: xref:Microsoft.PowerShell.Management.Remove-Item +[06]: xref:Microsoft.PowerShell.Management.Clear-Item +[07]: xref:Microsoft.PowerShell.Utility.Get-Variable +[08]: xref:Microsoft.PowerShell.Utility.New-Variable +[09]: xref:Microsoft.PowerShell.Utility.Set-Variable +[10]: xref:Microsoft.PowerShell.Utility.Remove-Variable +[11]: xref:Microsoft.PowerShell.Utility.Clear-Variable +[12]: xref:Microsoft.PowerShell.Management.Get-ChildItem +[13]: xref:Microsoft.PowerShell.Management.Set-Location +[14]: xref:Microsoft.PowerShell.Management.Get-Location +[15]: xref:Microsoft.PowerShell.Core.Get-Help +[16]: about_Automatic_Variables.md +[17]: about_Providers.md +[18]: about_Variables.md diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Variables.md index 800311d7c31f..9926999bd7bd 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Variables.md @@ -515,7 +515,7 @@ Get-Help [01]: #variable-names-that-include-special-characters [02]: about_Alias_Provider.md -[03]: about_assignment_operators.md#assigning-multiple-variables +[03]: about_Assignment_Operators.md#assigning-multiple-variables [04]: about_Automatic_Variables.md [05]: about_Environment_Provider.md [06]: about_Environment_Variables.md diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_While.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_While.md index fd42a62b6dd0..2a7aa79e7c98 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_While.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_While.md @@ -28,11 +28,11 @@ The following shows the While statement syntax: while (){} ``` -When you run a `while` statement, PowerShell evaluates the `` section -of the statement before entering the `` section. The condition -portion of the statement resolves to either true or false. As long as the -condition remains true, PowerShell reruns the `` section. For -more information about how booleans are evaluated, see +When you run a `while` statement, PowerShell evaluates the `` +section of the statement before entering the `` section. The +condition portion of the statement resolves to either true or false. As long as +the condition remains true, PowerShell reruns the `` section. +For more information about how booleans are evaluated, see [about_Booleans](about_Booleans.md). The `` section of the statement contains one or more commands @@ -40,8 +40,8 @@ that are run each time the loop is entered or repeated. The `` can contain any valid PowerShell statements, including the `break` and `continue` keywords. -For example, the following `while` statement displays the numbers 1 through 3 if -the `$val` variable has not been created or if the `$val` variable has been +For example, the following `while` statement displays the numbers 1 through 3 +if the `$val` variable has not been created or if the `$val` variable has been created and initialized to 0. ```powershell @@ -64,8 +64,8 @@ can enter it in the following way: while($val -ne 3){$val++; Write-Host $val} ``` -Notice that the semicolon separates the first command that adds 1 to `$val` from -the second command that writes the value of `$val` to the console. +Notice that the semicolon separates the first command that adds 1 to `$val` +from the second command that writes the value of `$val` to the console. ## See also diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Wildcards.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Wildcards.md index 9bba4d5523c5..7996600f3d93 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Wildcards.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Wildcards.md @@ -82,7 +82,7 @@ following command gets services in which the **ServiceType** property value includes **Interactive**. ```powershell -Get-Service | Where-Object {$_.ServiceType -Like "*Interactive*"} +Get-Service | Where-Object {$_.ServiceType -like "*Interactive*"} ``` In the following example, the `If` statement includes a condition that uses @@ -106,7 +106,7 @@ foreach ($point in $p) { - [about_Script_Blocks][04] -[01]: ./about_Regular_Expressions.md +[01]: about_Regular_Expressions.md [02]: about_If.md [03]: about_Language_Keywords.md [04]: about_Script_Blocks.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/About.md b/reference/7.4/Microsoft.PowerShell.Core/About/About.md index 1a38ce399f49..ed49ce71c6c8 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/About.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/About.md @@ -223,7 +223,8 @@ Describes the attribute that makes a function work like a compiled cmdlet. ### [about_Functions_OutputTypeAttribute](about_Functions_OutputTypeAttribute.md) -Describes an attribute that reports the type of object that the function returns. +Describes an attribute that reports the type of object that the function +returns. ### [about_Functions](about_Functions.md) diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_PSSession_Details.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_PSSession_Details.md index c266b7675ce2..b22777e2c859 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_PSSession_Details.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_PSSession_Details.md @@ -9,57 +9,56 @@ title: about_PSSession_Details # about_PSSession_Details ## Short description + Provides detailed information about PowerShell sessions and the role they play in remote commands. ## Long description -A session is an environment in which PowerShell runs. A session is -created for you whenever you start PowerShell. You can create -additional sessions, called "PowerShell sessions" or "PSSessions" -on your computer or another computer. +A session is an environment in which PowerShell runs. A session is created for +you whenever you start PowerShell. You can create additional sessions, called +"PowerShell sessions" or "PSSessions" on your computer or another computer. -Unlike the sessions that PowerShell creates for you, you control -and manage the PSSessions that you create. +Unlike the sessions that PowerShell creates for you, you control and manage the +PSSessions that you create. PSSessions play an important role in remote computing. When you create a -PSSession that is connected to a remote computer, PowerShell -establishes a persistent connection to the remote computer to support the -PSSession. You can use the PSSession to run a series of commands, -functions, and scripts that share data. +PSSession that is connected to a remote computer, PowerShell establishes a +persistent connection to the remote computer to support the PSSession. You can +use the PSSession to run a series of commands, functions, and scripts that +share data. -This topic provides detailed information about sessions and PSSessions -in PowerShell. For basic information about the tasks that you -can perform with sessions, see [about_PSSessions](about_PSSessions.md). +This topic provides detailed information about sessions and PSSessions in +PowerShell. For basic information about the tasks that you can perform with +sessions, see [about_PSSessions][01]. ## About Sessions -Technically, a session is an execution environment in which -PowerShell runs. Each session includes an instance of the -System.Management.Automation engine and a host program in which -PowerShell runs. The host can be the familiar PowerShell console -or another program that runs commands, such as Cmd.exe, or a program built -to host PowerShell, such as Windows PowerShell Integrated Scripting -Environment (ISE). From a Windows perspective, a session is a Windows +Technically, a session is an execution environment in which PowerShell runs. +Each session includes an instance of the System.Management.Automation engine +and a host program in which PowerShell runs. The host can be the familiar +PowerShell console or another program that runs commands, such as Cmd.exe, or +a program built to host PowerShell, such as Windows PowerShell Integrated +Scripting Environment (ISE). From a Windows perspective, a session is a Windows process on the target computer. -Each session is configured independently. It includes its own properties, -its own execution policy, and its own profiles. The environment that exists -when the session is created persists for its lifetime even if you change -the environment on the computer. All sessions are created in a global -scope, even sessions that you create in a script. +Each session is configured independently. It includes its own properties, its +own execution policy, and its own profiles. The environment that exists when +the session is created persists for its lifetime even if you change the +environment on the computer. All sessions are created in a global scope, even +sessions that you create in a script. -You can run only one command (or command pipeline) in a session at one -time. A second command run synchronously (one at a time) waits up to four -minutes for the first command to be completed. A second command run -asynchronously (concurrently) fails. +You can run only one command (or command pipeline) in a session at one time. +A second command run synchronously (one at a time) waits up to four minutes for +the first command to be completed. A second command run asynchronously +(concurrently) fails. ## About PSSessions -A session is created each time that you start PowerShell. And, -PowerShell creates temporary sessions to run individual commands. -However, you can also create sessions (called "PowerShell sessions" -or "PSSessions") that you control and manage. +A session is created each time that you start PowerShell. And, PowerShell +creates temporary sessions to run individual commands. However, you can also +create sessions (called "PowerShell sessions" or "PSSessions") that you control +and manage. PSSessions are critical to remote commands. If you use the **ComputerName** parameter of the `Invoke-Command` or `Enter-PSSession` cmdlets, PowerShell @@ -73,15 +72,15 @@ create remain open and available for use until you delete them or until you close the session in which they were created. When you create a PSSession on a remote computer, the system creates a -PowerShell process on the remote computer and establishes a connection -from the local computer to the process on the remote computer. When you -create a PSSession on the local computer, both the new process and the -connections are created on the local computer. +PowerShell process on the remote computer and establishes a connection from the +local computer to the process on the remote computer. When you create a +PSSession on the local computer, both the new process and the connections are +created on the local computer. ## When Do I Need a PSSession? -The `Invoke-Command` and `Enter-PSSession` cmdlets have both **ComputerName** and -**Session** parameters. You can use either to run a remote command. +The `Invoke-Command` and `Enter-PSSession` cmdlets have both **ComputerName** +and **Session** parameters. You can use either to run a remote command. Use the **ComputerName** parameter to run a single command or a series of unrelated commands on one or many computers. @@ -90,12 +89,11 @@ To run commands that share data, you need a persistent connection to the remote computer. In that case, create a PSSession, and then use the **Session** parameter to run commands in the PSSession. -Many other cmdlets that get data from remote computers, such as -`Get-Process`, `Get-Service`, `Get-EventLog`, and `Get-WmiObject` have only a -**ComputerName** parameter. They use technologies other than PowerShell -remoting to gather data remotely. These cmdlets do not have a **Session** -parameter, but you can use the `Invoke-Command` cmdlet to run these commands -in a PSSession. +Many other cmdlets that get data from remote computers, such as `Get-Process`, +`Get-Service`, `Get-EventLog`, and `Get-WmiObject` have only a **ComputerName** +parameter. They use technologies other than PowerShell remoting to gather data +remotely. These cmdlets do not have a **Session** parameter, but you can use +the `Invoke-Command` cmdlet to run these commands in a PSSession. ## How Do I Create a PSSession? @@ -105,114 +103,101 @@ To create a PSSession, use the `New-PSSession` cmdlet. You can use ## Can I Create a PSSession on Any Computer? To create a PSSession that is connected to a remote computer, the computer -must be configured for remoting in PowerShell. The current user -must be a member of the Administrators group on the remote computer, or -the current user must be able to supply the credentials of a member of -the Administrators group. For more information, -see [about_Remote_Requirements](about_Remote_Requirements.md). +must be configured for remoting in PowerShell. The current user must be a +member of the Administrators group on the remote computer, or the current user +must be able to supply the credentials of a member of the Administrators group. +For more information, see [about_Remote_Requirements][02]. ## Can I See My PSSessions in Other Sessions? -Beginning in Windows PowerShell 3.0, the **ComputerName** -parameter of the `Get-PSSession` cmdlet gets PSSessions -that you created on the specified remote computers. +Beginning in Windows PowerShell 3.0, the **ComputerName** parameter of the +`Get-PSSession` cmdlet gets PSSessions that you created on the specified +remote computers. -Active PSSessions are maintained on the remote computer -(the "server-side" of a connection) and you can get them -from any session on any computer. +Active PSSessions are maintained on the remote computer (the "server-side" of +a connection) and you can get them from any session on any computer. -For example, if you create a PSSession from the Server01 -computer to the Server02 computer, and then switch to the -Server03 computer, you can use a command like the following -one to get the session. +For example, if you create a PSSession from the Server01 computer to the +Server02 computer, and then switch to the Server03 computer, you can use a +command like the following one to get the session. ```powershell Get-PSSession -ComputerName Server02 ``` -Even if you disconnect from the session, the session is -maintained on the remote computer until you delete it or it -times out. - -In Windows PowerShell 2.0, you can get only the PSSessions -that you have created in the current session. You cannot get -PSSessions that you created in other sessions. +Even if you disconnect from the session, the session is maintained on the +remote computer until you delete it or it times out. -For more information, see [Get-PSSession](xref:Microsoft.PowerShell.Core.Get-PSSession). +In Windows PowerShell 2.0, you can get only the PSSessions that you have +created in the current session. You cannot get PSSessions that you created in +other sessions. For more information, see [Get-PSSession][03]. ## Can I See the PSSessions That Others Have Created on My Computer? -You can get and manage only the PSSessions that others have created -only if you can supply the credentials of the user who created the -PSSession or the session configuration that the PSSession uses -includes RunAs credentials. Otherwise, you can get, connect to, use, -and manage only the PSSessions that you created. +You can get and manage only the PSSessions that others have created only if you +can supply the credentials of the user who created the PSSession or the session +configuration that the PSSession uses includes RunAs credentials. Otherwise, +you can get, connect to, use, and manage only the PSSessions that you created. ## Can I Connect to a PSSession From a Different Computer? Beginning in Windows PowerShell 3.0, PSSessions on Windows computers are independent of the sessions in which they were created. Active PSSessions -are maintained on the computer at the remote or "server-side" of -a connection. +are maintained on the computer at the remote or "server-side" of a connection. On a Windows computer, you can use the `Disconnect-PSSession` cmdlet to disconnect from a PSSession. The PSSession is disconnected from the local session, but is maintained on the remote computer. -Commands continue to run in the disconnected PSSession. You -can close PowerShell and shut down the originating computer -without interrupting the PSSession. +Commands continue to run in the disconnected PSSession. You can close +PowerShell and shut down the originating computer without interrupting the +PSSession. -Then, even hours later, you can use the `Get-PSSession` cmdlet to -get the PSSession and the `Connect-PSSession` cmdlet to connect to the -PSSession from a new session on a different Windows computer. - -For more information, see [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md). +Then, even hours later, you can use the `Get-PSSession` cmdlet to get the +PSSession and the `Connect-PSSession` cmdlet to connect to the PSSession from +a new session on a different Windows computer. For more information, see +[about_Remote_Disconnected_Sessions][04]. ## What Happens to My PSSession if My Computer Stops? -Disconnected PSSessions are independent of the sessions -in which they were created. If you disconnect a PSSession -and then close the originating computer, the PSSession is -maintained on the remote computer. - -In addition, PowerShell attempts to recover active -PSSessions that are disconnected unintentionally, such as -by a computer reboot, a temporary power outage or network -disruption. PowerShell attempts to maintain or recover -the PSSession to an Opened state, if the originating session -is still available, or to a disconnected state if it is not. +Disconnected PSSessions are independent of the sessions in which they were +created. If you disconnect a PSSession and then close the originating computer, +the PSSession is maintained on the remote computer. -An "active" PSSession is one that is running commands. If -a PSSession is connected (not disconnected) and commands are -running in the PSSession when the connected session closes, -PowerShell attempts to maintain the PSSession on the -remote computer. However, if no commands are running in the -PSSession, PowerShell closes the PSSession when the -connected session closes. +In addition, PowerShell attempts to recover active PSSessions that are +disconnected unintentionally, such as by a computer reboot, a temporary power +outage or network disruption. PowerShell attempts to maintain or recover the +PSSession to an Opened state, if the originating session is still available, or +to a disconnected state if it is not. -For more information, see [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md). +An "active" PSSession is one that is running commands. If a PSSession is +connected (not disconnected) and commands are running in the PSSession when the +connected session closes, PowerShell attempts to maintain the PSSession on the +remote computer. However, if no commands are running in the PSSession, +PowerShell closes the PSSession when the connected session closes. For more +information, see [about_Remote_Disconnected_Sessions][04]. ## Can I Run a Background Job in a PSSession? -Yes. A background job is a command that runs asynchronously in the -background without interacting with the current session. When you submit -a command to start a job, the command returns a job object, but the job -continues to run in the background until it is complete. +Yes. A background job is a command that runs asynchronously in the background +without interacting with the current session. When you submit a command to +start a job, the command returns a job object, but the job continues to run in +the background until it is complete. To start a background job on a local computer, use the `Start-Job` command. You can run the background job in a temporary connection (by using the -**ComputerName** parameter) or in a PSSession (by using the **Session** parameter). +**ComputerName** parameter) or in a PSSession (by using the **Session** +parameter). To start a background job on a remote computer, use the `Invoke-Command` -cmdlet with its **AsJob** parameter, or use the `Invoke-Command` cmdlet to run a -`Start-Job` command on a remote computer. When using the **AsJob** parameter, +cmdlet with its **AsJob** parameter, or use the `Invoke-Command` cmdlet to run +a `Start-Job` command on a remote computer. When using the **AsJob** parameter, you can use the **ComputerName** or **Session** parameters. When using `Invoke-Command` to run a `Start-Job` command, you must run the command in a PSSession. If you use the **ComputerName** parameter, PowerShell ends the connection when the job object returns, and the job is interrupted. -For more information, see [about_Jobs](about_Jobs.md). +For more information, see [about_Jobs][05]. ## Can I Run an Interactive Session? @@ -222,15 +207,15 @@ type run on the remote computer, just as if you typed them directly on the remote computer. You can run an interactive session in a temporary session (by using the -**ComputerName** parameter) or in a PSSession (by using the **Session** parameter). -If you use a PSSession, the PSSession retains the data from previous -commands, and the PSSession retains any data generated during the +**ComputerName** parameter) or in a PSSession (by using the **Session** +parameter). If you use a PSSession, the PSSession retains the data from +previous commands, and the PSSession retains any data generated during the interactive session for use in later commands. When you end the interactive session, the PSSession remains open and available for use. -For more information, see [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) and [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession). +For more information, see [Enter-PSSession][06] and [Exit-PSSession][07]. ## Must I Delete the PSSessions? @@ -243,9 +228,9 @@ in use. To delete PSSessions, use the `Remove-PSSession` cmdlet. It deletes the PSSessions and releases all of the resources that they were using. -You can also use the **IdleTimeOut** parameter of `New-PSSessionOption` to close -an idle PSSession after an interval that you specify. For more information, -see [New-PSSessionOption](xref:Microsoft.PowerShell.Core.New-PSSessionOption). +You can also use the **IdleTimeOut** parameter of `New-PSSessionOption` to +close an idle PSSession after an interval that you specify. For more +information, see [New-PSSessionOption][08]. If you save a PSSession object in a variable and then delete the PSSession or let it time out, the variable still contains the PSSession object, but @@ -254,19 +239,33 @@ the PSSession is not active and cannot be used or repaired. ## Are All Sessions and PSSessions Alike? No. Developers can create custom sessions that include only selected -providers and cmdlets. If a command works in one session but not in -another, it might be because the session is restricted. +providers and cmdlets. If a command works in one session but not in another, +it might be because the session is restricted. ## See also -- [about_Jobs](about_Jobs.md) -- [about_PSSessions](about_PSSessions.md) -- [about_Remote](about_Remote.md) -- [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md) -- [about_Remote_Requirements](about_Remote_Requirements.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) -- [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) -- [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession) -- [Get-PSSession](xref:Microsoft.PowerShell.Core.Get-PSSession) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) -- [Remove-PSSession](xref:Microsoft.PowerShell.Core.Remove-PSSession) +- [about_Jobs][05] +- [about_PSSessions][01] +- [about_Remote][09] +- [about_Remote_Disconnected_Sessions][04] +- [about_Remote_Requirements][02] +- [Invoke-Command][10] +- [Enter-PSSession][06] +- [Exit-PSSession][07] +- [Get-PSSession][03] +- [New-PSSession][11] +- [Remove-PSSession][12] + + +[01]: about_PSSessions.md +[02]: about_Remote_Requirements.md +[03]: xref:Microsoft.PowerShell.Core.Get-PSSession +[04]: about_Remote_Disconnected_Sessions.md +[05]: about_Jobs.md +[06]: xref:Microsoft.PowerShell.Core.Enter-PSSession +[07]: xref:Microsoft.PowerShell.Core.Exit-PSSession +[08]: xref:Microsoft.PowerShell.Core.New-PSSessionOption +[09]: about_Remote.md +[10]: xref:Microsoft.PowerShell.Core.Invoke-Command +[11]: xref:Microsoft.PowerShell.Core.New-PSSession +[12]: xref:Microsoft.PowerShell.Core.Remove-PSSession diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_PSSessions.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_PSSessions.md index 5923d83a7a9f..8b600fdeabcf 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_PSSessions.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_PSSessions.md @@ -9,23 +9,24 @@ title: about_PSSessions # about_PSSessions ## Short description -Describes PowerShell sessions (PSSessions) and explains how to -establish a persistent connection to a remote computer. + +Describes PowerShell sessions (PSSessions) and explains how to establish a +persistent connection to a remote computer. ## Long description To run PowerShell commands on a remote computer, you can use the -**ComputerName** parameter of a cmdlet, or you can create a PowerShell -session (PSSession) and run commands in the PSSession. +**ComputerName** parameter of a cmdlet, or you can create a PowerShell session +(PSSession) and run commands in the PSSession. -When you create a PSSession, PowerShell establishes a persistent -connection to the remote computer. Use a PSSession to run a series of related -commands on a remote computer. Commands that run in the same PSSession can -share data, such as the values of variables, aliases, and functions. +When you create a PSSession, PowerShell establishes a persistent connection to +the remote computer. Use a PSSession to run a series of related commands on a +remote computer. Commands that run in the same PSSession can share data, such +as the values of variables, aliases, and functions. You can also create a PSSession on the local computer and run commands in it. -A local PSSession uses the PowerShell remoting infrastructure to -create and maintain the PSSession. +A local PSSession uses the PowerShell remoting infrastructure to create and +maintain the PSSession. Beginning in Windows PowerShell 3.0, PSSessions on Windows are independent of the sessions in which they are created. Active PSSessions are maintained @@ -35,36 +36,33 @@ on a remote Windows computer and reconnect to it at a later time from the same computer or from a different Windows computer. This topic explains how to create, use, get, and delete PSSessions. For more -advanced information, see -[about_PSSession_Details](about_PSSession_Details.md). +advanced information, see [about_PSSession_Details][01]. -Note: PSSessions use the PowerShell remoting infrastructure. To use -PSSessions, the local and remote computers must be configured for remoting. -For more information, see -[about_Remote_Requirements](about_Remote_Requirements.md). +Note: PSSessions use the PowerShell remoting infrastructure. To use PSSessions, +the local and remote computers must be configured for remoting. For more +information, see [about_Remote_Requirements][02]. In Windows Vista and later versions of Windows, to create a PSSession on a -local computer, you must start PowerShell with the "Run as -administrator" option. +local computer, you must start PowerShell with the "Run as administrator" +option. ## What Is a Session? A session is an environment in which PowerShell runs. -Each time you start PowerShell, a session is created for you, and you -can run commands in the session. You can also add items to your session, such -as modules and snap-ins, and you can create items, such as variables, -functions, and aliases. These items exist only in the session and are deleted -when the session ends. - -You can also create user-managed sessions, known as " PowerShell -sessions" or "PSSessions," on the local computer or on a remote computer. Like -the default session, you can run commands in a PSSession and add and create -items. However, unlike the session that starts automatically, you can control -the PSSessions that you create. You can get, create, configure, and remove -them, disconnect and reconnect to them, and run multiple commands in the same -PSSession. The PSSession remains available until you delete it or it times -out. +Each time you start PowerShell, a session is created for you, and you can run +commands in the session. You can also add items to your session, such as +modules and snap-ins, and you can create items, such as variables, functions, +and aliases. These items exist only in the session and are deleted when the +session ends. + +You can also create user-managed sessions, known as "PowerShell sessions" or +"PSSessions," on the local computer or on a remote computer. Like the default +session, you can run commands in a PSSession and add and create items. +However, unlike the session that starts automatically, you can control the +PSSessions that you create. You can get, create, configure, and remove them, +disconnect and reconnect to them, and run multiple commands in the same +PSSession. The PSSession remains available until you delete it or it times out. Typically, you create a PSSession to run a series of related commands on a remote computer. When you create a PSSession on a remote computer, PowerShell @@ -73,15 +71,14 @@ session. If you use the **ComputerName** parameter of the `Invoke-Command` or `Enter-PSSession` cmdlet to run a remote command or to start an interactive -session, PowerShell creates a temporary session on the remote computer -and closes the session as soon as the command is complete or as soon as the +session, PowerShell creates a temporary session on the remote computer and +closes the session as soon as the command is complete or as soon as the interactive session ends. You cannot control these temporary sessions, and you -cannot use them for more than a single command or a single interactive -session. +cannot use them for more than a single command or a single interactive session. -In PowerShell, the "current session" is the session that you are -working in. The "current session" can refer to any session, including a -temporary session or a PSSession. +In PowerShell, the "current session" is the session that you are working in. +The "current session" can refer to any session, including a temporary session +or a PSSession. ## Why Use a PSSession? @@ -95,10 +92,9 @@ You can run remote commands without creating a PSSession. Use the or a series of unrelated commands on one or many computers. When you use the **ComputerName** parameter of `Invoke-Command` or -`Enter-PSSession`, PowerShell establishes a temporary connection to -the remote computer and then closes the connection as soon as the command is -complete. Any data elements that you create are lost when the connection is -closed. +`Enter-PSSession`, PowerShell establishes a temporary connection to the remote +computer and then closes the connection as soon as the command is complete. +Any data elements that you create are lost when the connection is closed. Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` and `Get-WmiObject`, use different remoting technologies to gather data. None @@ -107,8 +103,8 @@ create a persistent connection like a PSSession. ## How to Create a PSSession To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession -on a remote computer, use the **ComputerName** parameter of the -`New-PSSession` cmdlet. +on a remote computer, use the **ComputerName** parameter of the `New-PSSession` +cmdlet. For example, the following command creates a new PSSession on the Server01 computer. @@ -150,7 +146,8 @@ To get the PSSessions that were created in your current session, use the `Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` returns the same type of object that `New-PSSession` returns. -The following command gets all the PSSessions that were created in the current session. +The following command gets all the PSSessions that were created in the current +session. ```powershell Get-PSSession @@ -238,7 +235,7 @@ until it times out. You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` cmdlet to set an expiration time for an idle PSSession. For more information, -see [New-PSSessionOption](xref:Microsoft.PowerShell.Core.New-PSSessionOption). +see [New-PSSessionOption][03]. ## The PSSession Cmdlets @@ -262,22 +259,37 @@ Get-Help *-PSSession > Disconnected sessions are only supported on Windows. The `Connect-PSSession`, > `Disconnect-PSSession`, and `Receive-PSSession` cmdlets are only available > on Windows. For more information about disconnected sessions, see -> [about_Remote_Disconnected_Session](about_Remote_Disconnected_Sessions.md) +> [about_Remote_Disconnected_Session][04]. ## For More Information -For more information about PSSessions, see [about_PSSession_Details](about_PSSession_Details.md). +For more information about PSSessions, see [about_PSSession_Details][01]. ## See also -- [about_Remote](about_Remote.md) -- [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md) -- [about_Remote_Requirements](about_Remote_Requirements.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) -- [Connect-PSSession](xref:Microsoft.PowerShell.Core.Connect-PSSession) -- [Disconnect-PSSession](xref:Microsoft.PowerShell.Core.Disconnect-PSSession) -- [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) -- [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession) -- [Get-PSSession](xref:Microsoft.PowerShell.Core.Get-PSSession) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) -- [Remove-PSSession](xref:Microsoft.PowerShell.Core.Remove-PSSession) +- [about_Remote][05] +- [about_Remote_Disconnected_Sessions][04] +- [about_Remote_Requirements][02] +- [Invoke-Command][06] +- [Connect-PSSession][07] +- [Disconnect-PSSession][08] +- [Enter-PSSession][09] +- [Exit-PSSession][10] +- [Get-PSSession][11] +- [New-PSSession][12] +- [Remove-PSSession][13] + + +[01]: about_PSSession_Details.md +[02]: about_Remote_Requirements.md +[03]: xref:Microsoft.PowerShell.Core.New-PSSessionOption +[04]: about_Remote_Disconnected_Sessions.md +[05]: about_Remote.md +[06]: xref:Microsoft.PowerShell.Core.Invoke-Command +[07]: xref:Microsoft.PowerShell.Core.Connect-PSSession +[08]: xref:Microsoft.PowerShell.Core.Disconnect-PSSession +[09]: xref:Microsoft.PowerShell.Core.Enter-PSSession +[10]: xref:Microsoft.PowerShell.Core.Exit-PSSession +[11]: xref:Microsoft.PowerShell.Core.Get-PSSession +[12]: xref:Microsoft.PowerShell.Core.New-PSSession +[13]: xref:Microsoft.PowerShell.Core.Remove-PSSession diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Pwsh.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Pwsh.md index 602ca62dfce0..d476a2025514 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Pwsh.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Pwsh.md @@ -1,7 +1,7 @@ --- description: Explains how to use the `pwsh` command-line interface. Displays the command-line parameters and describes the syntax. Locale: en-US -ms.date: 09/02/2024 +ms.date: 09/24/2024 no-loc: [-File, -f, -Command, -c, -CommandWithArgs, -cwa, -ConfigurationName, -config, -CustomPipeName, -EncodedCommand, -e, -ec, -ExecutionPolicy, -ex, -ep, -InputFormat, -inp, -if, -Interactive, -i, -Login, -l, -MTA, -NoExit, -noe, -NoLogo, -nol, -NonInteractive, -noni, -NoProfile, -nop, -OutputFormat, -o, -of, -SettingsFile, -settings, -SSHServerMode, -sshs, -STA, -Version, -v, -WindowStyle, -w, -WorkingDirectory, -wd, -Help] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_pwsh?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -10,6 +10,7 @@ title: about_Pwsh # about_Pwsh ## Short description + Explains how to use the `pwsh` command-line interface. Displays the command-line parameters and describes the syntax. @@ -107,11 +108,11 @@ Running `pwsh -File -` without redirected standard input starts a regular session. This is the same as not specifying the `File` parameter at all. When reading from standard input, the input statements are executed one statement at a time as though they were typed at the PowerShell command prompt. If a -statement doesn't parse correctly, the statement isn't executed. The process exit code is -determined by status of the last (executed) command within the input. With -normal termination, the exit code is always `0`. When the script file -terminates with an `exit` command, the process exit code is set to the numeric -argument used with the `exit` command. +statement doesn't parse correctly, the statement isn't executed. The process +exit code is determined by status of the last (executed) command within the +input. With normal termination, the exit code is always `0`. When the script +file terminates with an `exit` command, the process exit code is set to the +numeric argument used with the `exit` command. Similar to `-Command`, when a script-terminating error occurs, the exit code is set to `1`. However, unlike with `-Command`, when the execution is interrupted @@ -151,7 +152,7 @@ script block curly braces are often not required in the first place when running from `cmd.exe`. To execute an inline script block defined inside a string, the [call operator][03] `&` can be used: -``` +```powershell pwsh -Command "& {Get-WinEvent -LogName security}" ``` @@ -287,7 +288,7 @@ For example: $command = 'dir "c:\program files" ' $bytes = [System.Text.Encoding]::Unicode.GetBytes($command) $encodedCommand = [Convert]::ToBase64String($bytes) -pwsh -encodedcommand $encodedCommand +pwsh -EncodedCommand $encodedCommand ``` ### -ExecutionPolicy | -ex | -ep @@ -324,7 +325,8 @@ To set up `pwsh` as the login shell on UNIX-like operating systems: - Verify that the full absolute path to `pwsh` is listed under `/etc/shells` - This path is usually something like `/usr/bin/pwsh` on Linux or `/usr/local/bin/pwsh` on macOS - - With some installation methods, this entry will be added automatically at installation time + - With some installation methods, this entry will be added automatically at + installation time - If `pwsh` isn't present in `/etc/shells`, use an editor to append the path to `pwsh` on the last line. This requires elevated privileges to edit. - Use the [chsh][04] utility to set your current @@ -406,7 +408,8 @@ non-Windows platforms results in an error. ### -Version | -v -Displays the version of this PowerShell executable. Additional parameters are ignored. +Displays the version of this PowerShell executable. Additional parameters are +ignored. ### -WindowStyle | -w @@ -429,6 +432,6 @@ prepend the command parameters with a hyphen (`-`), not a forward slash (`/`). [01]: /powershell/module/microsoft.powershell.core/about/about_powershell_exe?view=powershell-5.1&preserve-view=true [02]: about_Automatic_Variables.md#lastexitcode -[03]: about_operators.md#special-operators +[03]: about_Operators.md#special-operators [04]: https://linux.die.net/man/1/chsh [05]: about_Parsing.md#passing-arguments-that-contain-quote-characters diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 85e7ebe04a26..a3828c866d93 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -9,6 +9,7 @@ title: about_Quoting_Rules # about_Quoting_Rules ## Short description + Describes rules for using single and double quotation marks in PowerShell. ## Long description @@ -464,7 +465,7 @@ For more information about this behavior, see the [about_Parsing][03] article. [01]: #including-quote-characters-in-a-string [02]: about_Parsing.md#argument-mode [03]: about_Parsing.md#passing-arguments-that-contain-quote-characters -[04]: about_preference_variables.md#ofs +[04]: about_Preference_Variables.md#ofs [05]: about_Special_Characters.md [06]: https://en.wikipedia.org/wiki/Quotation_marks_in_English#Smart_quotes [07]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md index 9a840ba31a31..7e18fa41ea17 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -9,13 +9,14 @@ title: about_Redirection # about_Redirection ## Short description + Explains how to redirect output from PowerShell to text files. ## Long description By default, PowerShell sends output to the PowerShell host. Usually this is the -console application. However, you can redirect the output to a text file and you -can redirect error output to the regular output stream. +console application. However, you can redirect the output to a text file and +you can redirect error output to the regular output stream. You can use the following methods to redirect output: @@ -78,8 +79,7 @@ PowerShell 7.4 changed the behavior of the redirection operators when used to redirect the **stdout** stream of a native command. The redirection operators now preserve the byte-stream data when redirecting output from a native command. PowerShell doesn't interpret the redirected data or add any additional -formatting. For more information, see -[Example #7](#example-7-redirecting-binary-data-from-a-native-command). +formatting. For more information, see [Example #7][17]. ## Examples @@ -133,8 +133,7 @@ file called `script.log`. ### Example 5: Suppress all Write-Host and Information stream data This example suppresses all information stream data. To read more about -**Information** stream cmdlets, see -[Write-Host][11] and +**Information** stream cmdlets, see [Write-Host][11] and [Write-Information][12] ```powershell @@ -153,27 +152,27 @@ particular stream. The script in this example shows how the value of ```powershell $ErrorActionPreference = 'Continue' $ErrorActionPreference > log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'SilentlyContinue' $ErrorActionPreference >> log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'Stop' $ErrorActionPreference >> log.txt Try { - get-item /not-here 2>&1 >> log.txt + Get-Item /not-here 2>&1 >> log.txt } catch { "`tError caught!" >> log.txt } $ErrorActionPreference = 'Ignore' $ErrorActionPreference >> log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'Inquire' $ErrorActionPreference >> log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'Continue' ``` @@ -386,7 +385,7 @@ used. For more information, see the `-gt` operator in [03]: about_Operators.md [04]: about_Output_Streams.md [05]: about_Path_Syntax.md -[06]: about_preference_variables.md#psdefaultparametervalues +[06]: about_Preference_Variables.md#psdefaultparametervalues [07]: xref:Microsoft.PowerShell.Utility.Out-File [08]: xref:Microsoft.PowerShell.Utility.Tee-Object [09]: xref:Microsoft.PowerShell.Utility.Write-Debug @@ -397,3 +396,4 @@ used. For more information, see the `-gt` operator in [14]: xref:Microsoft.PowerShell.Utility.Write-Progress [15]: xref:Microsoft.PowerShell.Utility.Write-Verbose [16]: xref:Microsoft.PowerShell.Utility.Write-Warning +[17]: #example-7-redirecting-binary-data-from-a-native-command diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Ref.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Ref.md index 29cfa3048727..364f117031c1 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Ref.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Ref.md @@ -42,7 +42,7 @@ Test -data $var $var ``` -```output +```Output 10 ``` @@ -64,7 +64,7 @@ Test -data $var $var ``` -```output +```Output Name Value ---- ----- Test New Text @@ -101,21 +101,21 @@ Test -data ([ref]$var) $var ``` -```output +```Output 3 ``` ## Passing references to .NET methods -Some .NET methods may require you to pass a variable as a reference. When -the method's definition uses the keywords `in`, `out`, or `ref` on a -parameter, it expects a reference. +Some .NET methods may require you to pass a variable as a reference. When the +method's definition uses the keywords `in`, `out`, or `ref` on a parameter, it +expects a reference. ```powershell [int] | Get-Member -Static -Name TryParse ``` -```output +```Output Name MemberType Definition ---- ---------- ---------- TryParse Method static bool TryParse(string s, [ref] int result) @@ -149,7 +149,7 @@ $iRef = [ref]0 "`$i = $i;`$iRef = $($iRef.Value)" ``` -```output +```Output $i = 0;$iRef = 1 ``` @@ -188,8 +188,8 @@ specifying the `[System.Management.Automation.PSReference]` type directly. Even though `[ref]` is a type accelerator for `[System.Management.Automation.PSReference]`, they behave differently. -- When you use `[ref]` to cast a variable, PowerShell creates a reference object - that contains a reference to the original instance of the variable. +- When you use `[ref]` to cast a variable, PowerShell creates a reference + object that contains a reference to the original instance of the variable. - When you use `[System.Management.Automation.PSReference]` to cast a variable, PowerShell creates a reference object that contains a copy of the variable, rather than a reference to the original instance. @@ -243,7 +243,7 @@ Value [01]: about_Environment_Variables.md [02]: about_Functions.md -[03]: about_scopes.md +[03]: about_Scopes.md [04]: about_Script_Blocks.md [05]: about_Type_Accelerators.md [06]: about_Variables.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Registry_Provider.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Registry_Provider.md index 7e6527b79384..26996a7aa4bc 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Registry_Provider.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Registry_Provider.md @@ -28,8 +28,8 @@ Provides access to the registry keys, entries, and values in PowerShell. > This information only applies to PowerShell running on Windows. -The PowerShell **Registry** provider lets you get, add, change, -clear, and delete registry keys, entries, and values in PowerShell. +The PowerShell **Registry** provider lets you get, add, change, clear, and +delete registry keys, entries, and values in PowerShell. The **Registry** drives are a hierarchical namespace containing the registry keys and subkeys on your computer. Registry entries and values aren't diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 255b1d3bb923..a9a6792d4d23 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -9,6 +9,7 @@ title: about_Regular_Expressions # about_Regular_Expressions ## Short description + Describes regular expressions in PowerShell. ## Long description @@ -36,7 +37,7 @@ shown above has a different way to force case sensitivity. - For `Select-String`, use the **CaseSensitive** parameter. - For operators that use regular expressions, use the case-sensitive version: `-cmatch`, `-creplace`, or `-csplit` -- For the `switch` statement, use the `-casesensitive` option +- For the `switch` statement, use the `-CaseSensitive` option ## Character literals @@ -353,7 +354,7 @@ The provided regular expression extracts the username and domain from the message and stores them under the keys:**N** for name and **D** for domain. ```powershell -$log = (Get-WinEvent -LogName Security -MaxEvents 1).message +$log = (Get-WinEvent -LogName Security -MaxEvents 1).Message $r = '(?s).*Account Name:\s*(?.*).*Account Domain:\s*(?[A-Z,0-9]*)' $log -match $r ``` diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md index 51be96c3b685..1b423ed3eb89 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md @@ -37,7 +37,8 @@ The following cmdlets support the Disconnected Sessions feature: - `Connect-PSSession`: Connects to a disconnected PSSession. - `Disconnect-PSSession`: Disconnects a PSSession. -- `Get-PSSession`: Gets PSSessions on the local computer or on remote computers. +- `Get-PSSession`: Gets PSSessions on the local computer or on remote + computers. - `Receive-PSSession`: Gets the results of commands that ran in disconnected sessions. - `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and @@ -56,7 +57,7 @@ created ends. When you disconnect a PSSession, the PSSession remains active and is maintained on the remote computer. The session state changes from **Running** to -**Disconnected**. You can reconnect to a disconnected PSSession from +**Disconnected**. You can reconnect to a disconnected PSSession from: - The current session on the same computer - A different session on the same computer diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md index 620d0d255c75..6a06273789f8 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md @@ -9,6 +9,7 @@ title: about_Remote_Jobs # about_Remote_Jobs ## Short description + Describes how to run background jobs on remote computers. ## Detailed Description @@ -82,10 +83,11 @@ all of the operations occur on the remote computer, not the local computer. use the Session parameter to run the interactive session in a PowerShell session (PSSession). - The following command starts an interactive session on the Server01 computer. + The following command starts an interactive session on the Server01 + computer. ```powershell - C:\PS> Enter-PSSession -computername Server01 + C:\PS> Enter-PSSession -ComputerName Server01 ``` The command prompt changes to show that you are now connected to the @@ -103,8 +105,8 @@ all of the operations occur on the remote computer, not the local computer. This command saves the job object in the `$job` variable. ```powershell - Server01\C:> $job = Start-Job -scriptblock { - Get-Eventlog "Windows PowerShell" + Server01\C:> $job = Start-Job -ScriptBlock { + Get-EventLog "Windows PowerShell" } ``` @@ -122,7 +124,7 @@ all of the operations occur on the remote computer, not the local computer. SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 1 Job1 Complete True localhost Get-Eventlog "Windows... + 1 Job1 Complete True localhost Get-EventLog "Windows... ``` The `Get-Job` output shows that job is running on the "localhost" computer @@ -161,8 +163,8 @@ all of the operations occur on the remote computer, not the local computer. view the contents of the file. ```powershell - $s = New-PSSession -computername Server01 - Invoke-Command -session $s -scriptblock { + $s = New-PSSession -ComputerName Server01 + Invoke-Command -Session $s -ScriptBlock { Get-Content c:\logs\pslog.txt} ``` @@ -188,8 +190,8 @@ requirements for remoting. assign a display name to the job. ```powershell - Invoke-Command -computername Server01 -scriptblock { - Get-Eventlog system} -AsJob + Invoke-Command -Computername Server01 -ScriptBlock { + Get-EventLog system} -AsJob ``` The results of the command resemble the following sample output. @@ -197,7 +199,7 @@ requirements for remoting. ```Output SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 1 Job1 Running True Server01 Get-Eventlog system + 1 Job1 Running True Server01 Get-EventLog system ``` When the **AsJob** parameter is used, `Invoke-Command` returns the same type @@ -227,7 +229,7 @@ requirements for remoting. ```Output SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 1 Job1 Completed True Server01 Get-Eventlog system + 1 Job1 Completed True Server01 Get-EventLog system ``` 1. To get the results of the job, use the `Receive-Job` cmdlet. Because the job @@ -240,7 +242,7 @@ requirements for remoting. file. ```powershell - $results = Receive-Job -id 1 + $results = Receive-Job -Id 1 ``` ### Start a remote job that keeps the results on the remote computer @@ -269,7 +271,7 @@ commands remotely to manage a local job on the remote computer. in the `$s` variable. ```powershell - $s = New-PSSession -computername Server01 + $s = New-PSSession -ComputerName Server01 ``` The next command uses the `Invoke-Command` cmdlet to run a `Start-Job` @@ -277,8 +279,8 @@ commands remotely to manage a local job on the remote computer. command are enclosed in braces. ```powershell - Invoke-Command -session $s -scriptblock { - Start-Job -scriptblock {Get-Eventlog system}} + Invoke-Command -Session $s -ScriptBlock { + Start-Job -ScriptBlock {Get-EventLog system}} ``` The results resemble the following sample output. @@ -286,7 +288,7 @@ commands remotely to manage a local job on the remote computer. ```Output Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- - 2 Job2 Running True Localhost Get-Eventlog system + 2 Job2 Running True Localhost Get-EventLog system ``` When you run a `Start-Job` command remotely, `Invoke-Command` returns the @@ -308,7 +310,7 @@ commands remotely to manage a local job on the remote computer. computer. ```powershell - Invoke-Command -session $s -scriptblock {Get-Job} + Invoke-Command -Session $s -ScriptBlock {Get-Job} ``` The command returns a job object. The **State** property of the job object @@ -317,7 +319,7 @@ commands remotely to manage a local job on the remote computer. ```Output SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 2 Job2 Completed True LocalHost Get-Eventlog system + 2 Job2 Completed True LocalHost Get-EventLog system ``` 1. To get the results of the job, use the `Invoke-Command` cmdlet to run a @@ -330,7 +332,7 @@ commands remotely to manage a local job on the remote computer. `Receive-Job` to keep the result in the job cache on the remote computer. ```powershell - $results = Invoke-Command -session $s -scriptblock { + $results = Invoke-Command -Session $s -ScriptBlock { Receive-Job -SessionId 2 -Keep } ``` @@ -340,7 +342,7 @@ commands remotely to manage a local job on the remote computer. file on the Server01 computer. ```powershell - Invoke-Command -session $s -command { + Invoke-Command -Session $s -Command { Receive-Job -SessionId 2 > c:\logs\pslog.txt } ``` diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md index 67b5c72507e8..192241985eb7 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md @@ -76,8 +76,8 @@ For errors: > - ERROR: ACCESS IS DENIED > - ERROR: The connection to the remote host was refused. Verify that the -> WS-Management service is running on the remote host and configured to listen -> for requests on the correct port and HTTP URL. +> WS-Management service is running on the remote host and configured to +> listen for requests on the correct port and HTTP URL. Enable the **Allow automatic configuration of listeners** policy to configure the listeners for all computers in a domain. @@ -136,7 +136,6 @@ The `Set-NetFirewallRule` cmdlet is exported by the **NetSecurity** module. For errors: > - ERROR: ACCESS IS DENIED - > - ERROR: The connection to the remote host was refused. Verify that the > WS-Management service is running on the remote host and configured to > listen for requests on the correct port and HTTP URL. diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index b9a88bbfa2f5..fff210da9439 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -77,10 +77,11 @@ $ps = "*PowerShell*" Invoke-Command -Session $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} ``` -A variable reference such as `$using:var` expands to the value of variable `$var` -from the caller's context. You do not get access to the caller's variable object. -The `Using` scope modifier cannot be used to modify a local variable within the -**PSSession**. For example, the following code does not work: +A variable reference such as `$using:var` expands to the value of variable +`$var` from the caller's context. You do not get access to the caller's +variable object. The `Using` scope modifier cannot be used to modify a local +variable within the **PSSession**. For example, the following code does not +work: ```powershell $s = New-PSSession -ComputerName S1 diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Requires.md index 7339427e428c..9cf0b546ac7e 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Requires.md @@ -16,9 +16,9 @@ Prevents a script from running without the required elements. ## Long description The `#Requires` statement prevents a script from running unless the PowerShell -version, modules (and version), and edition -prerequisites are met. If the prerequisites aren't met, PowerShell doesn't run -the script or provide other runtime features, such as tab completion. +version, modules (and version), and edition prerequisites are met. If the +prerequisites aren't met, PowerShell doesn't run the script or provide other +runtime features, such as tab completion. ### Syntax diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Return.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Return.md index 103d765ff1a3..527eeca6254f 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Return.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Return.md @@ -28,8 +28,8 @@ return only the value or values that are specified by the `return` keyword. > [!NOTE] > Beginning in PowerShell 5.0, PowerShell added language for defining > classes, by using formal syntax. In the context of a PowerShell class, -> nothing is output from a method except what you specify using a -> `return` statement. You can read more about PowerShell classes in +> nothing is output from a method except what you specify using a `return` +> statement. You can read more about PowerShell classes in > [about_Classes](about_Classes.md). ### Syntax @@ -67,7 +67,7 @@ function MultiplyEven 1..10 | ForEach-Object {MultiplyEven -Number $_} ``` -```output +```Output 1 is not even 4 3 is not even @@ -125,7 +125,7 @@ by the function and assigned to the `$a` variable. If you would like to display a message within your function, beginning in PowerShell 5.0, you can use the `Information` stream. The code below corrects the above example using the `Write-Information` cmdlet with a -`InformationAction` of **Continue**. +**InformationAction** set to `Continue`. ```powershell function calculation { @@ -135,13 +135,15 @@ function calculation { $value += 73 return $value } - -$a = calculation 14 ``` -```output +Now the information message to display in the host and not assigned to the +variable. + +```powershell +PS> $a = calculation 14 Please wait. Working on calculation... -C:\PS> $a +PS> $a 87 ``` diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md index 4128b86b89e5..f20c3b47322f 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md @@ -28,8 +28,8 @@ To use the **Run with PowerShell** feature: In File Explorer (or Windows Explorer), right-click the script filename and then select **Run with PowerShell**. -The **Run with PowerShell** feature starts a Windows PowerShell session that has -an execution policy of Bypass, runs the script, and closes the session. +The **Run with PowerShell** feature starts a Windows PowerShell session that +has an execution policy of Bypass, runs the script, and closes the session. It runs a command that has the following format: diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md index 0b3f8a4c5c37..1b8c9cc330a4 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md @@ -9,6 +9,7 @@ title: about_Script_Internationalization # about_Script_Internationalization ## Short description + Describes the script internationalization features that make it easy for scripts to display messages and instructions to users in their user interface (UI) language. @@ -30,8 +31,7 @@ To support international Help text, PowerShell includes the following features: - A Data section that separates text strings from code instructions. For more - information about the Data section, see - [about_Data_Sections](about_Data_Sections.md). + information about the Data section, see [about_Data_Sections][01]. - New automatic variables, `$PSCulture` and `$PSUICulture`. `$PSCulture` stores the name of the UI language used on the system for elements such as the date, @@ -41,7 +41,7 @@ features: - A cmdlet, `ConvertFrom-StringData`, that converts text strings into dictionary-like hash tables to facilitate translation. For more information, - see [ConvertFrom-StringData](xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData). + see [ConvertFrom-StringData][02]. - A new file type, `.psd1`, that stores translated text strings. The `.psd1` files are stored in language-specific subdirectories of the script directory. @@ -49,7 +49,7 @@ features: - A cmdlet, `Import-LocalizedData`, that imports translated text strings for a specified language into a script at runtime. This cmdlet recognizes and imports strings in any Windows-supported language. For more information see - [Import-LocalizedData](xref:Microsoft.PowerShell.Utility.Import-LocalizedData). + [Import-LocalizedData][03]. ### The Data Section: Storing Default Strings @@ -78,8 +78,7 @@ $msgTable = Data { } ``` -For more information about here-strings, see -[about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see [about_Quoting_Rules][04]. ### PSD1 Files: Storing Translated Strings @@ -241,9 +240,18 @@ Heute ist Freitag ## See also -- [about_Data_Sections](about_Data_Sections.md) -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_Quoting_Rules](about_Quoting_Rules.md) -- [Import-LocalizedData](xref:Microsoft.PowerShell.Utility.Import-LocalizedData) -- [ConvertFrom-StringData](xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData) +- [about_Data_Sections][01] +- [about_Automatic_Variables][05] +- [about_Hash_Tables][06] +- [about_Quoting_Rules][07] +- [Import-LocalizedData][03] +- [ConvertFrom-StringData][02] + + +[01]: about_Data_Sections.md +[02]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData +[03]: xref:Microsoft.PowerShell.Utility.Import-LocalizedData +[04]: about_Quoting_Rules.md +[05]: about_Automatic_Variables.md +[06]: about_Hash_Tables.md +[07]: about_Quoting_Rules.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Scripts.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Scripts.md index 49c8a2a67014..3301c8a4bb41 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Scripts.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Scripts.md @@ -9,6 +9,7 @@ title: about_Scripts # about_Scripts ## Short description + Describes how to run and write scripts in PowerShell. ## Long description @@ -37,7 +38,7 @@ running on non-Windows platforms. The default execution policy, `Restricted`, prevents all scripts from running, including scripts that you write on the local computer. For more information, -see [about_Execution_Policies](about_Execution_Policies.md). +see [about_Execution_Policies][01]. The execution policy is saved in the registry, so you need to change it only once on each computer. @@ -91,7 +92,7 @@ As a security feature, PowerShell does not run scripts when you double-click the script icon in File Explorer or when you type the script name without a full path, even when the script is in the current directory. For more information about running commands and scripts in PowerShell, see -[about_Command_Precedence](about_Command_Precedence.md). +[about_Command_Precedence][02]. ### Run with PowerShell @@ -105,12 +106,12 @@ PowerShell". The "Run with PowerShell" feature is designed to run scripts that do not have required parameters and do not return output to the command prompt. -For more information, see [about_Run_With_PowerShell](about_Run_With_PowerShell.md). +For more information, see [about_Run_With_PowerShell][03]. ### Running scripts on other computers -To run a script on one or more remote computers, use the **FilePath** parameter of -the `Invoke-Command` cmdlet. +To run a script on one or more remote computers, use the **FilePath** parameter +of the `Invoke-Command` cmdlet. Enter the path and filename of the script as the value of the **FilePath** parameter. The script must reside on the local computer or in a directory that @@ -120,8 +121,11 @@ The following command runs the `Get-ServiceLog.ps1` script on the remote computers named Server01 and Server02. ```powershell -Invoke-Command -ComputerName Server01,Server02 -FilePath ` - C:\Scripts\Get-ServiceLog.ps1 +$invokeCommandSplat = @{ + ComputerName = 'Server01', 'Server02' + FilePath = 'C:\Scripts\Get-ServiceLog.ps1' +} +Invoke-Command @invokeCommandSplat ``` ## Get help for scripts @@ -134,7 +138,7 @@ path is in your `Path` environment variable, you can omit the path. For example, to get help for the ServicesLog.ps1 script, type: ```powershell -get-help C:\admin\scripts\ServicesLog.ps1 +Get-Help C:\admin\scripts\ServicesLog.ps1 ``` ## How to write a script @@ -151,8 +155,8 @@ running on the current system and saves them to a log file. The log filename is created from the current date. ```powershell -$date = (get-date).dayofyear -get-service | out-file "$date.log" +$date = (Get-Date).DayOfYear +Get-Service | Out-File "$date.log" ``` To create this script, open a text editor or a script editor, type these @@ -180,22 +184,22 @@ The following example shows a `Test-Remote.ps1` script that has a param ($ComputerName = $(throw "ComputerName parameter is required.")) function CanPing { - $error.clear() - $tmp = test-connection $computername -erroraction SilentlyContinue + $error.Clear() + $tmp = Test-Connection $computername -ErrorAction SilentlyContinue if (!$?) - {write-host "Ping failed: $ComputerName."; return $false} + {Write-Host "Ping failed: $ComputerName."; return $false} else - {write-host "Ping succeeded: $ComputerName"; return $true} + {Write-Host "Ping succeeded: $ComputerName"; return $true} } function CanRemote { - $s = new-pssession $computername -erroraction SilentlyContinue + $s = New-PSSession $computername -ErrorAction SilentlyContinue if ($s -is [System.Management.Automation.Runspaces.PSSession]) - {write-host "Remote test succeeded: $ComputerName."} + {Write-Host "Remote test succeeded: $ComputerName."} else - {write-host "Remote test failed: $ComputerName."} + {Write-Host "Remote test failed: $ComputerName."} } if (CanPing $computername) {CanRemote $computername} @@ -204,15 +208,14 @@ if (CanPing $computername) {CanRemote $computername} To run this script, type the parameter name after the script name. For example: ```powershell -C:\PS> .\test-remote.ps1 -computername Server01 +C:\PS> .\test-remote.ps1 -ComputerName Server01 Ping succeeded: Server01 Remote test failed: Server01 ``` For more information about the Param statement and the function parameters, see -[about_Functions](about_Functions.md) and -[about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md). +[about_Functions][04] and [about_Functions_Advanced_Parameters][05]. ### Writing help for scripts @@ -224,7 +227,7 @@ methods: Create a Help topic by using special keywords in the comments. To create comment-based Help for a script, the comments must be placed at the beginning or end of the script file. For more information about comment-based Help, see - [about_Comment_Based_Help](about_Comment_Based_Help.md). + [about_Comment_Based_Help][06]. - XML-Based Help for Scripts @@ -234,9 +237,8 @@ methods: To associate the script with the XML-based Help topic, use the .ExternalHelp Help comment keyword. For more information about the ExternalHelp keyword, see -[about_Comment_Based_Help](about_Comment_Based_Help.md). For more information -about XML-based help, see -[How to Write Cmdlet Help](/powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets). +[about_Comment_Based_Help][06]. For more information about XML-based help, see +[How to Write Cmdlet Help][07]. ### Returning an exit value @@ -303,12 +305,12 @@ function and the `$ProfileName` variable. function New-Profile { Write-Host "Running New-Profile function" - $profileName = split-path $profile -leaf + $profileName = Split-Path $profile -Leaf - if (test-path $profile) - {write-error "Profile $profileName already exists on this computer."} + if (Test-Path $profile) + {Write-Error "Profile $profileName already exists on this computer."} else - {new-item -type file -path $profile -force } + {New-Item -Type file -Path $profile -Force } } ``` @@ -352,7 +354,7 @@ C:\PS> $profileName Microsoft.PowerShellISE_profile.ps1 ``` -For more information about scope, see [about_Scopes](about_Scopes.md). +For more information about scope, see [about_Scopes][08]. ## Scripts in modules @@ -366,7 +368,7 @@ which is a module that consists entirely or primarily of a script and supporting resources. A script module is just a script with a .psm1 file extension. -For more information about modules, see [about_Modules](about_Modules.md). +For more information about modules, see [about_Modules][09]. ## Other script features @@ -374,7 +376,7 @@ PowerShell has many useful features that you can use in scripts. - `#Requires` - You can use a `#Requires` statement to prevent a script from running without specified modules or snap-ins and a specified version of - PowerShell. For more information, see [about_Requires](about_Requires.md). + PowerShell. For more information, see [about_Requires][10]. - `$PSCommandPath` - Contains the full path and name of the script that is being run. This parameter is valid in all scripts. This automatic variable is @@ -397,11 +399,11 @@ PowerShell has many useful features that you can use in scripts. script. The values of these properties are populated only when the invoker or caller is a script. - - **PSCommandPath** contains the full path and name of the script that called or - invoked the current script. + - **PSCommandPath** contains the full path and name of the script that called + or invoked the current script. - - **PSScriptRoot** contains the directory of the script that called or invoked - the current script. + - **PSScriptRoot** contains the directory of the script that called or + invoked the current script. Unlike the `$PSCommandPath` and `$PSScriptRoot` automatic variables, which contain information about the current script, the **PSCommandPath** and @@ -410,26 +412,43 @@ PowerShell has many useful features that you can use in scripts. - Data sections - You can use the `Data` keyword to separate data from logic in scripts. Data sections can also make localization easier. For more - information, see [about_Data_Sections](about_Data_Sections.md) and - [about_Script_Internationalization](about_Script_Internationalization.md). + information, see [about_Data_Sections][11] and + [about_Script_Internationalization][12]. - Script Signing - You can add a digital signature to a script. Depending on the execution policy, you can use digital signatures to restrict the running of scripts that could include unsafe commands. For more information, see - [about_Execution_Policies](about_Execution_Policies.md) and - [about_Signing](about_Signing.md). + [about_Execution_Policies][01] and [about_Signing][13]. ## See also -- [about_Command_Precedence](about_Command_Precedence.md) -- [about_Comment_Based_Help](about_Comment_Based_Help.md) -- [about_Execution_Policies](about_Execution_Policies.md) -- [about_Functions](about_Functions.md) -- [about_Modules](about_Modules.md) -- [about_Profiles](about_Profiles.md) -- [about_Requires](about_Requires.md) -- [about_Run_With_PowerShell](about_Run_With_PowerShell.md) -- [about_Scopes](about_Scopes.md) -- [about_Script_Blocks](about_Script_Blocks.md) -- [about_Signing](about_Signing.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) +- [about_Command_Precedence][02] +- [about_Comment_Based_Help][06] +- [about_Execution_Policies][01] +- [about_Functions][04] +- [about_Modules][09] +- [about_Profiles][14] +- [about_Requires][10] +- [about_Run_With_PowerShell][03] +- [about_Scopes][08] +- [about_Script_Blocks][15] +- [about_Signing][13] +- [Invoke-Command][16] + + +[01]: about_Execution_Policies.md +[02]: about_Command_Precedence.md +[03]: about_Run_With_PowerShell.md +[04]: about_Functions.md +[05]: about_Functions_Advanced_Parameters.md +[06]: about_Comment_Based_Help.md +[07]: /powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets +[08]: about_Scopes.md +[09]: about_Modules.md +[10]: about_Requires.md +[11]: about_Data_Sections.md +[12]: about_Script_Internationalization.md +[13]: about_Signing.md +[14]: about_Profiles.md +[15]: about_Script_Blocks.md +[16]: xref:Microsoft.PowerShell.Core.Invoke-Command diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md index 8a82fd62196f..626270053301 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md @@ -9,6 +9,7 @@ title: about_Session_Configuration_Files # about_Session_Configuration_Files ## Short description + Describes session configuration files, which are used in a session configuration (also known as an "endpoint") to define the environment of sessions that use the session configuration. @@ -20,8 +21,8 @@ sessions that use the session configuration. A "session configuration file" is a text file with a .pssc file name extension that contains a hash table of session configuration properties and values. You can use a session configuration file to set the properties of a session -configuration. Doing so defines the environment of any PowerShell -sessions that use that session configuration. +configuration. Doing so defines the environment of any PowerShell sessions that +use that session configuration. Session configuration files make it easy to create custom session configurations without using complex C# assemblies or scripts. @@ -30,7 +31,7 @@ A "session configuration" or "endpoint" is a collection of local computer settings that determine such things as which users can create sessions on the computer; which commands users can run in those sessions; and whether the session should run as a privileged virtual account. For more information about -session configurations, see [about_Session_Configurations](about_Session_Configurations.md). +session configurations, see [about_Session_Configurations][01]. Session configurations were introduced in Windows PowerShell 2.0, and session configuration files were introduced in Windows PowerShell 3.0. You must use @@ -40,9 +41,9 @@ affected by the settings in the session configuration. ## Creating Custom Sessions -You can customize many features of a PowerShell session by specifying -session properties in a session configuration. You can customize a session by -writing a C# program that defines a custom runspace, or you can use a session +You can customize many features of a PowerShell session by specifying session +properties in a session configuration. You can customize a session by writing a +C# program that defines a custom runspace, or you can use a session configuration file to define the properties of sessions created by using the session configuration. As a general rule, it is easier to use the session configuration file than to write a C# program. @@ -54,25 +55,25 @@ the modules required for those tasks; and sessions where unprivileged users can only run specific commands as a privileged account. In addition to that, you can manage whether users of the session can use -PowerShell language elements such as script blocks, or whether they -can only run commands. You can manage the version of PowerShell users -can run in the session; manage which modules are imported into the session; -and manage which cmdlets, functions, and aliases session users can run. When -using the RoleDefinitions field, you can give users different capabilities in -the session based on group membership. +PowerShell language elements such as script blocks, or whether they can only +run commands. You can manage the version of PowerShell users can run in the +session; manage which modules are imported into the session; and manage which +cmdlets, functions, and aliases session users can run. When using the +RoleDefinitions field, you can give users different capabilities in the session +based on group membership. For more information about RoleDefinitions and how to define this Value, see -the help topic for the New-PSRoleCapabilityFile Cmdlet. +the help topic for the `New-PSRoleCapabilityFile` Cmdlet. ## Creating a Session Configuration File The easiest way to create a session configuration file is by using the -New-PSSessionConfigurationFile cmdlet. This cmdlet generates a file that uses +`New-PSSessionConfigurationFile` cmdlet. This cmdlet generates a file that uses the correct syntax and format, and that automatically verifies many of the configuration file property values. For detailed descriptions of the properties that you can set in a session -configuration file, see the help topic for the New-PSSessionConfigurationFile +configuration file, see the help topic for the `New-PSSessionConfigurationFile` cmdlet. The following command creates a session configuration file that uses the @@ -107,8 +108,7 @@ To create a session configuration for sessions in which users can use only Get cmdlets, type: ```powershell -New-PSSessionConfigurationFile -VisibleCmdlets Get-* --Path .\GetSessions.pssc +New-PSSessionConfigurationFile -VisibleCmdlets Get-* -Path .\GetSessions.pssc ``` In the preceding example, setting the VisibleCmdlets parameter to Get-* limits @@ -118,8 +118,7 @@ To create a session configuration for sessions that run under a privileged virtual account instead of the user's credentials, type: ```powershell -New-PSSessionConfigurationFile -RunAsVirtualAccount --Path .\VirtualAccount.pssc +New-PSSessionConfigurationFile -RunAsVirtualAccount -Path .\VirtualAccount.pssc ``` To create a session configuration for sessions in which the commands visible @@ -138,7 +137,7 @@ configuration or add you can add a file to the session configuration at a later time. To include a session configuration file when creating a session configuration, -use the Path parameter of the Register-PSSessionConfiguration cmdlet. +use the Path parameter of the `Register-PSSessionConfiguration` cmdlet. For example, the following command uses the NoLanguage.pssc file when it creates a NoLanguage session configuration. @@ -148,43 +147,43 @@ Register-PSSessionConfiguration -Name NoLanguage -Path .\NoLanguage.pssc ``` -When a new NoLanguage session starts, users will only have access to PowerShell commands. +When a new NoLanguage session starts, users will only have access to PowerShell +commands. To add a session configuration file to an existing session configuration, use the Set-PSSessionConfiguration cmdlet and the Path parameter. This affects any new sessions created with the specified session configuration. Note that the -Set-PSSessionConfiguration cmdlet changes the session itself and does not +`Set-PSSessionConfiguration` cmdlet changes the session itself and does not modify the session configuration file. For example, the following command adds the NoLanguage.pssc file to the LockedDown session configuration. ```powershell -Set-PSSessionConfiguration -Name LockedDown --Path .\NoLanguage.pssc +Set-PSSessionConfiguration -Name LockedDown -Path .\NoLanguage.pssc ``` When users use the LockedDown session configuration to create a session, they will be able to run cmdlets but they will not be able to create or use variables, assign values, or use other PowerShell language elements. -The following command uses the New-PSSession cmdlet to create a session on the -computer Srv01 that uses the LockedDown session configuration, saving an +The following command uses the `New-PSSession` cmdlet to create a session on +the computer Srv01 that uses the LockedDown session configuration, saving an object reference to the session in the $s variable. The ACL (access control list) of the session configuration determines who can use it to create a session. ```powershell -$s = New-PSSession -ComputerName Srv01 --ConfigurationName LockedDown +$s = New-PSSession -ComputerName Srv01 -ConfigurationName LockedDown ``` Because the NoLanguage constraints were added to the LockedDown session -configuration, users in LockedDown sessions will only be able to run PowerShell commands and cmdlets. For example, the following two commands use -the Invoke-Command cmdlet to run commands in the session referenced in the $s -variable. The first command, which runs the Get-UICulture cmdlet and does not +configuration, users in LockedDown sessions will only be able to run PowerShell +commands and cmdlets. For example, the following two commands use the +`Invoke-Command` cmdlet to run commands in the session referenced in the $s +variable. The first command, which runs the `Get-UICulture` cmdlet and does not use any variables, succeeds. The second command, which gets the value of the -$PSUICulture variable, fails. +`$PSUICulture` variable, fails. ``` Invoke-Command -Session $s {Get-UICulture} @@ -205,7 +204,8 @@ RunAsVirtualAccountGroups can be modified by editing the session configuration file used by the session configuration. To do this, begin by locating the active copy of the session configuration file. -When you use a session configuration file in a session configuration, PowerShell creates an active copy of the session configuration file and stores +When you use a session configuration file in a session configuration, +PowerShell creates an active copy of the session configuration file and stores it in the \$pshome\\SessionConfig directory on the local computer. The location of the active copy of a session configuration file is stored in @@ -249,12 +249,12 @@ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc ``` If the syntax and values in the configuration file are valid -Test-PSSessionConfigurationFile returns True. If the syntax and values are not -valid then the cmdlet returns False. +`Test-PSSessionConfigurationFile` returns True. If the syntax and values are +not valid then the cmdlet returns False. -You can use Test-PSSessionConfigurationFile to test any session configuration +You can use `Test-PSSessionConfigurationFile` to test any session configuration file, including files that the New-PSSessionConfiguration cmdlet creates. For -more information, see the help topic for the Test-PSSessionConfigurationFile +more information, see the help topic for the `Test-PSSessionConfigurationFile` cmdlet. ## Removing a Session Configuration File @@ -265,7 +265,7 @@ settings. This effectively cancels the settings used by the original configuration file. To replace a session configuration file, create a new session configuration -file that uses the default settings, then use the Set-PSSessionConfiguration +file that uses the default settings, then use the `Set-PSSessionConfiguration` cmdlet to replace the custom session configuration file with the new file. For example, the following commands create a Default session configuration @@ -287,8 +287,8 @@ objects that represent session configurations using session configuration files have additional properties that make it easy to discover and analyze the session configuration. (Note that the type name shown below includes a formatted view definition.) You can view the properties by running the -Get-PSSessionConfiguration cmdlet and piping the returned data to the -Get-Member cmdlet: +`Get-PSSessionConfiguration` cmdlet and piping the returned data to the +`Get-Member` cmdlet: ```powershell Get-PSSessionConfiguration NoLanguage | Get-Member @@ -351,20 +351,18 @@ use session configuration files, the command might not return all qualifying session configurations. ```powershell -Get-PSSessionConfiguration | -where {$_.ExecutionPolicy -eq "RemoteSigned"} +Get-PSSessionConfiguration | Where-Object {$_.ExecutionPolicy -eq "RemoteSigned"} ``` The following command gets session configurations in which the RunAsUser is the Exchange administrator. ```powershell - Get-PSSessionConfiguration | -where {$_.RunAsUser -eq "Exchange01\Admin01"} + Get-PSSessionConfiguration | Where-Object {$_.RunAsUser -eq "Exchange01\Admin01"} ``` To view information about the role definitions associated with a configuration -use the Get-PSSessionCapability cmdlet. This cmdlet enables you to determine +use the `Get-PSSessionCapability` cmdlet. This cmdlet enables you to determine the commands and environment available to specific users in specific endpoints. @@ -379,15 +377,29 @@ working with an empty session. ## See also -- [about_Session_Configurations](about_Session_Configurations.md) -- [New-PSRoleCapabilityFile](xref:Microsoft.PowerShell.Core.New-PSRoleCapabilityFile) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) -- [Get-PSSessionCapability](xref:Microsoft.PowerShell.Core.Get-PSSessionCapability) -- [Disable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Disable-PSSessionConfiguration) -- [Enable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Enable-PSSessionConfiguration) -- [Get-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Get-PSSessionConfiguration) -- [Register-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Register-PSSessionConfiguration) -- [Set-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Set-PSSessionConfiguration) -- [Unregister-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Unregister-PSSessionConfiguration) -- [New-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.New-PSSessionConfigurationFile) -- [Test-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.Test-PSSessionConfigurationFile) +- [about_Session_Configurations][01] +- [New-PSRoleCapabilityFile][02] +- [New-PSSession][03] +- [Get-PSSessionCapability][04] +- [Disable-PSSessionConfiguration][05] +- [Enable-PSSessionConfiguration][06] +- [Get-PSSessionConfiguration][07] +- [Register-PSSessionConfiguration][08] +- [Set-PSSessionConfiguration][09] +- [Unregister-PSSessionConfiguration][10] +- [New-PSSessionConfigurationFile][11] +- [Test-PSSessionConfigurationFile][12] + + +[01]: about_Session_Configurations.md +[02]: xref:Microsoft.PowerShell.Core.New-PSRoleCapabilityFile +[03]: xref:Microsoft.PowerShell.Core.New-PSSession +[04]: xref:Microsoft.PowerShell.Core.Get-PSSessionCapability +[05]: xref:Microsoft.PowerShell.Core.Disable-PSSessionConfiguration +[06]: xref:Microsoft.PowerShell.Core.Enable-PSSessionConfiguration +[07]: xref:Microsoft.PowerShell.Core.Get-PSSessionConfiguration +[08]: xref:Microsoft.PowerShell.Core.Register-PSSessionConfiguration +[09]: xref:Microsoft.PowerShell.Core.Set-PSSessionConfiguration +[10]: xref:Microsoft.PowerShell.Core.Unregister-PSSessionConfiguration +[11]: xref:Microsoft.PowerShell.Core.New-PSSessionConfigurationFile +[12]: xref:Microsoft.PowerShell.Core.Test-PSSessionConfigurationFile diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Session_Configurations.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Session_Configurations.md index ac8155be19df..2d5085edbb76 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Session_Configurations.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Session_Configurations.md @@ -9,6 +9,7 @@ title: about_Session_Configurations # about_Session_Configurations ## Short description + Describes session configurations, which determine the users who can connect to the computer remotely and the commands they can run. @@ -16,7 +17,8 @@ the computer remotely and the commands they can run. A session configuration, also known as an "endpoint" is a group of settings on the local computer that define the environment for the PowerShell sessions that -are created when remote or local users connect to PowerShell on the local computer. +are created when remote or local users connect to PowerShell on the local +computer. Administrators of the computer can use session configurations to protect the computer and to define custom environments for users who connect to the @@ -32,9 +34,8 @@ Beginning in PowerShell 3.0, you can use a session configuration file to define the elements of a session configuration. This feature makes it easy to customize sessions without writing code and to discover the properties of a session configuration. To create a session configuration file, use the -New-PSSessionConfiguration cmdlet. For more information about session -configuration files, see -[about_Session_Configuration_Files](about_Session_Configuration_Files.md). +`New-PSSessionConfiguration` cmdlet. For more information about session +configuration files, see [about_Session_Configuration_Files][01]. Session configurations are a feature of WSMAN-based PowerShell remoting. They are used only when you use the `New-PSSession`, `Invoke-Command`, or @@ -43,13 +44,13 @@ are used only when you use the `New-PSSession`, `Invoke-Command`, or To manage the session configurations on a Windows computer, start PowerShell with the **Run as administrator** option. -About Session Configurations +### About Session Configurations Every PowerShell session uses a session configuration. This includes -persistent sessions that you create by using the New-PSSession or -Enter-PSSession cmdlets, and the temporary sessions that PowerShell creates +persistent sessions that you create by using the `New-PSSession` or +`Enter-PSSession` cmdlets, and the temporary sessions that PowerShell creates when you use the ComputerName parameter of a cmdlet that uses -WS-Management-based remoting technology, such as Invoke-Command. +WS-Management-based remoting technology, such as `Invoke-Command`. Administrators can use session configurations to protect the resources of the computer and to create custom environments for users who connect to the @@ -70,7 +71,7 @@ default session configurations. But, you can change the security descriptors to allow everyone, no one, or only selected users to use the session configurations on your computer. -Built-in Session Configurations +### Built-in Session Configurations PowerShell 3.0 includes built-in session configurations named Microsoft.PowerShell and Microsoft.PowerShell.Workflow. On computers running @@ -79,8 +80,8 @@ Microsoft.PowerShell and Microsoft.PowerShell.Workflow. On computers running The Microsoft.PowerShell session configuration is used for sessions by default, that is, when a command to create a session does not include the -ConfigurationName parameter of the New-PSSession, Enter-PSSession, or -Invoke-Command cmdlet. +ConfigurationName parameter of the `New-PSSession`, `Enter-PSSession`, or +`Invoke-Command` cmdlet. The security descriptors for the default session configurations allow only members of the Administrators group on the local computer to use them. As @@ -88,13 +89,13 @@ such, only members of the Administrators group can connect to the computer remotely unless you change the default settings. You can change the default session configurations by using the -$PSSessionConfigurationName preference variable. For more information, see -about_Preference_Variables. +`$PSSessionConfigurationName` preference variable. For more information, see +[about_Preference_Variables][02]. -Viewing Session Configurations on the Local Computer +### Viewing Session Configurations on the Local Computer To get the session configurations on your local computer, use the -Get-PSSessionConfiguration cmdlet. +`Get-PSSessionConfiguration` cmdlet. For example, type: @@ -144,11 +145,12 @@ Container {Name=microsoft.powershell.wor... microsoft.powershell.workflow Container {Name=microsoft.powershell32} microsoft.powershell32 ``` -Viewing Session Configurations on a Remote Computer +### Viewing Session Configurations on a Remote Computer -To view the session configurations on a remote computer, use the Connect-WSMan -cmdlet to add a note for the remote computer to the WSMAN: drive on your local -computer, and then use the WSMAN: drive to view the session configurations. +To view the session configurations on a remote computer, use the +`Connect-WSMan` cmdlet to add a note for the remote computer to the +WSMAN: drive on your local computer, and then use the WSMAN: drive to view the +session configurations. For example, the following command adds a node for the Server01 remote computer to the WSMAN: drive on the local computer. @@ -184,7 +186,7 @@ Container {Name=microsoft.powershell.wor... microsoft.powershell.workflow Container {Name=microsoft.powershell32} microsoft.powershell32 ``` -Changing the Security Descriptor of a Session Configuration +### Changing the Security Descriptor of a Session Configuration In Windows Server 2012 and newer releases of Windows Server, the built-in session configurations are enabled for remote users by default. In other @@ -192,7 +194,7 @@ supported versions of Windows, you must change the security descriptors of the session configurations to allow remote access. To enable remote access to the session configurations on the computer, use the -Enable-PSRemoting cmdlet. This cmdlet creates two session configurations: +`Enable-PSRemoting` cmdlet. This cmdlet creates two session configurations: - with the name defined as: "PowerShell." + "current PowerShell version" - with name "PowerShell.6", untied to any specific PowerShell version. @@ -212,12 +214,11 @@ the security descriptor for the Microsoft.PowerShell default session configuration. ```powershell -Set-PSSessionConfiguration -name Microsoft.PowerShell ` - -ShowSecurityDescriptorUI +Set-PSSessionConfiguration -Name Microsoft.PowerShell -ShowSecurityDescriptorUI ``` To deny everyone permission to all the session configurations on the computer, -use the Disable-PSSessionConfiguration cmdlet. For example, the following +use the `Disable-PSSessionConfiguration` cmdlet. For example, the following command disables the default session configurations on the computer. ```powershell @@ -225,7 +226,7 @@ PS C:> Disable-PSSessionConfiguration -Name Microsoft.PowerShell ``` To prevent remote users from connecting to the computer, but allow local users -to connect, use the Disable-PSRemoting cmdlet. Disable-PSRemoting adds a +to connect, use the `Disable-PSRemoting` cmdlet. `Disable-PSRemoting` adds a "Network_Deny_All" entry to all session configurations on the computer. ```powershell @@ -233,16 +234,16 @@ PS C:> Disable-PSRemoting ``` To allow remote users to use all session configurations on the computer, use -the Enable-PSRemoting or Enable-PSSessionConfiguration cmdlet. For example, +the `Enable-PSRemoting` or `Enable-PSSessionConfiguration` cmdlet. For example, the following command enables remote access to the built-in session configurations. ```powershell -PS C:> Enable-PSSessionConfiguration -name Microsoft.Power* +PS C:> Enable-PSSessionConfiguration -Name Microsoft.Power* ``` To make other changes to the security descriptor of a session configuration, -use the Set-PSSessionConfiguration cmdlet. Use the SecurityDescriptorSDDL +use the `Set-PSSessionConfiguration` cmdlet. Use the SecurityDescriptorSDDL parameter to submit an SDDL string value. Use the ShowSecurityDescriptorUI parameter to display a user interface property sheet that helps you to create a new SDDL. @@ -250,16 +251,15 @@ a new SDDL. For example: ```powershell -Set-PSSessionConfiguration -Name Microsoft.PowerShell ` - -ShowSecurityDescriptorUI +Set-PSSessionConfiguration -Name Microsoft.PowerShell -ShowSecurityDescriptorUI ``` -Creating a New Session Configuration +### Creating a New Session Configuration To create a new session configuration on the local computer, use the -Register-PSSessionConfiguration cmdlet. To define the new session +`Register-PSSessionConfiguration` cmdlet. To define the new session configuration, you can use a C# assembly, a PowerShell script, and the -parameters of the Register-PSSessionConfiguration cmdlet. +parameters of the `Register-PSSessionConfiguration` cmdlet. For example, the following command creates a session configuration that is identical the Microsoft.PowerShell session configuration, except that it @@ -267,52 +267,55 @@ limits the data received from a remote command to 20 megabytes (MB). (The default is 50 MB). ```powershell -Register-PSSessionConfiguration -Name NewConfig ` - -MaximumReceivedDataSizePerCommandMB 20 +$registerPSSessionConfigurationSplat = @{ + Name = 'NewConfig' + MaximumReceivedDataSizePerCommandMB = 20 +} +Register-PSSessionConfiguration @registerPSSessionConfigurationSplat ``` When you create a session configuration, you can manage it by using the other session configuration cmdlets, and it appears in the WSMAN: drive. -For more information, see Register-PSSessionConfiguration. +For more information, see `Register-PSSessionConfiguration`. -Removing a Session Configuration +### Removing a Session Configuration To remove a session configuration from the local computer, use the -Unregister-PSSessionConfiguration cmdlet. For example, the following command +`Unregister-PSSessionConfiguration` cmdlet. For example, the following command removes the NewConfig session configuration from the computer. ```powershell -PS C:> Unregister-PSSessionConfiguration -Name NewConfig +Unregister-PSSessionConfiguration -Name NewConfig ``` -For more information, see Unregister-PSSessionConfiguration. +For more information, see `Unregister-PSSessionConfiguration`. -Restoring a Session Configuration +### Restoring a Session Configuration To restore a default session configuration that was deleted (unregistered) -accidentally, use the Enable-PSRemoting cmdlet. +accidentally, use the `Enable-PSRemoting` cmdlet. -The Enable-PSRemoting cmdlet recreates all default sessions configurations +The `Enable-PSRemoting` cmdlet recreates all default sessions configurations that do not exist on the computer. It does not overwrite or change the property values of existing session configurations. To restore the original property values of a default session configuration, -use the Unregister-PSSessionConfiguration to delete the session configuration -and then use the Enable-PSRemoting cmdlet to recreate it. +use the `Unregister-PSSessionConfiguration` to delete the session configuration +and then use the `Enable-PSRemoting` cmdlet to recreate it. -Selecting a Session Configuration +### Selecting a Session Configuration To select a particular session configuration for a session, use the -ConfigurationName parameter of New-PSSession, Enter-PSSession, or -Invoke-Command. +ConfigurationName parameter of `New-PSSession`, `Enter-PSSession`, or +`Invoke-Command`. -For example, this command uses the New-PSSession cmdlet to start a PSSession +For example, this command uses the `New-PSSession` cmdlet to start a PSSession on the Server01 computer. The command uses the ConfigurationName parameter to select the WithProfile configuration on the Server01 computer. ```powershell -PS C:> New-PSSession -ComputerName Server01 -ConfigurationName WithProfile +New-PSSession -ComputerName Server01 -ConfigurationName WithProfile ``` This command will succeed only if the current user has permission to use the @@ -322,7 +325,7 @@ has the required permissions. You can also use the $PSSessionConfigurationName preference variable to change the default session configuration on the computer. For more information about the $PSSessionConfigurationName preference variable, see -about_Preference_Variables. +[about_Preference_Variables][02]. ## KEYWORDS @@ -331,10 +334,10 @@ about_SessionConfigurations ## See also -- [about_Preference_Variables](about_Preference_Variables.md) +- [about_Preference_Variables][02] - [about_PSSessions](about_PSSessions.md) - [about_Remote](about_Remote.md) -- [about_Session_Configuration_Files](about_Session_Configuration_Files.md) +- [about_Session_Configuration_Files][01] - [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) - [Disable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Disable-PSSessionConfiguration) - [Enable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Enable-PSSessionConfiguration) @@ -344,3 +347,7 @@ about_SessionConfigurations - [Unregister-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Unregister-PSSessionConfiguration) - [New-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.New-PSSessionConfigurationFile) - [Test-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.Test-PSSessionConfigurationFile) + + +[01]: about_Session_Configuration_Files.md +[02]: about_Preference_Variables.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md index bed764fca901..9ae349c8d7dd 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md @@ -9,6 +9,7 @@ title: about_Simplified_Syntax # about_Simplified_Syntax ## Short description + Describes easier, more natural-language ways of scripting filters for collections of objects. @@ -60,7 +61,7 @@ commands: ```powershell dir Cert:\LocalMachine\Root | Where FriendlyName -EQ 'Verisign' -dir Cert:\ -Recurse | ForEach GetKeyAlgorithm +dir Cert:\ -Recurse | foreach GetKeyAlgorithm ``` While both syntaxes work, the simplified syntax returns results without @@ -96,5 +97,5 @@ Get-ChildItem /home -Directory | foreach GetFiles .* - [about_Comparison_Operators](about_Comparison_Operators.md) - [about_Foreach](about_Foreach.md) -- [Foreach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) +- [ForEach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) - [Where-Object](xref:Microsoft.PowerShell.Core.Where-Object) diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Splatting.md index 87af55abbb10..96b52c518161 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -72,7 +72,8 @@ table of parameter-name and parameter-value pairs and stores it in the variable in a command with splatting. The At symbol (`@HashArguments`) replaces the dollar sign (`$HashArguments`) in the command. -To provide a value for the **WhatIf** switch parameter, use `$True` or `$False`. +To provide a value for the **WhatIf** switch parameter, use `$True` or +`$False`. ```powershell $HashArguments = @{ diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md index 9f2aafddb756..c349f9e4dfb7 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Split.md @@ -9,6 +9,7 @@ title: about_Split # about_Split ## Short description + Explains how to use the Split operator to split one or more strings into substrings. diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md index 620d023a59e7..3b2ae06239d7 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md @@ -9,6 +9,7 @@ title: about_Switch # about_Switch ## Short description + Explains how to use a switch to handle multiple `if` statements. ## Long description @@ -191,10 +192,10 @@ examples evaluates 4 and then 2. ```powershell switch (4, 2) { - 1 {"It is one." } - 2 {"It is two." } - 3 {"It is three." } - 4 {"It is four." } + 1 {"It is one."} + 2 {"It is two."} + 3 {"It is three."} + 4 {"It is four."} 3 {"Three again."} } ``` @@ -212,9 +213,9 @@ statement in the condition of value 4. switch (4, 2) { 1 {"It is one."; Break} - 2 {"It is two." ; Break } - 3 {"It is three." ; Break } - 4 {"It is four." ; Break } + 2 {"It is two." ; Break} + 3 {"It is three." ; Break} + 4 {"It is four." ; Break} 3 {"Three again."} } ``` @@ -369,7 +370,7 @@ the beginning of the year 2022. ```powershell switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { { $_.Year -eq 2021 } { - $days = ((Get-Date 1/1/2022) - $_).days + $days = ((Get-Date 1/1/2022) - $_).Days "There are $days days until 2022." } { $_.Year -eq 2022 } { 'Welcome to 2022!' } diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md index 4fc3fda8b143..7f59796b8d22 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md @@ -10,6 +10,7 @@ title: About_tab_expansion # about_Tab_Expansion ## Short description + PowerShell provides completions on input to provide hints, enable discovery, and speed up input entry. Command names, parameter names, argument values and file paths can all be completed by pressing the Tab key. @@ -43,6 +44,8 @@ part of the name and press the Tab key. PowerShell automatically expands the name to the first match that it finds. Pressing the Tab key repeatedly cycles through all the available choices. +## Cmdlet name completion + The tab expansion of cmdlet names is slightly different. To use tab expansion on a cmdlet name, type the entire first part of the name (the verb) and the hyphen that follows it. You can fill in more of the name for a partial match. @@ -109,8 +112,9 @@ keys to select the value you want. Tab completion can also work to complete parameter arguments. You can use the Tab key to cycle through a list of possible values that are valid -for some parameter. For more information, see -[about_Functions_Argument_Completion][04]. +for some parameter. + +For more information, see [about_Functions_Argument_Completion][04]. ## Enumerated value completion diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Telemetry.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Telemetry.md index 1af478481d9a..675544a506da 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Telemetry.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Telemetry.md @@ -58,7 +58,8 @@ session for all host applications. To opt-out of this telemetry, set the environment variable `$env:POWERSHELL_TELEMETRY_OPTOUT` to `true`, `yes`, or `1`. For this environment variable to have effect, it must be set before starting the -PowerShell process. For more information, see [about_Environment_Variables][01]. +PowerShell process. For more information, see +[about_Environment_Variables][01]. The `$env:POWERSHELL_DISTRIBUTION_CHANNEL` environment variable is set by the installer packages to record the method and source of installation for @@ -72,6 +73,6 @@ For more information about Microsoft's statement on privacy, see [Microsoft Privacy Statement][03] -[01]: about_environment_variables.md#powershell-environment-variables +[01]: about_Environment_Variables.md#powershell-environment-variables [02]: /azure/azure-monitor/app/ip-collection?tabs=net [03]: https://privacy.microsoft.com/privacystatement diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Thread_Jobs.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Thread_Jobs.md index df40198e8de2..706f5f9ec977 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Thread_Jobs.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Thread_Jobs.md @@ -21,9 +21,9 @@ PowerShell concurrently runs commands and scripts through jobs. There are three jobs types provided by PowerShell to support concurrency. - `RemoteJob` - Commands and scripts run in a remote session. For information, - see [about_Remote_Jobs](about_Remote_Jobs.md). + see [about_Remote_Jobs][01]. - `BackgroundJob` - Commands and scripts run in a separate process on the local - machine. For more information, see [about_Jobs](about_Jobs.md). + machine. For more information, see [about_Jobs][02]. - `PSTaskJob` or `ThreadJob` - Commands and scripts run in a separate thread within the same process on the local machine. @@ -46,10 +46,9 @@ faster and use fewer resources than the other job types. There are two ways work around this situation: 1. Use `Invoke-Command` to create jobs that run in disconnected sessions. For - more information, see [about_Remote_Jobs](about_Remote_Jobs.md). + more information, see [about_Remote_Jobs][01]. 1. Use `Start-Process` to create a new process rather than a job. For more - information, see - [Start-Process](xref:Microsoft.PowerShell.Management.Start-Process). + information, see [Start-Process][03]. ## How to start and manage thread-based jobs @@ -59,7 +58,7 @@ There are two ways to start thread-based jobs: - `ForEach-Object -Parallel -AsJob` - the parallel feature was added in PowerShell 7.0 -Use the same **Job** cmdlets described in [about_Jobs](about_Jobs.md) to manage +Use the same **Job** cmdlets described in [about_Jobs][02] to manage thread-based jobs. ### Using `Start-ThreadJob` @@ -184,7 +183,7 @@ system logs. Since the script involves reading a number of logs, it makes sense to do the operations in parallel. ```powershell -$logNames.count +$logNames.Count 10 Measure-Command { @@ -277,14 +276,29 @@ NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName ## See also -- [about_Job_Details](about_Job_Details.md) -- [about_Remote_Jobs](about_Remote_Jobs.md) -- [about_Thread_Jobs](about_Thread_Jobs.md) -- [about_PSSessions](about_PSSessions.md) -- [about_Remote](about_Remote.md) -- [Get-Job](xref:Microsoft.PowerShell.Core.Get-Job) -- [Receive-Job](xref:Microsoft.PowerShell.Core.Receive-Job) -- [Remove-Job](xref:Microsoft.PowerShell.Core.Remove-Job) -- [Start-Job](xref:Microsoft.PowerShell.Core.Start-Job) -- [Stop-Job](xref:Microsoft.PowerShell.Core.Stop-Job) -- [Wait-Job](xref:Microsoft.PowerShell.Core.Wait-Job) +- [about_Job_Details][04] +- [about_Remote_Jobs][01] +- [about_Thread_Jobs][05] +- [about_PSSessions][06] +- [about_Remote][07] +- [Get-Job][08] +- [Receive-Job][09] +- [Remove-Job][10] +- [Start-Job][11] +- [Stop-Job][12] +- [Wait-Job][13] + + +[01]: about_Remote_Jobs.md +[02]: about_Jobs.md +[03]: xref:Microsoft.PowerShell.Management.Start-Process +[04]: about_Job_Details.md +[05]: about_Thread_Jobs.md +[06]: about_PSSessions.md +[07]: about_Remote.md +[08]: xref:Microsoft.PowerShell.Core.Get-Job +[09]: xref:Microsoft.PowerShell.Core.Receive-Job +[10]: xref:Microsoft.PowerShell.Core.Remove-Job +[11]: xref:Microsoft.PowerShell.Core.Start-Job +[12]: xref:Microsoft.PowerShell.Core.Stop-Job +[13]: xref:Microsoft.PowerShell.Core.Wait-Job diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Trap.md index 5c915ce4a4c4..9b62de3a3ddd 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Trap.md @@ -366,8 +366,8 @@ however, the `trap` statement is outside the function. PowerShell doesn't go back into the function after the `trap` statement runs. > [!CAUTION] -> When multiple traps are defined for the same error condition, the first `trap` -> defined lexically (highest in the script block) is used. +> When multiple traps are defined for the same error condition, the first +> `trap` defined lexically (highest in the script block) is used. In the following example, only the `trap` with `whoops 1` runs. diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md index 56949987f384..1a5810b8e477 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md @@ -255,7 +255,7 @@ try { "An error occurred that could not be resolved." } finally { $wc.Dispose() - if (Test-Path $tempPath) { Remove-item $tempFile } + if (Test-Path $tempPath) { Remove-Item $tempFile } } ``` diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Type_Conversion.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Type_Conversion.md index e02b04d4b02c..907666ed4843 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Type_Conversion.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Type_Conversion.md @@ -528,8 +528,8 @@ For more information, see [about_Comparison_Operators][05]. [05]: about_Comparison_Operators.md [06]: about_Functions_Advanced.md [07]: about_Numeric_Literals.md -[08]: about_parameter_binding.md -[09]: about_preference_variables.md#ofs +[08]: about_Parameter_Binding.md +[09]: about_Preference_Variables.md#ofs [10]: about_Types.ps1xml.md [11]: https://stackoverflow.com/questions/76241804/how-does-powershell-split-consecutive-strings-not-a-single-letter [12]: xref:Microsoft.PowerShell.Utility.Update-TypeData diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index 5db581fef06c..312b4ee67288 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -9,6 +9,7 @@ title: about_Types.ps1xml # about_Types.ps1xml ## Short description + Explains how to use `Types.ps1xml` files to extend the types of objects that are used in PowerShell. @@ -24,8 +25,7 @@ data to a PowerShell session. This topic describes `Types.ps1xml` files. For more information about using the `Update-TypeData` cmdlet to add dynamic extended type data to the current -session see -[Update-TypeData](xref:Microsoft.PowerShell.Utility.Update-TypeData). +session see [Update-TypeData][01]. ## About extended type data @@ -46,8 +46,8 @@ Sunday, January 29, 2012 9:43:57 AM ``` You won't find the **DateTime** property in the description of the -[System.DateTime](/dotnet/api/system.datetime) structure, because PowerShell -adds the property and it is visible only in PowerShell. +[System.DateTime][02] structure, because PowerShell adds the property and it is +visible only in PowerShell. PowerShell internally defines a default set of extended types. This type information is loaded in every PowerShell session at startup. The **DateTime** @@ -141,12 +141,12 @@ As a result, you can use either the **Count** property or the **Length** property of arrays in PowerShell. For example: ```powershell -(1, 2, 3, 4).count +(1, 2, 3, 4).Count 4 ``` ```powershell -(1, 2, 3, 4).length +(1, 2, 3, 4).Length 4 ``` @@ -176,9 +176,7 @@ the `Update-TypeData` command to your PowerShell profile. The `Types.ps1xml` files add properties and methods to all the instances of the objects of the specified .NET type in the affected PowerShell session. However, if you need to add properties or methods only to one instance of an object, use -the `Add-Member` cmdlet. - -For more information, see [Add-Member](xref:Microsoft.PowerShell.Utility.Add-Member). +the `Add-Member` cmdlet. For more information, see [Add-Member][03]. ## Example: Adding an Age member to FileInfo objects @@ -210,13 +208,11 @@ Save the follow XML code to the file `$PSHOME\MyTypes.ps1xml`. Run `Update-TypeData` to add the new `Types.ps1xml` file to the current session. The command uses the **PrependData** parameter to place the new file -in a precedence order higher than the original definitions. - -For more information about `Update-TypeData`, see -[Update-TypeData](xref:Microsoft.PowerShell.Utility.Update-TypeData). +in a precedence order higher than the original definitions. For more +information about `Update-TypeData`, see [Update-TypeData][01]. ```powershell -Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml +Update-TypeData -PrependPath $PSHOME\MyTypes.ps1xml ``` To test the change, run a `Get-ChildItem` command to get the PowerShell.exe @@ -234,9 +230,8 @@ Get-ChildItem $PSHOME\pwsh.exe | Select-Object Age ## The XML in Types.ps1xml files -The full schema definition can be found in -[Types.xsd](https://github.com/PowerShell/PowerShell/blob/master/src/Schemas/Types.xsd) -in the PowerShell source code repository on GitHub. +The full schema definition can be found in [Types.xsd][04] in the PowerShell +source code repository on GitHub. The `` tag encloses all of the types that are defined in the file. There should be only one `` tag. @@ -517,7 +512,7 @@ objects. ``` For more information, see the -[Windows PowerShell Software Development Kit (SDK)](/powershell/scripting/developer/windows-powershell). +[Windows PowerShell Software Development Kit (SDK)][05]. ## Update-TypeData @@ -545,15 +540,27 @@ are added by running the `Update-TypeData` cmdlet cannot use method syntax. ## Signing a Types.ps1xml file To protect users of your `Types.ps1xml` file, you can sign the file using a -digital signature. For more information, see -[about_Signing](about_Signing.md). +digital signature. For more information, see [about_Signing][06]. ## See also -- [about_Signing](about_Signing.md) -- [Copy-Item](xref:Microsoft.PowerShell.Management.Copy-Item) -- [Copy-ItemProperty](xref:Microsoft.PowerShell.Management.Copy-ItemProperty) -- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) -- [Get-TypeData](xref:Microsoft.PowerShell.Utility.Get-TypeData) -- [Remove-TypeData](xref:Microsoft.PowerShell.Utility.Remove-TypeData) -- [Update-TypeData](xref:Microsoft.PowerShell.Utility.Update-TypeData) +- [about_Signing][06] +- [Copy-Item][07] +- [Copy-ItemProperty][08] +- [Get-Member][09] +- [Get-TypeData][10] +- [Remove-TypeData][11] +- [Update-TypeData][01] + + +[01]: xref:Microsoft.PowerShell.Utility.Update-TypeData +[02]: /dotnet/api/system.datetime +[03]: xref:Microsoft.PowerShell.Utility.Add-Member +[04]: https://github.com/PowerShell/PowerShell/blob/master/src/Schemas/Types.xsd +[05]: /powershell/scripting/developer/windows-powershell +[06]: about_Signing.md +[07]: xref:Microsoft.PowerShell.Management.Copy-Item +[08]: xref:Microsoft.PowerShell.Management.Copy-ItemProperty +[09]: xref:Microsoft.PowerShell.Utility.Get-Member +[10]: xref:Microsoft.PowerShell.Utility.Get-TypeData +[11]: xref:Microsoft.PowerShell.Utility.Remove-TypeData diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index e4e6814efc60..5d6693f3fce0 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -9,6 +9,7 @@ title: about_Updatable_Help # about_Updatable_Help ## Short description + Describes the updatable help system in PowerShell. ## Long description @@ -382,8 +383,7 @@ to specify a different filesystem location, but they can't exclude the > only the policy setting under **Computer Configuration** is effective. The > policy setting under **User Configuration** is ignored. -For more information, see -[about_Group_Policy_Settings][04]. +For more information, see [about_Group_Policy_Settings][04]. ## How to update help for non-standard modules diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Update_Notifications.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Update_Notifications.md index 1b5f8ebca166..43aabd106737 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Update_Notifications.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Update_Notifications.md @@ -52,9 +52,9 @@ information about setting environment variables, see PowerShell uses the following endpoints for determining the latest version available for each channel: -- `LTS`: -- `Stable`: -- `Preview`: +- `LTS`: [https://aka.ms/pwsh-buildinfo-lts][02] +- `Stable`: [https://aka.ms/pwsh-buildinfo-stable][03] +- `Preview`: [https://aka.ms/pwsh-buildinfo-preview][04] The update notification doesn't provide any way to automatically update PowerShell. In the future, there may be more instructions or capabilities to @@ -63,3 +63,6 @@ mechanism you used to install PowerShell to update it. [01]: ../about/about_Environment_Variables.md +[02]: https://aka.ms/pwsh-buildinfo-lts +[03]: https://aka.ms/pwsh-buildinfo-stable +[04]: https://aka.ms/pwsh-buildinfo-preview diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Variable_Provider.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Variable_Provider.md index 8d56f3cb6ee2..65b493d5c996 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Variable_Provider.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Variable_Provider.md @@ -9,6 +9,7 @@ title: about_Variable_Provider # about_Variable_Provider ## Provider name + Variable ## Drives @@ -38,31 +39,31 @@ objects. The variables have no child items. The **Variable** provider supports the following cmdlets, which are covered in this article. -- [Get-Location](xref:Microsoft.PowerShell.Management.Get-Location) -- [Set-Location](xref:Microsoft.PowerShell.Management.Set-Location) -- [Get-Item](xref:Microsoft.PowerShell.Management.Get-Item) -- [New-Item](xref:Microsoft.PowerShell.Management.New-Item) -- [Remove-Item](xref:Microsoft.PowerShell.Management.Remove-Item) -- [Clear-Item](xref:Microsoft.PowerShell.Management.Clear-Item) +- [Get-Location][01] +- [Set-Location][02] +- [Get-Item][03] +- [New-Item][04] +- [Remove-Item][05] +- [Clear-Item][06] PowerShell also includes a set of cmdlets designed especially to view and to change variables. When you use **Variable** cmdlets, you do not need to specify the `Variable:` drive in the name. This article does not cover working with **Variable** cmdlets. -- [Get-Variable](xref:Microsoft.PowerShell.Utility.Get-Variable) -- [New-Variable](xref:Microsoft.PowerShell.Utility.New-Variable) -- [Set-Variable](xref:Microsoft.PowerShell.Utility.Set-Variable) -- [Remove-Variable](xref:Microsoft.PowerShell.Utility.Remove-Variable) -- [Clear-Variable](xref:Microsoft.PowerShell.Utility.Clear-Variable) +- [Get-Variable][07] +- [New-Variable][08] +- [Set-Variable][09] +- [Remove-Variable][10] +- [Clear-Variable][11] > [!NOTE] > You can also use the PowerShell expression parser to create, view, and change -> the values of variables without using the cmdlets. When working with variables -> directly, use a dollar sign (`$`) to identify the name as a variable and the -> assignment operator (`=`)to establish and change its value. For example, -> `$p = Get-Process` creates the `p` variable and stores the results of a -> `Get-Process` command in it. +> the values of variables without using the cmdlets. When working with +> variables directly, use a dollar sign (`$`) to identify the name as a +> variable and the assignment operator (`=`)to establish and change its value. +> For example, `$p = Get-Process` creates the `p` variable and stores the +> results of a `Get-Process` command in it. ## Types exposed by this provider @@ -108,9 +109,8 @@ drive. To reference a variable from another location, use the drive name > [!NOTE] > PowerShell uses aliases to allow you a familiar way to work with provider > paths. Commands such as `dir` and `ls` are now aliases for -> [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem), -> `cd` is an alias for [Set-Location](xref:Microsoft.PowerShell.Management.Set-Location). and `pwd` is -> an alias for [Get-Location](xref:Microsoft.PowerShell.Management.Get-Location). +> [Get-ChildItem][12], `cd` is an alias for [Set-Location][13]. and `pwd` is +> an alias for [Get-Location][14]. ## Displaying the value of variables @@ -125,9 +125,9 @@ Get-ChildItem -Path Variable: ### Get a variable using its provider path -This command retrieves a variables value using its provider path prefixed by the -dollar sign (`$`). This has the same effect as prefixing the variables name with -the dollar sign (`$`). +This command retrieves a variables value using its provider path prefixed by +the dollar sign (`$`). This has the same effect as prefixing the variables name +with the dollar sign (`$`). ```powershell $variable:home @@ -144,14 +144,13 @@ Get-ChildItem -Path Variable:max* ### Get the value of the ? variable -This command uses the `-LiteralPath` parameter of -[Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) to get +This command uses the `-LiteralPath` parameter of [Get-ChildItem][12] to get the value of the `?` variable from within the `Variable:` drive. The `?` is a wildcard in paths, but `Get-ChildItem` does not attempt to resolve any wildcards in the values of the `-LiteralPath` parameter. ```powershell -Get-ChildItem -Literalpath ? +Get-ChildItem -LiteralPath ? ``` ### Get ReadOnly and Constant variables @@ -161,8 +160,8 @@ This command gets the variables that have the values of `ReadOnly` or ```powershell Get-ChildItem -Path Variable: | Where-Object { - $_.options -Match "Constant" ` - -or $_.options -Match "ReadOnly" + $_.options -match "Constant" ` + -or $_.options -match "ReadOnly" } | Format-List -Property name, value, options ``` @@ -266,8 +265,8 @@ Beginning in Windows PowerShell 3.0, you can get customized help topics for provider cmdlets that explain how those cmdlets behave in a file system drive. To get the help topics that are customized for the file system drive, run a -[Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) command in a file system drive or use the `-Path` -parameter of [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) to specify a file system drive. +[Get-Help][15] command in a file system drive or use the `-Path` parameter of +[Get-Help][15] to specify a file system drive. ```powershell Get-Help Get-ChildItem @@ -279,6 +278,26 @@ Get-Help Get-ChildItem -Path variable: ## See also -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_Providers](about_Providers.md) -- [about_Variables](about_Variables.md) +- [about_Automatic_Variables][16] +- [about_Providers][17] +- [about_Variables][18] + + +[01]: xref:Microsoft.PowerShell.Management.Get-Location +[02]: xref:Microsoft.PowerShell.Management.Set-Location +[03]: xref:Microsoft.PowerShell.Management.Get-Item +[04]: xref:Microsoft.PowerShell.Management.New-Item +[05]: xref:Microsoft.PowerShell.Management.Remove-Item +[06]: xref:Microsoft.PowerShell.Management.Clear-Item +[07]: xref:Microsoft.PowerShell.Utility.Get-Variable +[08]: xref:Microsoft.PowerShell.Utility.New-Variable +[09]: xref:Microsoft.PowerShell.Utility.Set-Variable +[10]: xref:Microsoft.PowerShell.Utility.Remove-Variable +[11]: xref:Microsoft.PowerShell.Utility.Clear-Variable +[12]: xref:Microsoft.PowerShell.Management.Get-ChildItem +[13]: xref:Microsoft.PowerShell.Management.Set-Location +[14]: xref:Microsoft.PowerShell.Management.Get-Location +[15]: xref:Microsoft.PowerShell.Core.Get-Help +[16]: about_Automatic_Variables.md +[17]: about_Providers.md +[18]: about_Variables.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Variables.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Variables.md index d773c2f08341..f30b7b9e0d5b 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Variables.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Variables.md @@ -515,7 +515,7 @@ Get-Help [01]: #variable-names-that-include-special-characters [02]: about_Alias_Provider.md -[03]: about_assignment_operators.md#assigning-multiple-variables +[03]: about_Assignment_Operators.md#assigning-multiple-variables [04]: about_Automatic_Variables.md [05]: about_Environment_Provider.md [06]: about_Environment_Variables.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_While.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_While.md index 0541aa4abae8..e0ed0cde582d 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_While.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_While.md @@ -9,6 +9,7 @@ title: about_While # about_While ## Short description + Describes a language statement that you can use to run a command block based on the results of a conditional test. @@ -28,11 +29,11 @@ The following shows the While statement syntax: while (){} ``` -When you run a `while` statement, PowerShell evaluates the `` section -of the statement before entering the `` section. The condition -portion of the statement resolves to either true or false. As long as the -condition remains true, PowerShell reruns the `` section. For -more information about how booleans are evaluated, see +When you run a `while` statement, PowerShell evaluates the `` +section of the statement before entering the `` section. The +condition portion of the statement resolves to either true or false. As long as +the condition remains true, PowerShell reruns the `` section. +For more information about how booleans are evaluated, see [about_Booleans](about_Booleans.md). The `` section of the statement contains one or more commands @@ -40,8 +41,8 @@ that are run each time the loop is entered or repeated. The `` can contain any valid PowerShell statements, including the `break` and `continue` keywords. -For example, the following `while` statement displays the numbers 1 through 3 if -the `$val` variable has not been created or if the `$val` variable has been +For example, the following `while` statement displays the numbers 1 through 3 +if the `$val` variable has not been created or if the `$val` variable has been created and initialized to 0. ```powershell @@ -64,8 +65,8 @@ can enter it in the following way: while($val -ne 3){$val++; Write-Host $val} ``` -Notice that the semicolon separates the first command that adds 1 to `$val` from -the second command that writes the value of `$val` to the console. +Notice that the semicolon separates the first command that adds 1 to `$val` +from the second command that writes the value of `$val` to the console. ## See also diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Wildcards.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Wildcards.md index d57428da8b26..2f80299225d9 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Wildcards.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Wildcards.md @@ -82,7 +82,7 @@ following command gets services in which the **ServiceType** property value includes **Interactive**. ```powershell -Get-Service | Where-Object {$_.ServiceType -Like "*Interactive*"} +Get-Service | Where-Object {$_.ServiceType -like "*Interactive*"} ``` In the following example, the `If` statement includes a condition that uses @@ -106,7 +106,7 @@ foreach ($point in $p) { - [about_Script_Blocks][04] -[01]: ./about_Regular_Expressions.md +[01]: about_Regular_Expressions.md [02]: about_If.md [03]: about_Language_Keywords.md [04]: about_Script_Blocks.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_Compatibility.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_Compatibility.md index ff824114a853..a29f18177081 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_Compatibility.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_Compatibility.md @@ -163,6 +163,6 @@ from the session or close the session. [01]: about_Modules.md -[02]: about_powershell_config.md +[02]: about_Powershell_Config.md [03]: https://aka.ms/PSModuleCompat [04]: xref:Microsoft.PowerShell.Core.Import-Module diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_PSSession_Details.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_PSSession_Details.md index 6f5aba4c8eac..0f41f3e86832 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_PSSession_Details.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_PSSession_Details.md @@ -6,6 +6,7 @@ online version: https://learn.microsoft.com/powershell/module/microsoft.powershe schema: 2.0.0 title: about_PSSession_Details --- + # about_PSSession_Details ## Short description diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_PSSessions.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_PSSessions.md index d43c6b37487a..2b39320a3565 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_PSSessions.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_PSSessions.md @@ -6,6 +6,7 @@ online version: https://learn.microsoft.com/powershell/module/microsoft.powershe schema: 2.0.0 title: about_PSSessions --- + # about_PSSessions ## Short description diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 416fb65fae34..fa85628eeb86 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -85,7 +85,7 @@ enclosed in a subexpression. For example: ``` ```Output -PS version: 7.5.0-preview.4 +PS version: 7.5.0 ``` To separate a variable name from subsequent characters in the string, enclose diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Return.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Return.md index 3a0001b9ba99..be757b4ec720 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Return.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Return.md @@ -125,7 +125,7 @@ by the function and assigned to the `$a` variable. If you would like to display a message within your function, beginning in PowerShell 5.0, you can use the `Information` stream. The code below corrects the above example using the `Write-Information` cmdlet with a -`InformationAction` of **Continue**. +**InformationAction** set to `Continue`. ```powershell function calculation { @@ -135,13 +135,15 @@ function calculation { $value += 73 return $value } - -$a = calculation 14 ``` -``` +Now the information message to display in the host and not assigned to the +variable. + +```powershell +PS> $a = calculation 14 Please wait. Working on calculation... -C:\PS> $a +PS> $a 87 ``` diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Scripts.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Scripts.md index 761bac88703e..c626ce066773 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Scripts.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Scripts.md @@ -121,8 +121,11 @@ The following command runs the `Get-ServiceLog.ps1` script on the remote computers named Server01 and Server02. ```powershell -Invoke-Command -ComputerName Server01, Server02 -FilePath ` - C:\Scripts\Get-ServiceLog.ps1 +$invokeCommandSplat = @{ + ComputerName = 'Server01', 'Server02' + FilePath = 'C:\Scripts\Get-ServiceLog.ps1' +} +Invoke-Command @invokeCommandSplat ``` ## Get help for scripts diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md index 887a0d7a009a..ab30485f99d2 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md @@ -6,6 +6,7 @@ online version: https://learn.microsoft.com/powershell/module/microsoft.powershe schema: 2.0.0 title: about_Session_Configuration_Files --- + # about_Session_Configuration_Files ## Short description diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Session_Configurations.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Session_Configurations.md index a388e18dfa3b..b6cc3a52afe8 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Session_Configurations.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Session_Configurations.md @@ -267,7 +267,11 @@ limits the data received from a remote command to 20 megabytes (MB). (The default is 50 MB). ```powershell -Register-PSSessionConfiguration -Name NewConfig -MaximumReceivedDataSizePerCommandMB 20 +$registerPSSessionConfigurationSplat = @{ + Name = 'NewConfig' + MaximumReceivedDataSizePerCommandMB = 20 +} +Register-PSSessionConfiguration @registerPSSessionConfigurationSplat ``` When you create a session configuration, you can manage it by using the other @@ -282,7 +286,7 @@ To remove a session configuration from the local computer, use the removes the NewConfig session configuration from the computer. ```powershell -PS C:> Unregister-PSSessionConfiguration -Name NewConfig +Unregister-PSSessionConfiguration -Name NewConfig ``` For more information, see `Unregister-PSSessionConfiguration`. @@ -311,7 +315,7 @@ on the Server01 computer. The command uses the ConfigurationName parameter to select the WithProfile configuration on the Server01 computer. ```powershell -PS C:> New-PSSession -ComputerName Server01 -ConfigurationName WithProfile +New-PSSession -ComputerName Server01 -ConfigurationName WithProfile ``` This command will succeed only if the current user has permission to use the diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md index 22be256e8bc8..aec74c149b51 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md @@ -121,7 +121,7 @@ Tab completion can also work to complete parameter arguments. You can use the Tab key to cycle through a list of possible values that are valid for some parameter. -For more information, see[about_Functions_Argument_Completion][04]. +For more information, see [about_Functions_Argument_Completion][04]. ## Enumerated value completion diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Telemetry.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Telemetry.md index 97b5e389c4cb..d389cdebbb37 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Telemetry.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Telemetry.md @@ -3,7 +3,6 @@ description: Describes the telemetry collected in PowerShell and how to opt-out. Locale: en-US ms.date: 09/24/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_telemetry?view=powershell-7.5&WT.mc_id=ps-gethelp -ms.custom: 7.5-preview.5 schema: 2.0.0 title: about_Telemetry --- diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/About.md b/reference/7.6/Microsoft.PowerShell.Core/About/About.md index 2cc0b52b0a63..31c17830509a 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/About.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/About.md @@ -223,7 +223,8 @@ Describes the attribute that makes a function work like a compiled cmdlet. ### [about_Functions_OutputTypeAttribute](about_Functions_OutputTypeAttribute.md) -Describes an attribute that reports the type of object that the function returns. +Describes an attribute that reports the type of object that the function +returns. ### [about_Functions](about_Functions.md) diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_PSSession_Details.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_PSSession_Details.md index 4d483712de32..397c180b517f 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_PSSession_Details.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_PSSession_Details.md @@ -15,52 +15,50 @@ role they play in remote commands. ## Long description -A session is an environment in which PowerShell runs. A session is -created for you whenever you start PowerShell. You can create -additional sessions, called "PowerShell sessions" or "PSSessions" -on your computer or another computer. +A session is an environment in which PowerShell runs. A session is created for +you whenever you start PowerShell. You can create additional sessions, called +"PowerShell sessions" or "PSSessions" on your computer or another computer. -Unlike the sessions that PowerShell creates for you, you control -and manage the PSSessions that you create. +Unlike the sessions that PowerShell creates for you, you control and manage the +PSSessions that you create. PSSessions play an important role in remote computing. When you create a -PSSession that is connected to a remote computer, PowerShell -establishes a persistent connection to the remote computer to support the -PSSession. You can use the PSSession to run a series of commands, -functions, and scripts that share data. +PSSession that is connected to a remote computer, PowerShell establishes a +persistent connection to the remote computer to support the PSSession. You can +use the PSSession to run a series of commands, functions, and scripts that +share data. -This topic provides detailed information about sessions and PSSessions -in PowerShell. For basic information about the tasks that you -can perform with sessions, see [about_PSSessions](about_PSSessions.md). +This topic provides detailed information about sessions and PSSessions in +PowerShell. For basic information about the tasks that you can perform with +sessions, see [about_PSSessions][01]. ## About Sessions -Technically, a session is an execution environment in which -PowerShell runs. Each session includes an instance of the -System.Management.Automation engine and a host program in which -PowerShell runs. The host can be the familiar PowerShell console -or another program that runs commands, such as Cmd.exe, or a program built -to host PowerShell, such as Windows PowerShell Integrated Scripting -Environment (ISE). From a Windows perspective, a session is a Windows +Technically, a session is an execution environment in which PowerShell runs. +Each session includes an instance of the System.Management.Automation engine +and a host program in which PowerShell runs. The host can be the familiar +PowerShell console or another program that runs commands, such as Cmd.exe, or +a program built to host PowerShell, such as Windows PowerShell Integrated +Scripting Environment (ISE). From a Windows perspective, a session is a Windows process on the target computer. -Each session is configured independently. It includes its own properties, -its own execution policy, and its own profiles. The environment that exists -when the session is created persists for its lifetime even if you change -the environment on the computer. All sessions are created in a global -scope, even sessions that you create in a script. +Each session is configured independently. It includes its own properties, its +own execution policy, and its own profiles. The environment that exists when +the session is created persists for its lifetime even if you change the +environment on the computer. All sessions are created in a global scope, even +sessions that you create in a script. -You can run only one command (or command pipeline) in a session at one -time. A second command run synchronously (one at a time) waits up to four -minutes for the first command to be completed. A second command run -asynchronously (concurrently) fails. +You can run only one command (or command pipeline) in a session at one time. +A second command run synchronously (one at a time) waits up to four minutes for +the first command to be completed. A second command run asynchronously +(concurrently) fails. ## About PSSessions -A session is created each time that you start PowerShell. And, -PowerShell creates temporary sessions to run individual commands. -However, you can also create sessions (called "PowerShell sessions" -or "PSSessions") that you control and manage. +A session is created each time that you start PowerShell. And, PowerShell +creates temporary sessions to run individual commands. However, you can also +create sessions (called "PowerShell sessions" or "PSSessions") that you control +and manage. PSSessions are critical to remote commands. If you use the **ComputerName** parameter of the `Invoke-Command` or `Enter-PSSession` cmdlets, PowerShell @@ -74,15 +72,15 @@ create remain open and available for use until you delete them or until you close the session in which they were created. When you create a PSSession on a remote computer, the system creates a -PowerShell process on the remote computer and establishes a connection -from the local computer to the process on the remote computer. When you -create a PSSession on the local computer, both the new process and the -connections are created on the local computer. +PowerShell process on the remote computer and establishes a connection from the +local computer to the process on the remote computer. When you create a +PSSession on the local computer, both the new process and the connections are +created on the local computer. ## When Do I Need a PSSession? -The `Invoke-Command` and `Enter-PSSession` cmdlets have both **ComputerName** and -**Session** parameters. You can use either to run a remote command. +The `Invoke-Command` and `Enter-PSSession` cmdlets have both **ComputerName** +and **Session** parameters. You can use either to run a remote command. Use the **ComputerName** parameter to run a single command or a series of unrelated commands on one or many computers. @@ -91,12 +89,11 @@ To run commands that share data, you need a persistent connection to the remote computer. In that case, create a PSSession, and then use the **Session** parameter to run commands in the PSSession. -Many other cmdlets that get data from remote computers, such as -`Get-Process`, `Get-Service`, `Get-EventLog`, and `Get-WmiObject` have only a -**ComputerName** parameter. They use technologies other than PowerShell -remoting to gather data remotely. These cmdlets do not have a **Session** -parameter, but you can use the `Invoke-Command` cmdlet to run these commands -in a PSSession. +Many other cmdlets that get data from remote computers, such as `Get-Process`, +`Get-Service`, `Get-EventLog`, and `Get-WmiObject` have only a **ComputerName** +parameter. They use technologies other than PowerShell remoting to gather data +remotely. These cmdlets do not have a **Session** parameter, but you can use +the `Invoke-Command` cmdlet to run these commands in a PSSession. ## How Do I Create a PSSession? @@ -106,114 +103,101 @@ To create a PSSession, use the `New-PSSession` cmdlet. You can use ## Can I Create a PSSession on Any Computer? To create a PSSession that is connected to a remote computer, the computer -must be configured for remoting in PowerShell. The current user -must be a member of the Administrators group on the remote computer, or -the current user must be able to supply the credentials of a member of -the Administrators group. For more information, -see [about_Remote_Requirements](about_Remote_Requirements.md). +must be configured for remoting in PowerShell. The current user must be a +member of the Administrators group on the remote computer, or the current user +must be able to supply the credentials of a member of the Administrators group. +For more information, see [about_Remote_Requirements][02]. ## Can I See My PSSessions in Other Sessions? -Beginning in Windows PowerShell 3.0, the **ComputerName** -parameter of the `Get-PSSession` cmdlet gets PSSessions -that you created on the specified remote computers. +Beginning in Windows PowerShell 3.0, the **ComputerName** parameter of the +`Get-PSSession` cmdlet gets PSSessions that you created on the specified +remote computers. -Active PSSessions are maintained on the remote computer -(the "server-side" of a connection) and you can get them -from any session on any computer. +Active PSSessions are maintained on the remote computer (the "server-side" of +a connection) and you can get them from any session on any computer. -For example, if you create a PSSession from the Server01 -computer to the Server02 computer, and then switch to the -Server03 computer, you can use a command like the following -one to get the session. +For example, if you create a PSSession from the Server01 computer to the +Server02 computer, and then switch to the Server03 computer, you can use a +command like the following one to get the session. ```powershell Get-PSSession -ComputerName Server02 ``` -Even if you disconnect from the session, the session is -maintained on the remote computer until you delete it or it -times out. +Even if you disconnect from the session, the session is maintained on the +remote computer until you delete it or it times out. -In Windows PowerShell 2.0, you can get only the PSSessions -that you have created in the current session. You cannot get -PSSessions that you created in other sessions. - -For more information, see [Get-PSSession](xref:Microsoft.PowerShell.Core.Get-PSSession). +In Windows PowerShell 2.0, you can get only the PSSessions that you have +created in the current session. You cannot get PSSessions that you created in +other sessions. For more information, see [Get-PSSession][03]. ## Can I See the PSSessions That Others Have Created on My Computer? -You can get and manage only the PSSessions that others have created -only if you can supply the credentials of the user who created the -PSSession or the session configuration that the PSSession uses -includes RunAs credentials. Otherwise, you can get, connect to, use, -and manage only the PSSessions that you created. +You can get and manage only the PSSessions that others have created only if you +can supply the credentials of the user who created the PSSession or the session +configuration that the PSSession uses includes RunAs credentials. Otherwise, +you can get, connect to, use, and manage only the PSSessions that you created. ## Can I Connect to a PSSession From a Different Computer? Beginning in Windows PowerShell 3.0, PSSessions on Windows computers are independent of the sessions in which they were created. Active PSSessions -are maintained on the computer at the remote or "server-side" of -a connection. +are maintained on the computer at the remote or "server-side" of a connection. On a Windows computer, you can use the `Disconnect-PSSession` cmdlet to disconnect from a PSSession. The PSSession is disconnected from the local session, but is maintained on the remote computer. -Commands continue to run in the disconnected PSSession. You -can close PowerShell and shut down the originating computer -without interrupting the PSSession. - -Then, even hours later, you can use the `Get-PSSession` cmdlet to -get the PSSession and the `Connect-PSSession` cmdlet to connect to the -PSSession from a new session on a different Windows computer. +Commands continue to run in the disconnected PSSession. You can close +PowerShell and shut down the originating computer without interrupting the +PSSession. -For more information, see [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md). +Then, even hours later, you can use the `Get-PSSession` cmdlet to get the +PSSession and the `Connect-PSSession` cmdlet to connect to the PSSession from +a new session on a different Windows computer. For more information, see +[about_Remote_Disconnected_Sessions][04]. ## What Happens to My PSSession if My Computer Stops? -Disconnected PSSessions are independent of the sessions -in which they were created. If you disconnect a PSSession -and then close the originating computer, the PSSession is -maintained on the remote computer. - -In addition, PowerShell attempts to recover active -PSSessions that are disconnected unintentionally, such as -by a computer reboot, a temporary power outage or network -disruption. PowerShell attempts to maintain or recover -the PSSession to an Opened state, if the originating session -is still available, or to a disconnected state if it is not. +Disconnected PSSessions are independent of the sessions in which they were +created. If you disconnect a PSSession and then close the originating computer, +the PSSession is maintained on the remote computer. -An "active" PSSession is one that is running commands. If -a PSSession is connected (not disconnected) and commands are -running in the PSSession when the connected session closes, -PowerShell attempts to maintain the PSSession on the -remote computer. However, if no commands are running in the -PSSession, PowerShell closes the PSSession when the -connected session closes. +In addition, PowerShell attempts to recover active PSSessions that are +disconnected unintentionally, such as by a computer reboot, a temporary power +outage or network disruption. PowerShell attempts to maintain or recover the +PSSession to an Opened state, if the originating session is still available, or +to a disconnected state if it is not. -For more information, see [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md). +An "active" PSSession is one that is running commands. If a PSSession is +connected (not disconnected) and commands are running in the PSSession when the +connected session closes, PowerShell attempts to maintain the PSSession on the +remote computer. However, if no commands are running in the PSSession, +PowerShell closes the PSSession when the connected session closes. For more +information, see [about_Remote_Disconnected_Sessions][04]. ## Can I Run a Background Job in a PSSession? -Yes. A background job is a command that runs asynchronously in the -background without interacting with the current session. When you submit -a command to start a job, the command returns a job object, but the job -continues to run in the background until it is complete. +Yes. A background job is a command that runs asynchronously in the background +without interacting with the current session. When you submit a command to +start a job, the command returns a job object, but the job continues to run in +the background until it is complete. To start a background job on a local computer, use the `Start-Job` command. You can run the background job in a temporary connection (by using the -**ComputerName** parameter) or in a PSSession (by using the **Session** parameter). +**ComputerName** parameter) or in a PSSession (by using the **Session** +parameter). To start a background job on a remote computer, use the `Invoke-Command` -cmdlet with its **AsJob** parameter, or use the `Invoke-Command` cmdlet to run a -`Start-Job` command on a remote computer. When using the **AsJob** parameter, +cmdlet with its **AsJob** parameter, or use the `Invoke-Command` cmdlet to run +a `Start-Job` command on a remote computer. When using the **AsJob** parameter, you can use the **ComputerName** or **Session** parameters. When using `Invoke-Command` to run a `Start-Job` command, you must run the command in a PSSession. If you use the **ComputerName** parameter, PowerShell ends the connection when the job object returns, and the job is interrupted. -For more information, see [about_Jobs](about_Jobs.md). +For more information, see [about_Jobs][05]. ## Can I Run an Interactive Session? @@ -223,15 +207,15 @@ type run on the remote computer, just as if you typed them directly on the remote computer. You can run an interactive session in a temporary session (by using the -**ComputerName** parameter) or in a PSSession (by using the **Session** parameter). -If you use a PSSession, the PSSession retains the data from previous -commands, and the PSSession retains any data generated during the +**ComputerName** parameter) or in a PSSession (by using the **Session** +parameter). If you use a PSSession, the PSSession retains the data from +previous commands, and the PSSession retains any data generated during the interactive session for use in later commands. When you end the interactive session, the PSSession remains open and available for use. -For more information, see [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) and [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession). +For more information, see [Enter-PSSession][06] and [Exit-PSSession][07]. ## Must I Delete the PSSessions? @@ -244,9 +228,9 @@ in use. To delete PSSessions, use the `Remove-PSSession` cmdlet. It deletes the PSSessions and releases all of the resources that they were using. -You can also use the **IdleTimeOut** parameter of `New-PSSessionOption` to close -an idle PSSession after an interval that you specify. For more information, -see [New-PSSessionOption](xref:Microsoft.PowerShell.Core.New-PSSessionOption). +You can also use the **IdleTimeOut** parameter of `New-PSSessionOption` to +close an idle PSSession after an interval that you specify. For more +information, see [New-PSSessionOption][08]. If you save a PSSession object in a variable and then delete the PSSession or let it time out, the variable still contains the PSSession object, but @@ -255,19 +239,33 @@ the PSSession is not active and cannot be used or repaired. ## Are All Sessions and PSSessions Alike? No. Developers can create custom sessions that include only selected -providers and cmdlets. If a command works in one session but not in -another, it might be because the session is restricted. +providers and cmdlets. If a command works in one session but not in another, +it might be because the session is restricted. ## See also -- [about_Jobs](about_Jobs.md) -- [about_PSSessions](about_PSSessions.md) -- [about_Remote](about_Remote.md) -- [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md) -- [about_Remote_Requirements](about_Remote_Requirements.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) -- [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) -- [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession) -- [Get-PSSession](xref:Microsoft.PowerShell.Core.Get-PSSession) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) -- [Remove-PSSession](xref:Microsoft.PowerShell.Core.Remove-PSSession) +- [about_Jobs][05] +- [about_PSSessions][01] +- [about_Remote][09] +- [about_Remote_Disconnected_Sessions][04] +- [about_Remote_Requirements][02] +- [Invoke-Command][10] +- [Enter-PSSession][06] +- [Exit-PSSession][07] +- [Get-PSSession][03] +- [New-PSSession][11] +- [Remove-PSSession][12] + + +[01]: about_PSSessions.md +[02]: about_Remote_Requirements.md +[03]: xref:Microsoft.PowerShell.Core.Get-PSSession +[04]: about_Remote_Disconnected_Sessions.md +[05]: about_Jobs.md +[06]: xref:Microsoft.PowerShell.Core.Enter-PSSession +[07]: xref:Microsoft.PowerShell.Core.Exit-PSSession +[08]: xref:Microsoft.PowerShell.Core.New-PSSessionOption +[09]: about_Remote.md +[10]: xref:Microsoft.PowerShell.Core.Invoke-Command +[11]: xref:Microsoft.PowerShell.Core.New-PSSession +[12]: xref:Microsoft.PowerShell.Core.Remove-PSSession diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_PSSessions.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_PSSessions.md index aa3a4e423f4c..f1b61be979ef 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_PSSessions.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_PSSessions.md @@ -10,23 +10,23 @@ title: about_PSSessions ## Short description -Describes PowerShell sessions (PSSessions) and explains how to -establish a persistent connection to a remote computer. +Describes PowerShell sessions (PSSessions) and explains how to establish a +persistent connection to a remote computer. ## Long description To run PowerShell commands on a remote computer, you can use the -**ComputerName** parameter of a cmdlet, or you can create a PowerShell -session (PSSession) and run commands in the PSSession. +**ComputerName** parameter of a cmdlet, or you can create a PowerShell session +(PSSession) and run commands in the PSSession. -When you create a PSSession, PowerShell establishes a persistent -connection to the remote computer. Use a PSSession to run a series of related -commands on a remote computer. Commands that run in the same PSSession can -share data, such as the values of variables, aliases, and functions. +When you create a PSSession, PowerShell establishes a persistent connection to +the remote computer. Use a PSSession to run a series of related commands on a +remote computer. Commands that run in the same PSSession can share data, such +as the values of variables, aliases, and functions. You can also create a PSSession on the local computer and run commands in it. -A local PSSession uses the PowerShell remoting infrastructure to -create and maintain the PSSession. +A local PSSession uses the PowerShell remoting infrastructure to create and +maintain the PSSession. Beginning in Windows PowerShell 3.0, PSSessions on Windows are independent of the sessions in which they are created. Active PSSessions are maintained @@ -36,36 +36,33 @@ on a remote Windows computer and reconnect to it at a later time from the same computer or from a different Windows computer. This topic explains how to create, use, get, and delete PSSessions. For more -advanced information, see -[about_PSSession_Details](about_PSSession_Details.md). +advanced information, see [about_PSSession_Details][01]. -Note: PSSessions use the PowerShell remoting infrastructure. To use -PSSessions, the local and remote computers must be configured for remoting. -For more information, see -[about_Remote_Requirements](about_Remote_Requirements.md). +Note: PSSessions use the PowerShell remoting infrastructure. To use PSSessions, +the local and remote computers must be configured for remoting. For more +information, see [about_Remote_Requirements][02]. In Windows Vista and later versions of Windows, to create a PSSession on a -local computer, you must start PowerShell with the "Run as -administrator" option. +local computer, you must start PowerShell with the "Run as administrator" +option. ## What Is a Session? A session is an environment in which PowerShell runs. -Each time you start PowerShell, a session is created for you, and you -can run commands in the session. You can also add items to your session, such -as modules and snap-ins, and you can create items, such as variables, -functions, and aliases. These items exist only in the session and are deleted -when the session ends. - -You can also create user-managed sessions, known as " PowerShell -sessions" or "PSSessions," on the local computer or on a remote computer. Like -the default session, you can run commands in a PSSession and add and create -items. However, unlike the session that starts automatically, you can control -the PSSessions that you create. You can get, create, configure, and remove -them, disconnect and reconnect to them, and run multiple commands in the same -PSSession. The PSSession remains available until you delete it or it times -out. +Each time you start PowerShell, a session is created for you, and you can run +commands in the session. You can also add items to your session, such as +modules and snap-ins, and you can create items, such as variables, functions, +and aliases. These items exist only in the session and are deleted when the +session ends. + +You can also create user-managed sessions, known as "PowerShell sessions" or +"PSSessions," on the local computer or on a remote computer. Like the default +session, you can run commands in a PSSession and add and create items. +However, unlike the session that starts automatically, you can control the +PSSessions that you create. You can get, create, configure, and remove them, +disconnect and reconnect to them, and run multiple commands in the same +PSSession. The PSSession remains available until you delete it or it times out. Typically, you create a PSSession to run a series of related commands on a remote computer. When you create a PSSession on a remote computer, PowerShell @@ -74,15 +71,14 @@ session. If you use the **ComputerName** parameter of the `Invoke-Command` or `Enter-PSSession` cmdlet to run a remote command or to start an interactive -session, PowerShell creates a temporary session on the remote computer -and closes the session as soon as the command is complete or as soon as the +session, PowerShell creates a temporary session on the remote computer and +closes the session as soon as the command is complete or as soon as the interactive session ends. You cannot control these temporary sessions, and you -cannot use them for more than a single command or a single interactive -session. +cannot use them for more than a single command or a single interactive session. -In PowerShell, the "current session" is the session that you are -working in. The "current session" can refer to any session, including a -temporary session or a PSSession. +In PowerShell, the "current session" is the session that you are working in. +The "current session" can refer to any session, including a temporary session +or a PSSession. ## Why Use a PSSession? @@ -96,10 +92,9 @@ You can run remote commands without creating a PSSession. Use the or a series of unrelated commands on one or many computers. When you use the **ComputerName** parameter of `Invoke-Command` or -`Enter-PSSession`, PowerShell establishes a temporary connection to -the remote computer and then closes the connection as soon as the command is -complete. Any data elements that you create are lost when the connection is -closed. +`Enter-PSSession`, PowerShell establishes a temporary connection to the remote +computer and then closes the connection as soon as the command is complete. +Any data elements that you create are lost when the connection is closed. Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` and `Get-WmiObject`, use different remoting technologies to gather data. None @@ -108,8 +103,8 @@ create a persistent connection like a PSSession. ## How to Create a PSSession To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession -on a remote computer, use the **ComputerName** parameter of the -`New-PSSession` cmdlet. +on a remote computer, use the **ComputerName** parameter of the `New-PSSession` +cmdlet. For example, the following command creates a new PSSession on the Server01 computer. @@ -151,7 +146,8 @@ To get the PSSessions that were created in your current session, use the `Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` returns the same type of object that `New-PSSession` returns. -The following command gets all the PSSessions that were created in the current session. +The following command gets all the PSSessions that were created in the current +session. ```powershell Get-PSSession @@ -239,7 +235,7 @@ until it times out. You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` cmdlet to set an expiration time for an idle PSSession. For more information, -see [New-PSSessionOption](xref:Microsoft.PowerShell.Core.New-PSSessionOption). +see [New-PSSessionOption][03]. ## The PSSession Cmdlets @@ -263,22 +259,37 @@ Get-Help *-PSSession > Disconnected sessions are only supported on Windows. The `Connect-PSSession`, > `Disconnect-PSSession`, and `Receive-PSSession` cmdlets are only available > on Windows. For more information about disconnected sessions, see -> [about_Remote_Disconnected_Session](about_Remote_Disconnected_Sessions.md) +> [about_Remote_Disconnected_Session][04]. ## For More Information -For more information about PSSessions, see [about_PSSession_Details](about_PSSession_Details.md). +For more information about PSSessions, see [about_PSSession_Details][01]. ## See also -- [about_Remote](about_Remote.md) -- [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md) -- [about_Remote_Requirements](about_Remote_Requirements.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) -- [Connect-PSSession](xref:Microsoft.PowerShell.Core.Connect-PSSession) -- [Disconnect-PSSession](xref:Microsoft.PowerShell.Core.Disconnect-PSSession) -- [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) -- [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession) -- [Get-PSSession](xref:Microsoft.PowerShell.Core.Get-PSSession) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) -- [Remove-PSSession](xref:Microsoft.PowerShell.Core.Remove-PSSession) +- [about_Remote][05] +- [about_Remote_Disconnected_Sessions][04] +- [about_Remote_Requirements][02] +- [Invoke-Command][06] +- [Connect-PSSession][07] +- [Disconnect-PSSession][08] +- [Enter-PSSession][09] +- [Exit-PSSession][10] +- [Get-PSSession][11] +- [New-PSSession][12] +- [Remove-PSSession][13] + + +[01]: about_PSSession_Details.md +[02]: about_Remote_Requirements.md +[03]: xref:Microsoft.PowerShell.Core.New-PSSessionOption +[04]: about_Remote_Disconnected_Sessions.md +[05]: about_Remote.md +[06]: xref:Microsoft.PowerShell.Core.Invoke-Command +[07]: xref:Microsoft.PowerShell.Core.Connect-PSSession +[08]: xref:Microsoft.PowerShell.Core.Disconnect-PSSession +[09]: xref:Microsoft.PowerShell.Core.Enter-PSSession +[10]: xref:Microsoft.PowerShell.Core.Exit-PSSession +[11]: xref:Microsoft.PowerShell.Core.Get-PSSession +[12]: xref:Microsoft.PowerShell.Core.New-PSSession +[13]: xref:Microsoft.PowerShell.Core.Remove-PSSession diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Pwsh.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Pwsh.md index d032459caae9..bda4a1358657 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Pwsh.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Pwsh.md @@ -108,11 +108,11 @@ Running `pwsh -File -` without redirected standard input starts a regular session. This is the same as not specifying the `File` parameter at all. When reading from standard input, the input statements are executed one statement at a time as though they were typed at the PowerShell command prompt. If a -statement doesn't parse correctly, the statement isn't executed. The process exit code is -determined by status of the last (executed) command within the input. With -normal termination, the exit code is always `0`. When the script file -terminates with an `exit` command, the process exit code is set to the numeric -argument used with the `exit` command. +statement doesn't parse correctly, the statement isn't executed. The process +exit code is determined by status of the last (executed) command within the +input. With normal termination, the exit code is always `0`. When the script +file terminates with an `exit` command, the process exit code is set to the +numeric argument used with the `exit` command. Similar to `-Command`, when a script-terminating error occurs, the exit code is set to `1`. However, unlike with `-Command`, when the execution is interrupted @@ -152,7 +152,7 @@ script block curly braces are often not required in the first place when running from `cmd.exe`. To execute an inline script block defined inside a string, the [call operator][03] `&` can be used: -``` +```powershell pwsh -Command "& {Get-WinEvent -LogName security}" ``` @@ -289,7 +289,7 @@ For example: $command = 'dir "c:\program files" ' $bytes = [System.Text.Encoding]::Unicode.GetBytes($command) $encodedCommand = [Convert]::ToBase64String($bytes) -pwsh -encodedcommand $encodedCommand +pwsh -EncodedCommand $encodedCommand ``` ### -ExecutionPolicy | -ex | -ep @@ -326,7 +326,8 @@ To set up `pwsh` as the login shell on UNIX-like operating systems: - Verify that the full absolute path to `pwsh` is listed under `/etc/shells` - This path is usually something like `/usr/bin/pwsh` on Linux or `/usr/local/bin/pwsh` on macOS - - With some installation methods, this entry will be added automatically at installation time + - With some installation methods, this entry will be added automatically at + installation time - If `pwsh` isn't present in `/etc/shells`, use an editor to append the path to `pwsh` on the last line. This requires elevated privileges to edit. - Use the [chsh][04] utility to set your current @@ -408,7 +409,8 @@ non-Windows platforms results in an error. ### -Version | -v -Displays the version of this PowerShell executable. Additional parameters are ignored. +Displays the version of this PowerShell executable. Additional parameters are +ignored. ### -WindowStyle | -w @@ -431,6 +433,6 @@ prepend the command parameters with a hyphen (`-`), not a forward slash (`/`). [01]: /powershell/module/microsoft.powershell.core/about/about_powershell_exe?view=powershell-5.1&preserve-view=true [02]: about_Automatic_Variables.md#lastexitcode -[03]: about_operators.md#special-operators +[03]: about_Operators.md#special-operators [04]: https://linux.die.net/man/1/chsh [05]: about_Parsing.md#passing-arguments-that-contain-quote-characters diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index bf9572b6baca..36faaaa15ab0 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -465,7 +465,7 @@ For more information about this behavior, see the [about_Parsing][03] article. [01]: #including-quote-characters-in-a-string [02]: about_Parsing.md#argument-mode [03]: about_Parsing.md#passing-arguments-that-contain-quote-characters -[04]: about_preference_variables.md#ofs +[04]: about_Preference_Variables.md#ofs [05]: about_Special_Characters.md [06]: https://en.wikipedia.org/wiki/Quotation_marks_in_English#Smart_quotes [07]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Redirection.md index bbe4595bed34..d17b70751713 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -15,8 +15,8 @@ Explains how to redirect output from PowerShell to text files. ## Long description By default, PowerShell sends output to the PowerShell host. Usually this is the -console application. However, you can redirect the output to a text file and you -can redirect error output to the regular output stream. +console application. However, you can redirect the output to a text file and +you can redirect error output to the regular output stream. You can use the following methods to redirect output: @@ -79,8 +79,7 @@ PowerShell 7.4 changed the behavior of the redirection operators when used to redirect the **stdout** stream of a native command. The redirection operators now preserve the byte-stream data when redirecting output from a native command. PowerShell doesn't interpret the redirected data or add any additional -formatting. For more information, see -[Example #7](#example-7-redirecting-binary-data-from-a-native-command). +formatting. For more information, see [Example #7][17]. ## Examples @@ -134,8 +133,7 @@ file called `script.log`. ### Example 5: Suppress all Write-Host and Information stream data This example suppresses all information stream data. To read more about -**Information** stream cmdlets, see -[Write-Host][11] and +**Information** stream cmdlets, see [Write-Host][11] and [Write-Information][12] ```powershell @@ -154,27 +152,27 @@ particular stream. The script in this example shows how the value of ```powershell $ErrorActionPreference = 'Continue' $ErrorActionPreference > log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'SilentlyContinue' $ErrorActionPreference >> log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'Stop' $ErrorActionPreference >> log.txt Try { - get-item /not-here 2>&1 >> log.txt + Get-Item /not-here 2>&1 >> log.txt } catch { "`tError caught!" >> log.txt } $ErrorActionPreference = 'Ignore' $ErrorActionPreference >> log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'Inquire' $ErrorActionPreference >> log.txt -get-item /not-here 2>&1 >> log.txt +Get-Item /not-here 2>&1 >> log.txt $ErrorActionPreference = 'Continue' ``` @@ -387,7 +385,7 @@ used. For more information, see the `-gt` operator in [03]: about_Operators.md [04]: about_Output_Streams.md [05]: about_Path_Syntax.md -[06]: about_preference_variables.md#psdefaultparametervalues +[06]: about_Preference_Variables.md#psdefaultparametervalues [07]: xref:Microsoft.PowerShell.Utility.Out-File [08]: xref:Microsoft.PowerShell.Utility.Tee-Object [09]: xref:Microsoft.PowerShell.Utility.Write-Debug @@ -398,3 +396,4 @@ used. For more information, see the `-gt` operator in [14]: xref:Microsoft.PowerShell.Utility.Write-Progress [15]: xref:Microsoft.PowerShell.Utility.Write-Verbose [16]: xref:Microsoft.PowerShell.Utility.Write-Warning +[17]: #example-7-redirecting-binary-data-from-a-native-command diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Ref.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Ref.md index 957eae04a4f1..274435b4fb40 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Ref.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Ref.md @@ -42,7 +42,7 @@ Test -data $var $var ``` -```output +```Output 10 ``` @@ -64,7 +64,7 @@ Test -data $var $var ``` -```output +```Output Name Value ---- ----- Test New Text @@ -101,21 +101,21 @@ Test -data ([ref]$var) $var ``` -```output +```Output 3 ``` ## Passing references to .NET methods -Some .NET methods may require you to pass a variable as a reference. When -the method's definition uses the keywords `in`, `out`, or `ref` on a -parameter, it expects a reference. +Some .NET methods may require you to pass a variable as a reference. When the +method's definition uses the keywords `in`, `out`, or `ref` on a parameter, it +expects a reference. ```powershell [int] | Get-Member -Static -Name TryParse ``` -```output +```Output Name MemberType Definition ---- ---------- ---------- TryParse Method static bool TryParse(string s, [ref] int result) @@ -149,7 +149,7 @@ $iRef = [ref]0 "`$i = $i;`$iRef = $($iRef.Value)" ``` -```output +```Output $i = 0;$iRef = 1 ``` @@ -188,8 +188,8 @@ specifying the `[System.Management.Automation.PSReference]` type directly. Even though `[ref]` is a type accelerator for `[System.Management.Automation.PSReference]`, they behave differently. -- When you use `[ref]` to cast a variable, PowerShell creates a reference object - that contains a reference to the original instance of the variable. +- When you use `[ref]` to cast a variable, PowerShell creates a reference + object that contains a reference to the original instance of the variable. - When you use `[System.Management.Automation.PSReference]` to cast a variable, PowerShell creates a reference object that contains a copy of the variable, rather than a reference to the original instance. @@ -243,7 +243,7 @@ Value [01]: about_Environment_Variables.md [02]: about_Functions.md -[03]: about_scopes.md +[03]: about_Scopes.md [04]: about_Script_Blocks.md [05]: about_Type_Accelerators.md [06]: about_Variables.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Registry_Provider.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Registry_Provider.md index 25ea5ec117f9..794578d83018 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Registry_Provider.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Registry_Provider.md @@ -28,8 +28,8 @@ Provides access to the registry keys, entries, and values in PowerShell. > This information only applies to PowerShell running on Windows. -The PowerShell **Registry** provider lets you get, add, change, -clear, and delete registry keys, entries, and values in PowerShell. +The PowerShell **Registry** provider lets you get, add, change, clear, and +delete registry keys, entries, and values in PowerShell. The **Registry** drives are a hierarchical namespace containing the registry keys and subkeys on your computer. Registry entries and values aren't diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 4670b1c61850..902a953ca034 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -354,7 +354,7 @@ The provided regular expression extracts the username and domain from the message and stores them under the keys:**N** for name and **D** for domain. ```powershell -$log = (Get-WinEvent -LogName Security -MaxEvents 1).message +$log = (Get-WinEvent -LogName Security -MaxEvents 1).Message $r = '(?s).*Account Name:\s*(?.*).*Account Domain:\s*(?[A-Z,0-9]*)' $log -match $r ``` diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md index 4af8462b95dc..12486f20a67e 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md @@ -37,7 +37,8 @@ The following cmdlets support the Disconnected Sessions feature: - `Connect-PSSession`: Connects to a disconnected PSSession. - `Disconnect-PSSession`: Disconnects a PSSession. -- `Get-PSSession`: Gets PSSessions on the local computer or on remote computers. +- `Get-PSSession`: Gets PSSessions on the local computer or on remote + computers. - `Receive-PSSession`: Gets the results of commands that ran in disconnected sessions. - `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and @@ -56,7 +57,7 @@ created ends. When you disconnect a PSSession, the PSSession remains active and is maintained on the remote computer. The session state changes from **Running** to -**Disconnected**. You can reconnect to a disconnected PSSession from +**Disconnected**. You can reconnect to a disconnected PSSession from: - The current session on the same computer - A different session on the same computer diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md index b0e0757a0c9b..8c661b4ce244 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md @@ -83,10 +83,11 @@ all of the operations occur on the remote computer, not the local computer. use the Session parameter to run the interactive session in a PowerShell session (PSSession). - The following command starts an interactive session on the Server01 computer. + The following command starts an interactive session on the Server01 + computer. ```powershell - C:\PS> Enter-PSSession -computername Server01 + C:\PS> Enter-PSSession -ComputerName Server01 ``` The command prompt changes to show that you are now connected to the @@ -104,8 +105,8 @@ all of the operations occur on the remote computer, not the local computer. This command saves the job object in the `$job` variable. ```powershell - Server01\C:> $job = Start-Job -scriptblock { - Get-Eventlog "Windows PowerShell" + Server01\C:> $job = Start-Job -ScriptBlock { + Get-EventLog "Windows PowerShell" } ``` @@ -123,7 +124,7 @@ all of the operations occur on the remote computer, not the local computer. SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 1 Job1 Complete True localhost Get-Eventlog "Windows... + 1 Job1 Complete True localhost Get-EventLog "Windows... ``` The `Get-Job` output shows that job is running on the "localhost" computer @@ -162,8 +163,8 @@ all of the operations occur on the remote computer, not the local computer. view the contents of the file. ```powershell - $s = New-PSSession -computername Server01 - Invoke-Command -session $s -scriptblock { + $s = New-PSSession -ComputerName Server01 + Invoke-Command -Session $s -ScriptBlock { Get-Content c:\logs\pslog.txt} ``` @@ -189,8 +190,8 @@ requirements for remoting. assign a display name to the job. ```powershell - Invoke-Command -computername Server01 -scriptblock { - Get-Eventlog system} -AsJob + Invoke-Command -Computername Server01 -ScriptBlock { + Get-EventLog system} -AsJob ``` The results of the command resemble the following sample output. @@ -198,7 +199,7 @@ requirements for remoting. ```Output SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 1 Job1 Running True Server01 Get-Eventlog system + 1 Job1 Running True Server01 Get-EventLog system ``` When the **AsJob** parameter is used, `Invoke-Command` returns the same type @@ -228,7 +229,7 @@ requirements for remoting. ```Output SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 1 Job1 Completed True Server01 Get-Eventlog system + 1 Job1 Completed True Server01 Get-EventLog system ``` 1. To get the results of the job, use the `Receive-Job` cmdlet. Because the job @@ -241,7 +242,7 @@ requirements for remoting. file. ```powershell - $results = Receive-Job -id 1 + $results = Receive-Job -Id 1 ``` ### Start a remote job that keeps the results on the remote computer @@ -270,7 +271,7 @@ commands remotely to manage a local job on the remote computer. in the `$s` variable. ```powershell - $s = New-PSSession -computername Server01 + $s = New-PSSession -ComputerName Server01 ``` The next command uses the `Invoke-Command` cmdlet to run a `Start-Job` @@ -278,8 +279,8 @@ commands remotely to manage a local job on the remote computer. command are enclosed in braces. ```powershell - Invoke-Command -session $s -scriptblock { - Start-Job -scriptblock {Get-Eventlog system}} + Invoke-Command -Session $s -ScriptBlock { + Start-Job -ScriptBlock {Get-EventLog system}} ``` The results resemble the following sample output. @@ -287,7 +288,7 @@ commands remotely to manage a local job on the remote computer. ```Output Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- - 2 Job2 Running True Localhost Get-Eventlog system + 2 Job2 Running True Localhost Get-EventLog system ``` When you run a `Start-Job` command remotely, `Invoke-Command` returns the @@ -309,7 +310,7 @@ commands remotely to manage a local job on the remote computer. computer. ```powershell - Invoke-Command -session $s -scriptblock {Get-Job} + Invoke-Command -Session $s -ScriptBlock {Get-Job} ``` The command returns a job object. The **State** property of the job object @@ -318,7 +319,7 @@ commands remotely to manage a local job on the remote computer. ```Output SessionId Name State HasMoreData Location Command --------- ---- ----- ----------- -------- ------- - 2 Job2 Completed True LocalHost Get-Eventlog system + 2 Job2 Completed True LocalHost Get-EventLog system ``` 1. To get the results of the job, use the `Invoke-Command` cmdlet to run a @@ -331,7 +332,7 @@ commands remotely to manage a local job on the remote computer. `Receive-Job` to keep the result in the job cache on the remote computer. ```powershell - $results = Invoke-Command -session $s -scriptblock { + $results = Invoke-Command -Session $s -ScriptBlock { Receive-Job -SessionId 2 -Keep } ``` @@ -341,7 +342,7 @@ commands remotely to manage a local job on the remote computer. file on the Server01 computer. ```powershell - Invoke-Command -session $s -command { + Invoke-Command -Session $s -Command { Receive-Job -SessionId 2 > c:\logs\pslog.txt } ``` diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md index 8017b8e51b5b..c2e09533863c 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Troubleshooting.md @@ -77,8 +77,8 @@ For errors: > - ERROR: ACCESS IS DENIED > - ERROR: The connection to the remote host was refused. Verify that the -> WS-Management service is running on the remote host and configured to listen -> for requests on the correct port and HTTP URL. +> WS-Management service is running on the remote host and configured to +> listen for requests on the correct port and HTTP URL. Enable the **Allow automatic configuration of listeners** policy to configure the listeners for all computers in a domain. @@ -137,7 +137,6 @@ The `Set-NetFirewallRule` cmdlet is exported by the **NetSecurity** module. For errors: > - ERROR: ACCESS IS DENIED - > - ERROR: The connection to the remote host was refused. Verify that the > WS-Management service is running on the remote host and configured to > listen for requests on the correct port and HTTP URL. diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 8879e6c9fbc8..12f698ba5de1 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -77,10 +77,11 @@ $ps = "*PowerShell*" Invoke-Command -Session $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} ``` -A variable reference such as `$using:var` expands to the value of variable `$var` -from the caller's context. You do not get access to the caller's variable object. -The `Using` scope modifier cannot be used to modify a local variable within the -**PSSession**. For example, the following code does not work: +A variable reference such as `$using:var` expands to the value of variable +`$var` from the caller's context. You do not get access to the caller's +variable object. The `Using` scope modifier cannot be used to modify a local +variable within the **PSSession**. For example, the following code does not +work: ```powershell $s = New-PSSession -ComputerName S1 diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Requires.md index d721d498afb0..fdb353514bdf 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Requires.md @@ -16,9 +16,9 @@ Prevents a script from running without the required elements. ## Long description The `#Requires` statement prevents a script from running unless the PowerShell -version, modules (and version), and edition -prerequisites are met. If the prerequisites aren't met, PowerShell doesn't run -the script or provide other runtime features, such as tab completion. +version, modules (and version), and edition prerequisites are met. If the +prerequisites aren't met, PowerShell doesn't run the script or provide other +runtime features, such as tab completion. ### Syntax diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Return.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Return.md index 8ad390bc4a06..84c3af3374b1 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Return.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Return.md @@ -28,8 +28,8 @@ return only the value or values that are specified by the `return` keyword. > [!NOTE] > Beginning in PowerShell 5.0, PowerShell added language for defining > classes, by using formal syntax. In the context of a PowerShell class, -> nothing is output from a method except what you specify using a -> `return` statement. You can read more about PowerShell classes in +> nothing is output from a method except what you specify using a `return` +> statement. You can read more about PowerShell classes in > [about_Classes](about_Classes.md). ### Syntax @@ -67,7 +67,7 @@ function MultiplyEven 1..10 | ForEach-Object {MultiplyEven -Number $_} ``` -```output +```Output 1 is not even 4 3 is not even @@ -125,7 +125,7 @@ by the function and assigned to the `$a` variable. If you would like to display a message within your function, beginning in PowerShell 5.0, you can use the `Information` stream. The code below corrects the above example using the `Write-Information` cmdlet with a -`InformationAction` of **Continue**. +**InformationAction** set to `Continue`. ```powershell function calculation { @@ -135,13 +135,15 @@ function calculation { $value += 73 return $value } - -$a = calculation 14 ``` -```output +Now the information message to display in the host and not assigned to the +variable. + +```powershell +PS> $a = calculation 14 Please wait. Working on calculation... -C:\PS> $a +PS> $a 87 ``` diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md index ebe7f2ad9755..072aab575859 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md @@ -28,8 +28,8 @@ To use the **Run with PowerShell** feature: In File Explorer (or Windows Explorer), right-click the script filename and then select **Run with PowerShell**. -The **Run with PowerShell** feature starts a Windows PowerShell session that has -an execution policy of Bypass, runs the script, and closes the session. +The **Run with PowerShell** feature starts a Windows PowerShell session that +has an execution policy of Bypass, runs the script, and closes the session. It runs a command that has the following format: diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md index e78d763bac0f..383da941e797 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md @@ -31,8 +31,7 @@ To support international Help text, PowerShell includes the following features: - A Data section that separates text strings from code instructions. For more - information about the Data section, see - [about_Data_Sections](about_Data_Sections.md). + information about the Data section, see [about_Data_Sections][01]. - New automatic variables, `$PSCulture` and `$PSUICulture`. `$PSCulture` stores the name of the UI language used on the system for elements such as the date, @@ -42,7 +41,7 @@ features: - A cmdlet, `ConvertFrom-StringData`, that converts text strings into dictionary-like hash tables to facilitate translation. For more information, - see [ConvertFrom-StringData](xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData). + see [ConvertFrom-StringData][02]. - A new file type, `.psd1`, that stores translated text strings. The `.psd1` files are stored in language-specific subdirectories of the script directory. @@ -50,7 +49,7 @@ features: - A cmdlet, `Import-LocalizedData`, that imports translated text strings for a specified language into a script at runtime. This cmdlet recognizes and imports strings in any Windows-supported language. For more information see - [Import-LocalizedData](xref:Microsoft.PowerShell.Utility.Import-LocalizedData). + [Import-LocalizedData][03]. ### The Data Section: Storing Default Strings @@ -79,8 +78,7 @@ $msgTable = Data { } ``` -For more information about here-strings, see -[about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see [about_Quoting_Rules][04]. ### PSD1 Files: Storing Translated Strings @@ -242,9 +240,18 @@ Heute ist Freitag ## See also -- [about_Data_Sections](about_Data_Sections.md) -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_Quoting_Rules](about_Quoting_Rules.md) -- [Import-LocalizedData](xref:Microsoft.PowerShell.Utility.Import-LocalizedData) -- [ConvertFrom-StringData](xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData) +- [about_Data_Sections][01] +- [about_Automatic_Variables][05] +- [about_Hash_Tables][06] +- [about_Quoting_Rules][07] +- [Import-LocalizedData][03] +- [ConvertFrom-StringData][02] + + +[01]: about_Data_Sections.md +[02]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData +[03]: xref:Microsoft.PowerShell.Utility.Import-LocalizedData +[04]: about_Quoting_Rules.md +[05]: about_Automatic_Variables.md +[06]: about_Hash_Tables.md +[07]: about_Quoting_Rules.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Scripts.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Scripts.md index 0c48fb20d4fd..995a850a8937 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Scripts.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Scripts.md @@ -38,7 +38,7 @@ running on non-Windows platforms. The default execution policy, `Restricted`, prevents all scripts from running, including scripts that you write on the local computer. For more information, -see [about_Execution_Policies](about_Execution_Policies.md). +see [about_Execution_Policies][01]. The execution policy is saved in the registry, so you need to change it only once on each computer. @@ -92,7 +92,7 @@ As a security feature, PowerShell does not run scripts when you double-click the script icon in File Explorer or when you type the script name without a full path, even when the script is in the current directory. For more information about running commands and scripts in PowerShell, see -[about_Command_Precedence](about_Command_Precedence.md). +[about_Command_Precedence][02]. ### Run with PowerShell @@ -106,12 +106,12 @@ PowerShell". The "Run with PowerShell" feature is designed to run scripts that do not have required parameters and do not return output to the command prompt. -For more information, see [about_Run_With_PowerShell](about_Run_With_PowerShell.md). +For more information, see [about_Run_With_PowerShell][03]. ### Running scripts on other computers -To run a script on one or more remote computers, use the **FilePath** parameter of -the `Invoke-Command` cmdlet. +To run a script on one or more remote computers, use the **FilePath** parameter +of the `Invoke-Command` cmdlet. Enter the path and filename of the script as the value of the **FilePath** parameter. The script must reside on the local computer or in a directory that @@ -121,8 +121,11 @@ The following command runs the `Get-ServiceLog.ps1` script on the remote computers named Server01 and Server02. ```powershell -Invoke-Command -ComputerName Server01,Server02 -FilePath ` - C:\Scripts\Get-ServiceLog.ps1 +$invokeCommandSplat = @{ + ComputerName = 'Server01', 'Server02' + FilePath = 'C:\Scripts\Get-ServiceLog.ps1' +} +Invoke-Command @invokeCommandSplat ``` ## Get help for scripts @@ -135,7 +138,7 @@ path is in your `Path` environment variable, you can omit the path. For example, to get help for the ServicesLog.ps1 script, type: ```powershell -get-help C:\admin\scripts\ServicesLog.ps1 +Get-Help C:\admin\scripts\ServicesLog.ps1 ``` ## How to write a script @@ -181,22 +184,22 @@ The following example shows a `Test-Remote.ps1` script that has a param ($ComputerName = $(throw "ComputerName parameter is required.")) function CanPing { - $error.clear() + $error.Clear() $tmp = Test-Connection $computername -ErrorAction SilentlyContinue if (!$?) - {write-host "Ping failed: $ComputerName."; return $false} + {Write-Host "Ping failed: $ComputerName."; return $false} else - {write-host "Ping succeeded: $ComputerName"; return $true} + {Write-Host "Ping succeeded: $ComputerName"; return $true} } function CanRemote { $s = New-PSSession $computername -ErrorAction SilentlyContinue if ($s -is [System.Management.Automation.Runspaces.PSSession]) - {write-host "Remote test succeeded: $ComputerName."} + {Write-Host "Remote test succeeded: $ComputerName."} else - {write-host "Remote test failed: $ComputerName."} + {Write-Host "Remote test failed: $ComputerName."} } if (CanPing $computername) {CanRemote $computername} @@ -205,15 +208,14 @@ if (CanPing $computername) {CanRemote $computername} To run this script, type the parameter name after the script name. For example: ```powershell -C:\PS> .\test-remote.ps1 -computername Server01 +C:\PS> .\test-remote.ps1 -ComputerName Server01 Ping succeeded: Server01 Remote test failed: Server01 ``` For more information about the Param statement and the function parameters, see -[about_Functions](about_Functions.md) and -[about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md). +[about_Functions][04] and [about_Functions_Advanced_Parameters][05]. ### Writing help for scripts @@ -225,7 +227,7 @@ methods: Create a Help topic by using special keywords in the comments. To create comment-based Help for a script, the comments must be placed at the beginning or end of the script file. For more information about comment-based Help, see - [about_Comment_Based_Help](about_Comment_Based_Help.md). + [about_Comment_Based_Help][06]. - XML-Based Help for Scripts @@ -235,9 +237,8 @@ methods: To associate the script with the XML-based Help topic, use the .ExternalHelp Help comment keyword. For more information about the ExternalHelp keyword, see -[about_Comment_Based_Help](about_Comment_Based_Help.md). For more information -about XML-based help, see -[How to Write Cmdlet Help](/powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets). +[about_Comment_Based_Help][06]. For more information about XML-based help, see +[How to Write Cmdlet Help][07]. ### Returning an exit value @@ -304,12 +305,12 @@ function and the `$ProfileName` variable. function New-Profile { Write-Host "Running New-Profile function" - $profileName = split-path $profile -leaf + $profileName = Split-Path $profile -Leaf - if (test-path $profile) - {write-error "Profile $profileName already exists on this computer."} + if (Test-Path $profile) + {Write-Error "Profile $profileName already exists on this computer."} else - {new-item -type file -path $profile -force } + {New-Item -Type file -Path $profile -Force } } ``` @@ -353,7 +354,7 @@ C:\PS> $profileName Microsoft.PowerShellISE_profile.ps1 ``` -For more information about scope, see [about_Scopes](about_Scopes.md). +For more information about scope, see [about_Scopes][08]. ## Scripts in modules @@ -367,7 +368,7 @@ which is a module that consists entirely or primarily of a script and supporting resources. A script module is just a script with a .psm1 file extension. -For more information about modules, see [about_Modules](about_Modules.md). +For more information about modules, see [about_Modules][09]. ## Other script features @@ -375,7 +376,7 @@ PowerShell has many useful features that you can use in scripts. - `#Requires` - You can use a `#Requires` statement to prevent a script from running without specified modules or snap-ins and a specified version of - PowerShell. For more information, see [about_Requires](about_Requires.md). + PowerShell. For more information, see [about_Requires][10]. - `$PSCommandPath` - Contains the full path and name of the script that is being run. This parameter is valid in all scripts. This automatic variable is @@ -398,11 +399,11 @@ PowerShell has many useful features that you can use in scripts. script. The values of these properties are populated only when the invoker or caller is a script. - - **PSCommandPath** contains the full path and name of the script that called or - invoked the current script. + - **PSCommandPath** contains the full path and name of the script that called + or invoked the current script. - - **PSScriptRoot** contains the directory of the script that called or invoked - the current script. + - **PSScriptRoot** contains the directory of the script that called or + invoked the current script. Unlike the `$PSCommandPath` and `$PSScriptRoot` automatic variables, which contain information about the current script, the **PSCommandPath** and @@ -411,26 +412,43 @@ PowerShell has many useful features that you can use in scripts. - Data sections - You can use the `Data` keyword to separate data from logic in scripts. Data sections can also make localization easier. For more - information, see [about_Data_Sections](about_Data_Sections.md) and - [about_Script_Internationalization](about_Script_Internationalization.md). + information, see [about_Data_Sections][11] and + [about_Script_Internationalization][12]. - Script Signing - You can add a digital signature to a script. Depending on the execution policy, you can use digital signatures to restrict the running of scripts that could include unsafe commands. For more information, see - [about_Execution_Policies](about_Execution_Policies.md) and - [about_Signing](about_Signing.md). + [about_Execution_Policies][01] and [about_Signing][13]. ## See also -- [about_Command_Precedence](about_Command_Precedence.md) -- [about_Comment_Based_Help](about_Comment_Based_Help.md) -- [about_Execution_Policies](about_Execution_Policies.md) -- [about_Functions](about_Functions.md) -- [about_Modules](about_Modules.md) -- [about_Profiles](about_Profiles.md) -- [about_Requires](about_Requires.md) -- [about_Run_With_PowerShell](about_Run_With_PowerShell.md) -- [about_Scopes](about_Scopes.md) -- [about_Script_Blocks](about_Script_Blocks.md) -- [about_Signing](about_Signing.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) +- [about_Command_Precedence][02] +- [about_Comment_Based_Help][06] +- [about_Execution_Policies][01] +- [about_Functions][04] +- [about_Modules][09] +- [about_Profiles][14] +- [about_Requires][10] +- [about_Run_With_PowerShell][03] +- [about_Scopes][08] +- [about_Script_Blocks][15] +- [about_Signing][13] +- [Invoke-Command][16] + + +[01]: about_Execution_Policies.md +[02]: about_Command_Precedence.md +[03]: about_Run_With_PowerShell.md +[04]: about_Functions.md +[05]: about_Functions_Advanced_Parameters.md +[06]: about_Comment_Based_Help.md +[07]: /powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets +[08]: about_Scopes.md +[09]: about_Modules.md +[10]: about_Requires.md +[11]: about_Data_Sections.md +[12]: about_Script_Internationalization.md +[13]: about_Signing.md +[14]: about_Profiles.md +[15]: about_Script_Blocks.md +[16]: xref:Microsoft.PowerShell.Core.Invoke-Command diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md index 55c607384d02..d4b08274c0c5 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md @@ -21,8 +21,8 @@ sessions that use the session configuration. A "session configuration file" is a text file with a .pssc file name extension that contains a hash table of session configuration properties and values. You can use a session configuration file to set the properties of a session -configuration. Doing so defines the environment of any PowerShell -sessions that use that session configuration. +configuration. Doing so defines the environment of any PowerShell sessions that +use that session configuration. Session configuration files make it easy to create custom session configurations without using complex C# assemblies or scripts. @@ -31,7 +31,7 @@ A "session configuration" or "endpoint" is a collection of local computer settings that determine such things as which users can create sessions on the computer; which commands users can run in those sessions; and whether the session should run as a privileged virtual account. For more information about -session configurations, see [about_Session_Configurations](about_Session_Configurations.md). +session configurations, see [about_Session_Configurations][01]. Session configurations were introduced in Windows PowerShell 2.0, and session configuration files were introduced in Windows PowerShell 3.0. You must use @@ -41,9 +41,9 @@ affected by the settings in the session configuration. ## Creating Custom Sessions -You can customize many features of a PowerShell session by specifying -session properties in a session configuration. You can customize a session by -writing a C# program that defines a custom runspace, or you can use a session +You can customize many features of a PowerShell session by specifying session +properties in a session configuration. You can customize a session by writing a +C# program that defines a custom runspace, or you can use a session configuration file to define the properties of sessions created by using the session configuration. As a general rule, it is easier to use the session configuration file than to write a C# program. @@ -55,25 +55,25 @@ the modules required for those tasks; and sessions where unprivileged users can only run specific commands as a privileged account. In addition to that, you can manage whether users of the session can use -PowerShell language elements such as script blocks, or whether they -can only run commands. You can manage the version of PowerShell users -can run in the session; manage which modules are imported into the session; -and manage which cmdlets, functions, and aliases session users can run. When -using the RoleDefinitions field, you can give users different capabilities in -the session based on group membership. +PowerShell language elements such as script blocks, or whether they can only +run commands. You can manage the version of PowerShell users can run in the +session; manage which modules are imported into the session; and manage which +cmdlets, functions, and aliases session users can run. When using the +RoleDefinitions field, you can give users different capabilities in the session +based on group membership. For more information about RoleDefinitions and how to define this Value, see -the help topic for the New-PSRoleCapabilityFile Cmdlet. +the help topic for the `New-PSRoleCapabilityFile` Cmdlet. ## Creating a Session Configuration File The easiest way to create a session configuration file is by using the -New-PSSessionConfigurationFile cmdlet. This cmdlet generates a file that uses +`New-PSSessionConfigurationFile` cmdlet. This cmdlet generates a file that uses the correct syntax and format, and that automatically verifies many of the configuration file property values. For detailed descriptions of the properties that you can set in a session -configuration file, see the help topic for the New-PSSessionConfigurationFile +configuration file, see the help topic for the `New-PSSessionConfigurationFile` cmdlet. The following command creates a session configuration file that uses the @@ -108,8 +108,7 @@ To create a session configuration for sessions in which users can use only Get cmdlets, type: ```powershell -New-PSSessionConfigurationFile -VisibleCmdlets Get-* --Path .\GetSessions.pssc +New-PSSessionConfigurationFile -VisibleCmdlets Get-* -Path .\GetSessions.pssc ``` In the preceding example, setting the VisibleCmdlets parameter to Get-* limits @@ -119,8 +118,7 @@ To create a session configuration for sessions that run under a privileged virtual account instead of the user's credentials, type: ```powershell -New-PSSessionConfigurationFile -RunAsVirtualAccount --Path .\VirtualAccount.pssc +New-PSSessionConfigurationFile -RunAsVirtualAccount -Path .\VirtualAccount.pssc ``` To create a session configuration for sessions in which the commands visible @@ -139,7 +137,7 @@ configuration or add you can add a file to the session configuration at a later time. To include a session configuration file when creating a session configuration, -use the Path parameter of the Register-PSSessionConfiguration cmdlet. +use the Path parameter of the `Register-PSSessionConfiguration` cmdlet. For example, the following command uses the NoLanguage.pssc file when it creates a NoLanguage session configuration. @@ -149,43 +147,43 @@ Register-PSSessionConfiguration -Name NoLanguage -Path .\NoLanguage.pssc ``` -When a new NoLanguage session starts, users will only have access to PowerShell commands. +When a new NoLanguage session starts, users will only have access to PowerShell +commands. To add a session configuration file to an existing session configuration, use the Set-PSSessionConfiguration cmdlet and the Path parameter. This affects any new sessions created with the specified session configuration. Note that the -Set-PSSessionConfiguration cmdlet changes the session itself and does not +`Set-PSSessionConfiguration` cmdlet changes the session itself and does not modify the session configuration file. For example, the following command adds the NoLanguage.pssc file to the LockedDown session configuration. ```powershell -Set-PSSessionConfiguration -Name LockedDown --Path .\NoLanguage.pssc +Set-PSSessionConfiguration -Name LockedDown -Path .\NoLanguage.pssc ``` When users use the LockedDown session configuration to create a session, they will be able to run cmdlets but they will not be able to create or use variables, assign values, or use other PowerShell language elements. -The following command uses the New-PSSession cmdlet to create a session on the -computer Srv01 that uses the LockedDown session configuration, saving an +The following command uses the `New-PSSession` cmdlet to create a session on +the computer Srv01 that uses the LockedDown session configuration, saving an object reference to the session in the $s variable. The ACL (access control list) of the session configuration determines who can use it to create a session. ```powershell -$s = New-PSSession -ComputerName Srv01 --ConfigurationName LockedDown +$s = New-PSSession -ComputerName Srv01 -ConfigurationName LockedDown ``` Because the NoLanguage constraints were added to the LockedDown session -configuration, users in LockedDown sessions will only be able to run PowerShell commands and cmdlets. For example, the following two commands use -the Invoke-Command cmdlet to run commands in the session referenced in the $s -variable. The first command, which runs the Get-UICulture cmdlet and does not +configuration, users in LockedDown sessions will only be able to run PowerShell +commands and cmdlets. For example, the following two commands use the +`Invoke-Command` cmdlet to run commands in the session referenced in the $s +variable. The first command, which runs the `Get-UICulture` cmdlet and does not use any variables, succeeds. The second command, which gets the value of the -$PSUICulture variable, fails. +`$PSUICulture` variable, fails. ``` Invoke-Command -Session $s {Get-UICulture} @@ -206,7 +204,8 @@ RunAsVirtualAccountGroups can be modified by editing the session configuration file used by the session configuration. To do this, begin by locating the active copy of the session configuration file. -When you use a session configuration file in a session configuration, PowerShell creates an active copy of the session configuration file and stores +When you use a session configuration file in a session configuration, +PowerShell creates an active copy of the session configuration file and stores it in the \$pshome\\SessionConfig directory on the local computer. The location of the active copy of a session configuration file is stored in @@ -250,12 +249,12 @@ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc ``` If the syntax and values in the configuration file are valid -Test-PSSessionConfigurationFile returns True. If the syntax and values are not -valid then the cmdlet returns False. +`Test-PSSessionConfigurationFile` returns True. If the syntax and values are +not valid then the cmdlet returns False. -You can use Test-PSSessionConfigurationFile to test any session configuration +You can use `Test-PSSessionConfigurationFile` to test any session configuration file, including files that the New-PSSessionConfiguration cmdlet creates. For -more information, see the help topic for the Test-PSSessionConfigurationFile +more information, see the help topic for the `Test-PSSessionConfigurationFile` cmdlet. ## Removing a Session Configuration File @@ -266,7 +265,7 @@ settings. This effectively cancels the settings used by the original configuration file. To replace a session configuration file, create a new session configuration -file that uses the default settings, then use the Set-PSSessionConfiguration +file that uses the default settings, then use the `Set-PSSessionConfiguration` cmdlet to replace the custom session configuration file with the new file. For example, the following commands create a Default session configuration @@ -288,8 +287,8 @@ objects that represent session configurations using session configuration files have additional properties that make it easy to discover and analyze the session configuration. (Note that the type name shown below includes a formatted view definition.) You can view the properties by running the -Get-PSSessionConfiguration cmdlet and piping the returned data to the -Get-Member cmdlet: +`Get-PSSessionConfiguration` cmdlet and piping the returned data to the +`Get-Member` cmdlet: ```powershell Get-PSSessionConfiguration NoLanguage | Get-Member @@ -352,20 +351,18 @@ use session configuration files, the command might not return all qualifying session configurations. ```powershell -Get-PSSessionConfiguration | -where {$_.ExecutionPolicy -eq "RemoteSigned"} +Get-PSSessionConfiguration | Where-Object {$_.ExecutionPolicy -eq "RemoteSigned"} ``` The following command gets session configurations in which the RunAsUser is the Exchange administrator. ```powershell - Get-PSSessionConfiguration | -where {$_.RunAsUser -eq "Exchange01\Admin01"} + Get-PSSessionConfiguration | Where-Object {$_.RunAsUser -eq "Exchange01\Admin01"} ``` To view information about the role definitions associated with a configuration -use the Get-PSSessionCapability cmdlet. This cmdlet enables you to determine +use the `Get-PSSessionCapability` cmdlet. This cmdlet enables you to determine the commands and environment available to specific users in specific endpoints. @@ -380,15 +377,29 @@ working with an empty session. ## See also -- [about_Session_Configurations](about_Session_Configurations.md) -- [New-PSRoleCapabilityFile](xref:Microsoft.PowerShell.Core.New-PSRoleCapabilityFile) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) -- [Get-PSSessionCapability](xref:Microsoft.PowerShell.Core.Get-PSSessionCapability) -- [Disable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Disable-PSSessionConfiguration) -- [Enable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Enable-PSSessionConfiguration) -- [Get-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Get-PSSessionConfiguration) -- [Register-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Register-PSSessionConfiguration) -- [Set-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Set-PSSessionConfiguration) -- [Unregister-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Unregister-PSSessionConfiguration) -- [New-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.New-PSSessionConfigurationFile) -- [Test-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.Test-PSSessionConfigurationFile) +- [about_Session_Configurations][01] +- [New-PSRoleCapabilityFile][02] +- [New-PSSession][03] +- [Get-PSSessionCapability][04] +- [Disable-PSSessionConfiguration][05] +- [Enable-PSSessionConfiguration][06] +- [Get-PSSessionConfiguration][07] +- [Register-PSSessionConfiguration][08] +- [Set-PSSessionConfiguration][09] +- [Unregister-PSSessionConfiguration][10] +- [New-PSSessionConfigurationFile][11] +- [Test-PSSessionConfigurationFile][12] + + +[01]: about_Session_Configurations.md +[02]: xref:Microsoft.PowerShell.Core.New-PSRoleCapabilityFile +[03]: xref:Microsoft.PowerShell.Core.New-PSSession +[04]: xref:Microsoft.PowerShell.Core.Get-PSSessionCapability +[05]: xref:Microsoft.PowerShell.Core.Disable-PSSessionConfiguration +[06]: xref:Microsoft.PowerShell.Core.Enable-PSSessionConfiguration +[07]: xref:Microsoft.PowerShell.Core.Get-PSSessionConfiguration +[08]: xref:Microsoft.PowerShell.Core.Register-PSSessionConfiguration +[09]: xref:Microsoft.PowerShell.Core.Set-PSSessionConfiguration +[10]: xref:Microsoft.PowerShell.Core.Unregister-PSSessionConfiguration +[11]: xref:Microsoft.PowerShell.Core.New-PSSessionConfigurationFile +[12]: xref:Microsoft.PowerShell.Core.Test-PSSessionConfigurationFile diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Session_Configurations.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Session_Configurations.md index 7ecb98a8816e..952018297318 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Session_Configurations.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Session_Configurations.md @@ -17,7 +17,8 @@ the computer remotely and the commands they can run. A session configuration, also known as an "endpoint" is a group of settings on the local computer that define the environment for the PowerShell sessions that -are created when remote or local users connect to PowerShell on the local computer. +are created when remote or local users connect to PowerShell on the local +computer. Administrators of the computer can use session configurations to protect the computer and to define custom environments for users who connect to the @@ -33,9 +34,8 @@ Beginning in PowerShell 3.0, you can use a session configuration file to define the elements of a session configuration. This feature makes it easy to customize sessions without writing code and to discover the properties of a session configuration. To create a session configuration file, use the -New-PSSessionConfiguration cmdlet. For more information about session -configuration files, see -[about_Session_Configuration_Files](about_Session_Configuration_Files.md). +`New-PSSessionConfiguration` cmdlet. For more information about session +configuration files, see [about_Session_Configuration_Files][01]. Session configurations are a feature of WSMAN-based PowerShell remoting. They are used only when you use the `New-PSSession`, `Invoke-Command`, or @@ -44,13 +44,13 @@ are used only when you use the `New-PSSession`, `Invoke-Command`, or To manage the session configurations on a Windows computer, start PowerShell with the **Run as administrator** option. -About Session Configurations +### About Session Configurations Every PowerShell session uses a session configuration. This includes -persistent sessions that you create by using the New-PSSession or -Enter-PSSession cmdlets, and the temporary sessions that PowerShell creates +persistent sessions that you create by using the `New-PSSession` or +`Enter-PSSession` cmdlets, and the temporary sessions that PowerShell creates when you use the ComputerName parameter of a cmdlet that uses -WS-Management-based remoting technology, such as Invoke-Command. +WS-Management-based remoting technology, such as `Invoke-Command`. Administrators can use session configurations to protect the resources of the computer and to create custom environments for users who connect to the @@ -71,7 +71,7 @@ default session configurations. But, you can change the security descriptors to allow everyone, no one, or only selected users to use the session configurations on your computer. -Built-in Session Configurations +### Built-in Session Configurations PowerShell 3.0 includes built-in session configurations named Microsoft.PowerShell and Microsoft.PowerShell.Workflow. On computers running @@ -80,8 +80,8 @@ Microsoft.PowerShell and Microsoft.PowerShell.Workflow. On computers running The Microsoft.PowerShell session configuration is used for sessions by default, that is, when a command to create a session does not include the -ConfigurationName parameter of the New-PSSession, Enter-PSSession, or -Invoke-Command cmdlet. +ConfigurationName parameter of the `New-PSSession`, `Enter-PSSession`, or +`Invoke-Command` cmdlet. The security descriptors for the default session configurations allow only members of the Administrators group on the local computer to use them. As @@ -89,13 +89,13 @@ such, only members of the Administrators group can connect to the computer remotely unless you change the default settings. You can change the default session configurations by using the -$PSSessionConfigurationName preference variable. For more information, see -about_Preference_Variables. +`$PSSessionConfigurationName` preference variable. For more information, see +[about_Preference_Variables][02]. -Viewing Session Configurations on the Local Computer +### Viewing Session Configurations on the Local Computer To get the session configurations on your local computer, use the -Get-PSSessionConfiguration cmdlet. +`Get-PSSessionConfiguration` cmdlet. For example, type: @@ -145,11 +145,12 @@ Container {Name=microsoft.powershell.wor... microsoft.powershell.workflow Container {Name=microsoft.powershell32} microsoft.powershell32 ``` -Viewing Session Configurations on a Remote Computer +### Viewing Session Configurations on a Remote Computer -To view the session configurations on a remote computer, use the Connect-WSMan -cmdlet to add a note for the remote computer to the WSMAN: drive on your local -computer, and then use the WSMAN: drive to view the session configurations. +To view the session configurations on a remote computer, use the +`Connect-WSMan` cmdlet to add a note for the remote computer to the +WSMAN: drive on your local computer, and then use the WSMAN: drive to view the +session configurations. For example, the following command adds a node for the Server01 remote computer to the WSMAN: drive on the local computer. @@ -185,7 +186,7 @@ Container {Name=microsoft.powershell.wor... microsoft.powershell.workflow Container {Name=microsoft.powershell32} microsoft.powershell32 ``` -Changing the Security Descriptor of a Session Configuration +### Changing the Security Descriptor of a Session Configuration In Windows Server 2012 and newer releases of Windows Server, the built-in session configurations are enabled for remote users by default. In other @@ -193,7 +194,7 @@ supported versions of Windows, you must change the security descriptors of the session configurations to allow remote access. To enable remote access to the session configurations on the computer, use the -Enable-PSRemoting cmdlet. This cmdlet creates two session configurations: +`Enable-PSRemoting` cmdlet. This cmdlet creates two session configurations: - with the name defined as: "PowerShell." + "current PowerShell version" - with name "PowerShell.6", untied to any specific PowerShell version. @@ -213,12 +214,11 @@ the security descriptor for the Microsoft.PowerShell default session configuration. ```powershell -Set-PSSessionConfiguration -name Microsoft.PowerShell ` - -ShowSecurityDescriptorUI +Set-PSSessionConfiguration -Name Microsoft.PowerShell -ShowSecurityDescriptorUI ``` To deny everyone permission to all the session configurations on the computer, -use the Disable-PSSessionConfiguration cmdlet. For example, the following +use the `Disable-PSSessionConfiguration` cmdlet. For example, the following command disables the default session configurations on the computer. ```powershell @@ -226,7 +226,7 @@ PS C:> Disable-PSSessionConfiguration -Name Microsoft.PowerShell ``` To prevent remote users from connecting to the computer, but allow local users -to connect, use the Disable-PSRemoting cmdlet. Disable-PSRemoting adds a +to connect, use the `Disable-PSRemoting` cmdlet. `Disable-PSRemoting` adds a "Network_Deny_All" entry to all session configurations on the computer. ```powershell @@ -234,16 +234,16 @@ PS C:> Disable-PSRemoting ``` To allow remote users to use all session configurations on the computer, use -the Enable-PSRemoting or Enable-PSSessionConfiguration cmdlet. For example, +the `Enable-PSRemoting` or `Enable-PSSessionConfiguration` cmdlet. For example, the following command enables remote access to the built-in session configurations. ```powershell -PS C:> Enable-PSSessionConfiguration -name Microsoft.Power* +PS C:> Enable-PSSessionConfiguration -Name Microsoft.Power* ``` To make other changes to the security descriptor of a session configuration, -use the Set-PSSessionConfiguration cmdlet. Use the SecurityDescriptorSDDL +use the `Set-PSSessionConfiguration` cmdlet. Use the SecurityDescriptorSDDL parameter to submit an SDDL string value. Use the ShowSecurityDescriptorUI parameter to display a user interface property sheet that helps you to create a new SDDL. @@ -251,16 +251,15 @@ a new SDDL. For example: ```powershell -Set-PSSessionConfiguration -Name Microsoft.PowerShell ` - -ShowSecurityDescriptorUI +Set-PSSessionConfiguration -Name Microsoft.PowerShell -ShowSecurityDescriptorUI ``` -Creating a New Session Configuration +### Creating a New Session Configuration To create a new session configuration on the local computer, use the -Register-PSSessionConfiguration cmdlet. To define the new session +`Register-PSSessionConfiguration` cmdlet. To define the new session configuration, you can use a C# assembly, a PowerShell script, and the -parameters of the Register-PSSessionConfiguration cmdlet. +parameters of the `Register-PSSessionConfiguration` cmdlet. For example, the following command creates a session configuration that is identical the Microsoft.PowerShell session configuration, except that it @@ -268,52 +267,55 @@ limits the data received from a remote command to 20 megabytes (MB). (The default is 50 MB). ```powershell -Register-PSSessionConfiguration -Name NewConfig ` - -MaximumReceivedDataSizePerCommandMB 20 +$registerPSSessionConfigurationSplat = @{ + Name = 'NewConfig' + MaximumReceivedDataSizePerCommandMB = 20 +} +Register-PSSessionConfiguration @registerPSSessionConfigurationSplat ``` When you create a session configuration, you can manage it by using the other session configuration cmdlets, and it appears in the WSMAN: drive. -For more information, see Register-PSSessionConfiguration. +For more information, see `Register-PSSessionConfiguration`. -Removing a Session Configuration +### Removing a Session Configuration To remove a session configuration from the local computer, use the -Unregister-PSSessionConfiguration cmdlet. For example, the following command +`Unregister-PSSessionConfiguration` cmdlet. For example, the following command removes the NewConfig session configuration from the computer. ```powershell -PS C:> Unregister-PSSessionConfiguration -Name NewConfig +Unregister-PSSessionConfiguration -Name NewConfig ``` -For more information, see Unregister-PSSessionConfiguration. +For more information, see `Unregister-PSSessionConfiguration`. -Restoring a Session Configuration +### Restoring a Session Configuration To restore a default session configuration that was deleted (unregistered) -accidentally, use the Enable-PSRemoting cmdlet. +accidentally, use the `Enable-PSRemoting` cmdlet. -The Enable-PSRemoting cmdlet recreates all default sessions configurations +The `Enable-PSRemoting` cmdlet recreates all default sessions configurations that do not exist on the computer. It does not overwrite or change the property values of existing session configurations. To restore the original property values of a default session configuration, -use the Unregister-PSSessionConfiguration to delete the session configuration -and then use the Enable-PSRemoting cmdlet to recreate it. +use the `Unregister-PSSessionConfiguration` to delete the session configuration +and then use the `Enable-PSRemoting` cmdlet to recreate it. -Selecting a Session Configuration +### Selecting a Session Configuration To select a particular session configuration for a session, use the -ConfigurationName parameter of New-PSSession, Enter-PSSession, or -Invoke-Command. +ConfigurationName parameter of `New-PSSession`, `Enter-PSSession`, or +`Invoke-Command`. -For example, this command uses the New-PSSession cmdlet to start a PSSession +For example, this command uses the `New-PSSession` cmdlet to start a PSSession on the Server01 computer. The command uses the ConfigurationName parameter to select the WithProfile configuration on the Server01 computer. ```powershell -PS C:> New-PSSession -ComputerName Server01 -ConfigurationName WithProfile +New-PSSession -ComputerName Server01 -ConfigurationName WithProfile ``` This command will succeed only if the current user has permission to use the @@ -323,7 +325,7 @@ has the required permissions. You can also use the $PSSessionConfigurationName preference variable to change the default session configuration on the computer. For more information about the $PSSessionConfigurationName preference variable, see -about_Preference_Variables. +[about_Preference_Variables][02]. ## KEYWORDS @@ -332,10 +334,10 @@ about_SessionConfigurations ## See also -- [about_Preference_Variables](about_Preference_Variables.md) +- [about_Preference_Variables][02] - [about_PSSessions](about_PSSessions.md) - [about_Remote](about_Remote.md) -- [about_Session_Configuration_Files](about_Session_Configuration_Files.md) +- [about_Session_Configuration_Files][01] - [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) - [Disable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Disable-PSSessionConfiguration) - [Enable-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Enable-PSSessionConfiguration) @@ -345,3 +347,7 @@ about_SessionConfigurations - [Unregister-PSSessionConfiguration](xref:Microsoft.PowerShell.Core.Unregister-PSSessionConfiguration) - [New-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.New-PSSessionConfigurationFile) - [Test-PSSessionConfigurationFile](xref:Microsoft.PowerShell.Core.Test-PSSessionConfigurationFile) + + +[01]: about_Session_Configuration_Files.md +[02]: about_Preference_Variables.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md index 869e0af55362..d320977616dc 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md @@ -61,7 +61,7 @@ commands: ```powershell dir Cert:\LocalMachine\Root | Where FriendlyName -EQ 'Verisign' -dir Cert:\ -Recurse | ForEach GetKeyAlgorithm +dir Cert:\ -Recurse | foreach GetKeyAlgorithm ``` While both syntaxes work, the simplified syntax returns results without @@ -97,5 +97,5 @@ Get-ChildItem /home -Directory | foreach GetFiles .* - [about_Comparison_Operators](about_Comparison_Operators.md) - [about_Foreach](about_Foreach.md) -- [Foreach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) +- [ForEach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) - [Where-Object](xref:Microsoft.PowerShell.Core.Where-Object) diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Splatting.md index 993569f932f1..1b7a93702c93 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -72,7 +72,8 @@ table of parameter-name and parameter-value pairs and stores it in the variable in a command with splatting. The At symbol (`@HashArguments`) replaces the dollar sign (`$HashArguments`) in the command. -To provide a value for the **WhatIf** switch parameter, use `$True` or `$False`. +To provide a value for the **WhatIf** switch parameter, use `$True` or +`$False`. ```powershell $HashArguments = @{ diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Split.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Split.md index b700a96c9f8e..8dbadc094796 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Split.md @@ -9,6 +9,7 @@ title: about_Split # about_Split ## Short description + Explains how to use the Split operator to split one or more strings into substrings. diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md index 799f895c2893..a0d2e38624e8 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md @@ -192,10 +192,10 @@ examples evaluates 4 and then 2. ```powershell switch (4, 2) { - 1 {"It is one." } - 2 {"It is two." } - 3 {"It is three." } - 4 {"It is four." } + 1 {"It is one."} + 2 {"It is two."} + 3 {"It is three."} + 4 {"It is four."} 3 {"Three again."} } ``` @@ -213,9 +213,9 @@ statement in the condition of value 4. switch (4, 2) { 1 {"It is one."; Break} - 2 {"It is two." ; Break } - 3 {"It is three." ; Break } - 4 {"It is four." ; Break } + 2 {"It is two." ; Break} + 3 {"It is three." ; Break} + 4 {"It is four." ; Break} 3 {"Three again."} } ``` @@ -370,7 +370,7 @@ the beginning of the year 2022. ```powershell switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { { $_.Year -eq 2021 } { - $days = ((Get-Date 1/1/2022) - $_).days + $days = ((Get-Date 1/1/2022) - $_).Days "There are $days days until 2022." } { $_.Year -eq 2022 } { 'Welcome to 2022!' } diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md index 2e0d3076eb90..987d8357824f 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Tab_Expansion.md @@ -119,8 +119,9 @@ keys to select the value you want. Tab completion can also work to complete parameter arguments. You can use the Tab key to cycle through a list of possible values that are valid -for some parameter. For more information, see -[about_Functions_Argument_Completion][04]. +for some parameter. + +For more information, see [about_Functions_Argument_Completion][04]. ## Enumerated value completion diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Telemetry.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Telemetry.md index ffbd90014bb7..4edafa9d634f 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Telemetry.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Telemetry.md @@ -65,7 +65,8 @@ session for all host applications. To opt-out of this telemetry, set the environment variable `$env:POWERSHELL_TELEMETRY_OPTOUT` to `true`, `yes`, or `1`. For this environment variable to have effect, it must be set before starting the -PowerShell process. For more information, see [about_Environment_Variables][01]. +PowerShell process. For more information, see +[about_Environment_Variables][01]. The `$env:POWERSHELL_DISTRIBUTION_CHANNEL` environment variable is set by the installer packages to record the method and source of installation for @@ -79,6 +80,6 @@ For more information about Microsoft's statement on privacy, see [Microsoft Privacy Statement][03] -[01]: about_environment_variables.md#powershell-environment-variables +[01]: about_Environment_Variables.md#powershell-environment-variables [02]: /azure/azure-monitor/app/ip-collection?tabs=net [03]: https://privacy.microsoft.com/privacystatement diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Thread_Jobs.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Thread_Jobs.md index f992681cd0a7..983f11d46e5e 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Thread_Jobs.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Thread_Jobs.md @@ -21,9 +21,9 @@ PowerShell concurrently runs commands and scripts through jobs. There are three jobs types provided by PowerShell to support concurrency. - `RemoteJob` - Commands and scripts run in a remote session. For information, - see [about_Remote_Jobs](about_Remote_Jobs.md). + see [about_Remote_Jobs][01]. - `BackgroundJob` - Commands and scripts run in a separate process on the local - machine. For more information, see [about_Jobs](about_Jobs.md). + machine. For more information, see [about_Jobs][02]. - `PSTaskJob` or `ThreadJob` - Commands and scripts run in a separate thread within the same process on the local machine. @@ -46,10 +46,9 @@ faster and use fewer resources than the other job types. There are two ways work around this situation: 1. Use `Invoke-Command` to create jobs that run in disconnected sessions. For - more information, see [about_Remote_Jobs](about_Remote_Jobs.md). + more information, see [about_Remote_Jobs][01]. 1. Use `Start-Process` to create a new process rather than a job. For more - information, see - [Start-Process](xref:Microsoft.PowerShell.Management.Start-Process). + information, see [Start-Process][03]. ## How to start and manage thread-based jobs @@ -59,7 +58,7 @@ There are two ways to start thread-based jobs: - `ForEach-Object -Parallel -AsJob` - the parallel feature was added in PowerShell 7.0 -Use the same **Job** cmdlets described in [about_Jobs](about_Jobs.md) to manage +Use the same **Job** cmdlets described in [about_Jobs][02] to manage thread-based jobs. ### Using `Start-ThreadJob` @@ -184,7 +183,7 @@ system logs. Since the script involves reading a number of logs, it makes sense to do the operations in parallel. ```powershell -$logNames.count +$logNames.Count 10 Measure-Command { @@ -277,14 +276,29 @@ NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName ## See also -- [about_Job_Details](about_Job_Details.md) -- [about_Remote_Jobs](about_Remote_Jobs.md) -- [about_Thread_Jobs](about_Thread_Jobs.md) -- [about_PSSessions](about_PSSessions.md) -- [about_Remote](about_Remote.md) -- [Get-Job](xref:Microsoft.PowerShell.Core.Get-Job) -- [Receive-Job](xref:Microsoft.PowerShell.Core.Receive-Job) -- [Remove-Job](xref:Microsoft.PowerShell.Core.Remove-Job) -- [Start-Job](xref:Microsoft.PowerShell.Core.Start-Job) -- [Stop-Job](xref:Microsoft.PowerShell.Core.Stop-Job) -- [Wait-Job](xref:Microsoft.PowerShell.Core.Wait-Job) +- [about_Job_Details][04] +- [about_Remote_Jobs][01] +- [about_Thread_Jobs][05] +- [about_PSSessions][06] +- [about_Remote][07] +- [Get-Job][08] +- [Receive-Job][09] +- [Remove-Job][10] +- [Start-Job][11] +- [Stop-Job][12] +- [Wait-Job][13] + + +[01]: about_Remote_Jobs.md +[02]: about_Jobs.md +[03]: xref:Microsoft.PowerShell.Management.Start-Process +[04]: about_Job_Details.md +[05]: about_Thread_Jobs.md +[06]: about_PSSessions.md +[07]: about_Remote.md +[08]: xref:Microsoft.PowerShell.Core.Get-Job +[09]: xref:Microsoft.PowerShell.Core.Receive-Job +[10]: xref:Microsoft.PowerShell.Core.Remove-Job +[11]: xref:Microsoft.PowerShell.Core.Start-Job +[12]: xref:Microsoft.PowerShell.Core.Stop-Job +[13]: xref:Microsoft.PowerShell.Core.Wait-Job diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Trap.md index 0538b111449b..c053298e6614 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Trap.md @@ -366,8 +366,8 @@ however, the `trap` statement is outside the function. PowerShell doesn't go back into the function after the `trap` statement runs. > [!CAUTION] -> When multiple traps are defined for the same error condition, the first `trap` -> defined lexically (highest in the script block) is used. +> When multiple traps are defined for the same error condition, the first +> `trap` defined lexically (highest in the script block) is used. In the following example, only the `trap` with `whoops 1` runs. diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md index b1a3dcd7b012..c6510c70346d 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md @@ -255,7 +255,7 @@ try { "An error occurred that could not be resolved." } finally { $wc.Dispose() - if (Test-Path $tempPath) { Remove-item $tempFile } + if (Test-Path $tempPath) { Remove-Item $tempFile } } ``` diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Type_Conversion.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Type_Conversion.md index c3697bd90b7c..0bf33f4b96a8 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Type_Conversion.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Type_Conversion.md @@ -528,8 +528,8 @@ For more information, see [about_Comparison_Operators][05]. [05]: about_Comparison_Operators.md [06]: about_Functions_Advanced.md [07]: about_Numeric_Literals.md -[08]: about_parameter_binding.md -[09]: about_preference_variables.md#ofs +[08]: about_Parameter_Binding.md +[09]: about_Preference_Variables.md#ofs [10]: about_Types.ps1xml.md [11]: https://stackoverflow.com/questions/76241804/how-does-powershell-split-consecutive-strings-not-a-single-letter [12]: xref:Microsoft.PowerShell.Utility.Update-TypeData diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index 53b488fc802c..46f2a6fe1f2b 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -25,8 +25,7 @@ data to a PowerShell session. This topic describes `Types.ps1xml` files. For more information about using the `Update-TypeData` cmdlet to add dynamic extended type data to the current -session see -[Update-TypeData](xref:Microsoft.PowerShell.Utility.Update-TypeData). +session see [Update-TypeData][01]. ## About extended type data @@ -47,8 +46,8 @@ Sunday, January 29, 2012 9:43:57 AM ``` You won't find the **DateTime** property in the description of the -[System.DateTime](/dotnet/api/system.datetime) structure, because PowerShell -adds the property and it is visible only in PowerShell. +[System.DateTime][02] structure, because PowerShell adds the property and it is +visible only in PowerShell. PowerShell internally defines a default set of extended types. This type information is loaded in every PowerShell session at startup. The **DateTime** @@ -142,12 +141,12 @@ As a result, you can use either the **Count** property or the **Length** property of arrays in PowerShell. For example: ```powershell -(1, 2, 3, 4).count +(1, 2, 3, 4).Count 4 ``` ```powershell -(1, 2, 3, 4).length +(1, 2, 3, 4).Length 4 ``` @@ -177,9 +176,7 @@ the `Update-TypeData` command to your PowerShell profile. The `Types.ps1xml` files add properties and methods to all the instances of the objects of the specified .NET type in the affected PowerShell session. However, if you need to add properties or methods only to one instance of an object, use -the `Add-Member` cmdlet. - -For more information, see [Add-Member](xref:Microsoft.PowerShell.Utility.Add-Member). +the `Add-Member` cmdlet. For more information, see [Add-Member][03]. ## Example: Adding an Age member to FileInfo objects @@ -211,10 +208,8 @@ Save the follow XML code to the file `$PSHOME\MyTypes.ps1xml`. Run `Update-TypeData` to add the new `Types.ps1xml` file to the current session. The command uses the **PrependData** parameter to place the new file -in a precedence order higher than the original definitions. - -For more information about `Update-TypeData`, see -[Update-TypeData](xref:Microsoft.PowerShell.Utility.Update-TypeData). +in a precedence order higher than the original definitions. For more +information about `Update-TypeData`, see [Update-TypeData][01]. ```powershell Update-TypeData -PrependPath $PSHOME\MyTypes.ps1xml @@ -235,9 +230,8 @@ Get-ChildItem $PSHOME\pwsh.exe | Select-Object Age ## The XML in Types.ps1xml files -The full schema definition can be found in -[Types.xsd](https://github.com/PowerShell/PowerShell/blob/master/src/Schemas/Types.xsd) -in the PowerShell source code repository on GitHub. +The full schema definition can be found in [Types.xsd][04] in the PowerShell +source code repository on GitHub. The `` tag encloses all of the types that are defined in the file. There should be only one `` tag. @@ -518,7 +512,7 @@ objects. ``` For more information, see the -[Windows PowerShell Software Development Kit (SDK)](/powershell/scripting/developer/windows-powershell). +[Windows PowerShell Software Development Kit (SDK)][05]. ## Update-TypeData @@ -546,15 +540,27 @@ are added by running the `Update-TypeData` cmdlet cannot use method syntax. ## Signing a Types.ps1xml file To protect users of your `Types.ps1xml` file, you can sign the file using a -digital signature. For more information, see -[about_Signing](about_Signing.md). +digital signature. For more information, see [about_Signing][06]. ## See also -- [about_Signing](about_Signing.md) -- [Copy-Item](xref:Microsoft.PowerShell.Management.Copy-Item) -- [Copy-ItemProperty](xref:Microsoft.PowerShell.Management.Copy-ItemProperty) -- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) -- [Get-TypeData](xref:Microsoft.PowerShell.Utility.Get-TypeData) -- [Remove-TypeData](xref:Microsoft.PowerShell.Utility.Remove-TypeData) -- [Update-TypeData](xref:Microsoft.PowerShell.Utility.Update-TypeData) +- [about_Signing][06] +- [Copy-Item][07] +- [Copy-ItemProperty][08] +- [Get-Member][09] +- [Get-TypeData][10] +- [Remove-TypeData][11] +- [Update-TypeData][01] + + +[01]: xref:Microsoft.PowerShell.Utility.Update-TypeData +[02]: /dotnet/api/system.datetime +[03]: xref:Microsoft.PowerShell.Utility.Add-Member +[04]: https://github.com/PowerShell/PowerShell/blob/master/src/Schemas/Types.xsd +[05]: /powershell/scripting/developer/windows-powershell +[06]: about_Signing.md +[07]: xref:Microsoft.PowerShell.Management.Copy-Item +[08]: xref:Microsoft.PowerShell.Management.Copy-ItemProperty +[09]: xref:Microsoft.PowerShell.Utility.Get-Member +[10]: xref:Microsoft.PowerShell.Utility.Get-TypeData +[11]: xref:Microsoft.PowerShell.Utility.Remove-TypeData diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index 18442b1ae00d..6e887b429293 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -383,8 +383,7 @@ to specify a different filesystem location, but they can't exclude the > only the policy setting under **Computer Configuration** is effective. The > policy setting under **User Configuration** is ignored. -For more information, see -[about_Group_Policy_Settings][04]. +For more information, see [about_Group_Policy_Settings][04]. ## How to update help for non-standard modules diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Update_Notifications.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Update_Notifications.md index 9c45392fb18e..63d0a2be2709 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Update_Notifications.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Update_Notifications.md @@ -52,9 +52,9 @@ information about setting environment variables, see PowerShell uses the following endpoints for determining the latest version available for each channel: -- `LTS`: -- `Stable`: -- `Preview`: +- `LTS`: [https://aka.ms/pwsh-buildinfo-lts][02] +- `Stable`: [https://aka.ms/pwsh-buildinfo-stable][03] +- `Preview`: [https://aka.ms/pwsh-buildinfo-preview][04] The update notification doesn't provide any way to automatically update PowerShell. In the future, there may be more instructions or capabilities to @@ -63,3 +63,6 @@ mechanism you used to install PowerShell to update it. [01]: ../about/about_Environment_Variables.md +[02]: https://aka.ms/pwsh-buildinfo-lts +[03]: https://aka.ms/pwsh-buildinfo-stable +[04]: https://aka.ms/pwsh-buildinfo-preview diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Variable_Provider.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Variable_Provider.md index fdce7bb3d82e..a33e0164500d 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Variable_Provider.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Variable_Provider.md @@ -39,31 +39,31 @@ objects. The variables have no child items. The **Variable** provider supports the following cmdlets, which are covered in this article. -- [Get-Location](xref:Microsoft.PowerShell.Management.Get-Location) -- [Set-Location](xref:Microsoft.PowerShell.Management.Set-Location) -- [Get-Item](xref:Microsoft.PowerShell.Management.Get-Item) -- [New-Item](xref:Microsoft.PowerShell.Management.New-Item) -- [Remove-Item](xref:Microsoft.PowerShell.Management.Remove-Item) -- [Clear-Item](xref:Microsoft.PowerShell.Management.Clear-Item) +- [Get-Location][01] +- [Set-Location][02] +- [Get-Item][03] +- [New-Item][04] +- [Remove-Item][05] +- [Clear-Item][06] PowerShell also includes a set of cmdlets designed especially to view and to change variables. When you use **Variable** cmdlets, you do not need to specify the `Variable:` drive in the name. This article does not cover working with **Variable** cmdlets. -- [Get-Variable](xref:Microsoft.PowerShell.Utility.Get-Variable) -- [New-Variable](xref:Microsoft.PowerShell.Utility.New-Variable) -- [Set-Variable](xref:Microsoft.PowerShell.Utility.Set-Variable) -- [Remove-Variable](xref:Microsoft.PowerShell.Utility.Remove-Variable) -- [Clear-Variable](xref:Microsoft.PowerShell.Utility.Clear-Variable) +- [Get-Variable][07] +- [New-Variable][08] +- [Set-Variable][09] +- [Remove-Variable][10] +- [Clear-Variable][11] > [!NOTE] > You can also use the PowerShell expression parser to create, view, and change -> the values of variables without using the cmdlets. When working with variables -> directly, use a dollar sign (`$`) to identify the name as a variable and the -> assignment operator (`=`)to establish and change its value. For example, -> `$p = Get-Process` creates the `p` variable and stores the results of a -> `Get-Process` command in it. +> the values of variables without using the cmdlets. When working with +> variables directly, use a dollar sign (`$`) to identify the name as a +> variable and the assignment operator (`=`)to establish and change its value. +> For example, `$p = Get-Process` creates the `p` variable and stores the +> results of a `Get-Process` command in it. ## Types exposed by this provider @@ -109,9 +109,8 @@ drive. To reference a variable from another location, use the drive name > [!NOTE] > PowerShell uses aliases to allow you a familiar way to work with provider > paths. Commands such as `dir` and `ls` are now aliases for -> [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem), -> `cd` is an alias for [Set-Location](xref:Microsoft.PowerShell.Management.Set-Location). and `pwd` is -> an alias for [Get-Location](xref:Microsoft.PowerShell.Management.Get-Location). +> [Get-ChildItem][12], `cd` is an alias for [Set-Location][13]. and `pwd` is +> an alias for [Get-Location][14]. ## Displaying the value of variables @@ -126,9 +125,9 @@ Get-ChildItem -Path Variable: ### Get a variable using its provider path -This command retrieves a variables value using its provider path prefixed by the -dollar sign (`$`). This has the same effect as prefixing the variables name with -the dollar sign (`$`). +This command retrieves a variables value using its provider path prefixed by +the dollar sign (`$`). This has the same effect as prefixing the variables name +with the dollar sign (`$`). ```powershell $variable:home @@ -145,8 +144,7 @@ Get-ChildItem -Path Variable:max* ### Get the value of the ? variable -This command uses the `-LiteralPath` parameter of -[Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) to get +This command uses the `-LiteralPath` parameter of [Get-ChildItem][12] to get the value of the `?` variable from within the `Variable:` drive. The `?` is a wildcard in paths, but `Get-ChildItem` does not attempt to resolve any wildcards in the values of the `-LiteralPath` parameter. @@ -162,8 +160,8 @@ This command gets the variables that have the values of `ReadOnly` or ```powershell Get-ChildItem -Path Variable: | Where-Object { - $_.options -Match "Constant" ` - -or $_.options -Match "ReadOnly" + $_.options -match "Constant" ` + -or $_.options -match "ReadOnly" } | Format-List -Property name, value, options ``` @@ -267,8 +265,8 @@ Beginning in Windows PowerShell 3.0, you can get customized help topics for provider cmdlets that explain how those cmdlets behave in a file system drive. To get the help topics that are customized for the file system drive, run a -[Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) command in a file system drive or use the `-Path` -parameter of [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) to specify a file system drive. +[Get-Help][15] command in a file system drive or use the `-Path` parameter of +[Get-Help][15] to specify a file system drive. ```powershell Get-Help Get-ChildItem @@ -280,6 +278,26 @@ Get-Help Get-ChildItem -Path variable: ## See also -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_Providers](about_Providers.md) -- [about_Variables](about_Variables.md) +- [about_Automatic_Variables][16] +- [about_Providers][17] +- [about_Variables][18] + + +[01]: xref:Microsoft.PowerShell.Management.Get-Location +[02]: xref:Microsoft.PowerShell.Management.Set-Location +[03]: xref:Microsoft.PowerShell.Management.Get-Item +[04]: xref:Microsoft.PowerShell.Management.New-Item +[05]: xref:Microsoft.PowerShell.Management.Remove-Item +[06]: xref:Microsoft.PowerShell.Management.Clear-Item +[07]: xref:Microsoft.PowerShell.Utility.Get-Variable +[08]: xref:Microsoft.PowerShell.Utility.New-Variable +[09]: xref:Microsoft.PowerShell.Utility.Set-Variable +[10]: xref:Microsoft.PowerShell.Utility.Remove-Variable +[11]: xref:Microsoft.PowerShell.Utility.Clear-Variable +[12]: xref:Microsoft.PowerShell.Management.Get-ChildItem +[13]: xref:Microsoft.PowerShell.Management.Set-Location +[14]: xref:Microsoft.PowerShell.Management.Get-Location +[15]: xref:Microsoft.PowerShell.Core.Get-Help +[16]: about_Automatic_Variables.md +[17]: about_Providers.md +[18]: about_Variables.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Variables.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Variables.md index c5d05880cfdf..a44b8be3c4de 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Variables.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Variables.md @@ -515,7 +515,7 @@ Get-Help [01]: #variable-names-that-include-special-characters [02]: about_Alias_Provider.md -[03]: about_assignment_operators.md#assigning-multiple-variables +[03]: about_Assignment_Operators.md#assigning-multiple-variables [04]: about_Automatic_Variables.md [05]: about_Environment_Provider.md [06]: about_Environment_Variables.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_While.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_While.md index add8abc921dd..7736c927775f 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_While.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_While.md @@ -29,11 +29,11 @@ The following shows the While statement syntax: while (){} ``` -When you run a `while` statement, PowerShell evaluates the `` section -of the statement before entering the `` section. The condition -portion of the statement resolves to either true or false. As long as the -condition remains true, PowerShell reruns the `` section. For -more information about how booleans are evaluated, see +When you run a `while` statement, PowerShell evaluates the `` +section of the statement before entering the `` section. The +condition portion of the statement resolves to either true or false. As long as +the condition remains true, PowerShell reruns the `` section. +For more information about how booleans are evaluated, see [about_Booleans](about_Booleans.md). The `` section of the statement contains one or more commands @@ -41,8 +41,8 @@ that are run each time the loop is entered or repeated. The `` can contain any valid PowerShell statements, including the `break` and `continue` keywords. -For example, the following `while` statement displays the numbers 1 through 3 if -the `$val` variable has not been created or if the `$val` variable has been +For example, the following `while` statement displays the numbers 1 through 3 +if the `$val` variable has not been created or if the `$val` variable has been created and initialized to 0. ```powershell @@ -65,8 +65,8 @@ can enter it in the following way: while($val -ne 3){$val++; Write-Host $val} ``` -Notice that the semicolon separates the first command that adds 1 to `$val` from -the second command that writes the value of `$val` to the console. +Notice that the semicolon separates the first command that adds 1 to `$val` +from the second command that writes the value of `$val` to the console. ## See also diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Wildcards.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Wildcards.md index 161e52888acc..1960aaf354a2 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Wildcards.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Wildcards.md @@ -82,7 +82,7 @@ following command gets services in which the **ServiceType** property value includes **Interactive**. ```powershell -Get-Service | Where-Object {$_.ServiceType -Like "*Interactive*"} +Get-Service | Where-Object {$_.ServiceType -like "*Interactive*"} ``` In the following example, the `If` statement includes a condition that uses @@ -106,7 +106,7 @@ foreach ($point in $p) { - [about_Script_Blocks][04] -[01]: ./about_Regular_Expressions.md +[01]: about_Regular_Expressions.md [02]: about_If.md [03]: about_Language_Keywords.md [04]: about_Script_Blocks.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_Compatibility.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_Compatibility.md index 44310d621ce6..8c4062911fde 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_Compatibility.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_Compatibility.md @@ -163,6 +163,6 @@ from the session or close the session. [01]: about_Modules.md -[02]: about_powershell_config.md +[02]: about_Powershell_Config.md [03]: https://aka.ms/PSModuleCompat [04]: xref:Microsoft.PowerShell.Core.Import-Module