From 825399617bd65ac2ba4102bc18004c990f02dd34 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 21 Jun 2019 05:22:10 -0700 Subject: [PATCH] Sync docs changes into the embedded help for pwsh (#9952) --- .../resources/ManagedEntranceStrings.resx | 237 ++++++++++++------ 1 file changed, 161 insertions(+), 76 deletions(-) diff --git a/src/Microsoft.PowerShell.ConsoleHost/resources/ManagedEntranceStrings.resx b/src/Microsoft.PowerShell.ConsoleHost/resources/ManagedEntranceStrings.resx index 95f1717c85..fe14c5e740 100644 --- a/src/Microsoft.PowerShell.ConsoleHost/resources/ManagedEntranceStrings.resx +++ b/src/Microsoft.PowerShell.ConsoleHost/resources/ManagedEntranceStrings.resx @@ -132,8 +132,8 @@ Type 'help' to get help. [-EncodedCommand <Base64EncodedCommand>] [-ExecutionPolicy <ExecutionPolicy>] [-InputFormat {Text | XML}] [-Interactive] [-LoadProfile] [-NoExit] [-NoLogo] [-NonInteractive] [-NoProfile] - [-OutputFormat {Text | XML}] [-Version] [-WindowStyle <style>] - [-WorkingDirectory <directoryPath>] + [-OutputFormat {Text | XML}] [-SettingsFile <filePath>] [-Version] + [-WindowStyle <style>] [-WorkingDirectory <directoryPath>] pwsh[.exe] -h | -Help | -? | /? @@ -144,133 +144,218 @@ All parameters are case-insensitive. +-File | -f + + If the value of File is "-", the command text is read from standard input. + Running "pwsh -File -" without redirected standard input starts a regular + session. This is the same as not specifying the File parameter at all. + + This is the default parameter if no parameters are present but values are + present in the command line. The specified script runs in the local scope + ("dot-sourced"), so that the functions and variables that the script + creates are available in the current session. Enter the script file path + and any parameters. File must be the last parameter in the command, because + all characters typed after the File parameter name are interpreted as the + script file path followed by the script parameters. + + Typically, the switch parameters of a script are either included or + omitted. For example, the following command uses the All parameter of the + Get-Script.ps1 script file: "-File .\Get-Script.ps1 -All" + + In rare cases, you might need to provide a Boolean value for a switch + parameter. To provide a Boolean value for a switch parameter in the value + of the File parameter, enclose the parameter name and value in curly + braces, such as the following: "-File .\Get-Script.ps1 {-All:$False}." + + Parameters passed to the script are passed as literal strings, after + interpretation by the current shell. For example, if you are in cmd.exe and + want to pass an environment variable value, you would use the cmd.exe + syntax: "pwsh -File .\test.ps1 -TestParam %windir%" + + In contrast, running "pwsh -File .\test.ps1 -TestParam $env:windir" in + cmd.exe results in the script receiving the literal string "$env:windir" + because it has no special meaning to the current cmd.exe shell. The + "$env:windir" style of environment variable reference can be used inside a + Command parameter, since there it will be interpreted as PowerShell code. + -Command | -c - Executes the specified commands (and any parameters) as though they were typed - at the PowerShell command prompt, and then exits, unless NoExit is specified. - The value of Command can be "-", a string. or a script block. - If the value of Command is "-", the command text is read from standard input. + Executes the specified commands (and any parameters) as though they were + typed at the PowerShell command prompt, and then exits, unless the NoExit + parameter is specified. - If the value of Command is a script block, the script block must be enclosed - in braces ({}). You can specify a script block only when running 'pwsh' - in a PowerShell session. The results of the script block are returned to the - parent shell as deserialized XML objects, not live objects. + The value of Command can be "-", a script block, or a string. If the value + of Command is "-", the command text is read from standard input. - If the value of Command is a string, Command must be the last parameter in the command, - because any characters typed after the command are interpreted as the command arguments. + The Command parameter only accepts a script block for execution when it can + recognize the value passed to Command as a ScriptBlock type. This is only + possible when running pwsh from another PowerShell host. The ScriptBlock + type may be contained in an existing variable, returned from an expression, + or parsed by the PowerShell host as a literal script block enclosed in + curly braces "{}", before being passed to pwsh. - To write a string that runs a PowerShell command, use the format: - "& {<command>}" - where the quotation marks indicate a string and the invoke operator (&) - causes the command to be executed. - Example: - pwsh -Command {Get-WinEvent -LogName security} - pwsh -command "& {Get-WinEvent -LogName security}" + pwsh -Command {Get-WinEvent -LogName security} + + In cmd.exe, there is no such thing as a script block (or ScriptBlock type), + so the value passed to Command will always be a string. You can write a + script block inside the string, but instead of being executed it will + behave exactly as though you typed it at a typical PowerShell prompt, + printing the contents of the script block back out to you. + + A string passed to Command will still be executed as PowerShell, so the + 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 "&" can be used: + + pwsh -Command "& {Get-WinEvent -LogName security}" + + If the value of Command is a string, Command must be the last parameter for + pwsh, because all arguments following it are interpreted as part of the + command to execute. + + The results are returned to the parent shell as deserialized XML objects, + not live objects. + + If the value of Command is "-", the command text is read from standard + input. You must redirect standard input when using the Command parameter + with standard input. For example: + + + @' + "in" + + "hi" | + % { "$_ there" } + + "out" + '@ | powershell -NoProfile -Command - + + This example produces the following output: + + """Output + in + hi there + out -ConfigurationName | -config - Specifies a configuration endpoint in which PowerShell is run. - This can be any endpoint registered on the local machine including the default PowerShell - remoting endpoints or a custom endpoint having specific user role capabilities. - Example: pwsh -ConfigurationName AdminRoles + Specifies a configuration endpoint in which PowerShell is run. This can be + any endpoint registered on the local machine including the default + PowerShell remoting endpoints or a custom endpoint having specific user + role capabilities. + + Example: "pwsh -ConfigurationName AdminRoles" -CustomPipeName - Specifies the name to use for an additional IPC server (named pipe) used for debugging - and other cross-process communication. This offers a predictable mechanism for connecting - to other PowerShell instances. Typically used with the CustomPipeName parameter on Enter-PSHostProcess. - Example: + Specifies the name to use for an additional IPC server (named pipe) used + for debugging and other cross-process communication. This offers a + predictable mechanism for connecting to other PowerShell instances. + Typically used with the CustomPipeName parameter on "Enter-PSHostProcess". + + For example: + + # PowerShell instance 1 pwsh -CustomPipeName mydebugpipe # PowerShell instance 2 Enter-PSHostProcess -CustomPipeName mydebugpipe -EncodedCommand | -e | -ec - Accepts a base64 encoded string version of a command. Use this parameter to submit - commands to PowerShell that require complex quotation marks or curly braces. - Example: - $command = 'dir "c:\program files" ' - $bytes = [System.Text.Encoding]::Unicode.GetBytes($command) - $encodedCommand = [Convert]::ToBase64String($bytes) - pwsh -encodedcommand $encodedCommand + Accepts a base64-encoded string version of a command. Use this parameter to + submit commands to PowerShell that require complex quotation marks or curly + braces. The string must be formatted using UTF-16 character encoding. + + For example: + + + $command = 'dir "c:\program files" ' + $bytes = [System.Text.Encoding]::Unicode.GetBytes($command) + $encodedCommand = [Convert]::ToBase64String($bytes) + pwsh -encodedcommand $encodedCommand -ExecutionPolicy | -ex | -ep - Sets the default execution policy for the current session and saves it - in the $env:PSExecutionPolicyPreference environment variable. - This parameter does not change the PowerShell execution policy - that is set in the registry. - Example: pwsh -ExecutionPolicy RemoteSigned - --File | -f - Default parameter if no parameters is present but any values is present in the command line. - Runs the specified script in the local scope ("dot-sourced"), so that the functions - and variables that the script creates are available in the current session. - Enter the script file path and any parameters. File must be the last parameter - in the command, because all characters typed after the File parameter name are interpreted - as the script file path followed by the script parameters. - - Example: pwsh HelloWorld.ps1 - --Help | -h | -? | /? - Shows this help message. + Sets the default execution policy for the current session and saves it in + the "$env:PSExecutionPolicyPreference" environment variable. This parameter + does not change the PowerShell execution policy that is set in the + registry. -InputFormat | -in | -if - Describes the format of data sent to PowerShell. - Valid values are "Text" (text strings) or "XML" (serialized CLIXML format). + + Describes the format of data sent to PowerShell. Valid values are "Text" + (text strings) or "XML" (serialized CLIXML format). -Interactive | -i - Present an interactive prompt to the user. Inverse for NonInteractive parameter. + + Present an interactive prompt to the user. Inverse for NonInteractive + parameter. -LoadProfile | -l - Load the PowerShell profiles. This is the default behavior even if this is not specified. + + Load the PowerShell profiles. This is the default behavior even if this is + not specified. -NoExit | -noe + Does not exit after running startup commands. - Example: pwsh -NoExit -Command Get-Date + Example: "pwsh -NoExit -Command Get-Date" -NoLogo | -nol - Hides the copyright banner at startup. + +Hides the copyright banner at startup. -NonInteractive | -noni - Does not present an interactive prompt to the user. Inverse for Interactive parameter. + + Does not present an interactive prompt to the user. -NoProfile | -nop - Does not load the PowerShell profiles. + + Does not load the PowerShell profile. -OutputFormat | -o | -of - Determines how output from PowerShell is formatted. Valid values - are "Text" (text strings) or "XML" (serialized CLIXML format). - Default is "Text". - Example: pwsh -o XML -c Get-Date + Determines how output from PowerShell is formatted. Valid values are "Text" + (text strings) or "XML" (serialized CLIXML format). + + Example: "pwsh -o XML -c Get-Date" -SettingsFile | -settings - Overrides the system-wide powershell.config.json settings file for the session. - By default, system-wide settings are read from the powershell.config.json - in the $PSHOME directory. - Note that these settings are not used by the endpoint specified - by the -ConfigurationName argument. + Overrides the system-wide "powershell.config.json" settings file for the + session. By default, system-wide settings are read from the + "powershell.config.json" in the "$PSHOME" directory. - Example: pwsh -SettingsFile c:\myproject\powershell.config.json + Note that these settings are not used by the endpoint specified by the + "-ConfigurationName" argument. + + Example: "pwsh -SettingsFile c:\myproject\powershell.config.json" -Version | -v - Shows the version of PowerShell and exits. Additional arguments are ignored. - Example: pwsh -v + Displays the version of PowerShell. Additional parameters are ignored. -WindowStyle | -w - Sets the window style to Normal, Minimized, Maximized or Hidden. + + Sets the window style for the session. Valid values are Normal, Minimized, + Maximized and Hidden. -WorkingDirectory | -wd - Sets the working directory at the start of PowerShell given a valid PowerShell directory path. - Executing `Set-Location -LiteralPath <path>` at startup. - Example: pwsh -WorkingDirectory ~ + Sets the initial working directory by executing + "Set-Location -LiteralPath <path>" at startup. Any valid PowerShell file + path is supported. + + To start PowerShell in your home directory, use: "pwsh -WorkingDirectory ~" + +-Help, -?, /? + + Displays help for pwsh. If you are typing a pwsh command in PowerShell, + prepend the command parameters with a hyphen (-), not a forward slash (/). + You can use either a hyphen or forward slash in Cmd.exe.