about_Pwsh

  • Artículo

Descripción breve

Explica cómo usar la interfaz ine de pwsh comandos-l. Muestra los parámetros ine del comando-ly describe la sintaxis.

Descripción larga

Para obtener información sobre las opciones de ine de comandos-lpara Windows PowerShell 5.1, consulte about_PowerShell_exe.

Sintaxis

Usage: pwsh[.exe]
    [-Login]
    [[-File] <filePath> [args]]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <string> [<CommandParameters>] } ]
    [[-CommandWithArgs <string>] [<CommandParameters>]]
    [-ConfigurationFile <filePath>]
    [-ConfigurationName <string>]
    [-CustomPipeName <string>]
    [-EncodedCommand <Base64EncodedCommand>]
    [-ExecutionPolicy <ExecutionPolicy>]
    [-InputFormat {Text | XML}]
    [-Interactive]
    [-MTA]
    [-NoExit]
    [-NoLogo]
    [-NonInteractive]
    [-NoProfile]
    [-NoProfileLoadTime]
    [-OutputFormat {Text | XML}]
    [-SettingsFile <filePath>]
    [-SSHServerMode]
    [-STA]
    [-Version]
    [-WindowStyle <style>]
    [-WorkingDirectory <directoryPath>]

pwsh[.exe] -h | -Help | -? | /?

Parámetros

Todos los parámetros distinguen mayúsculas-ide minúsculas.

-File | -f

Si el valor de File es -, el texto del comando se lee de la entrada estándar. La ejecución pwsh -File - sin la entrada estándar redirigida inicia una sesión normal. Esto es lo mismo que no especificar el File parámetro en absoluto.

Este es el parámetro predeterminado si no hay parámetros presentes, pero los valores están presentes en la línea de comandos. El script especificado se ejecuta en el ámbito local ("dot-sourced") de la nueva sesión, de modo que las funciones y variables que crea el script estén disponibles en la nueva sesión. Escriba la ruta de acceso de archivo de script y los parámetros. El archivo debe ser el último parámetro del comando, ya que todos los caracteres que se escriben después del nombre del parámetro File se interpretan como la ruta de acceso de archivo de script seguida de los parámetros de script.

Normalmente, los parámetros de modificador de un script se incluyen o se omiten. Por ejemplo, el siguiente comando usa el parámetro All del archivo de script Get-Script.ps1: -File .\Get-Script.ps1 -All

En raras ocasiones, es posible que tenga que proporcionar un valor booleano para un parámetro switch. Para proporcionar un valor booleano para un parámetro switch en el valor del parámetro File , use el parámetro seguido normalmente por dos puntos y el valor booleano, como el siguiente: -File .\Get-Script.ps1 -All:$False.

Los parámetros que se pasan al script lo hacen como cadenas literales (una vez interpretados por el shell actual). Por ejemplo, si está en cmd.exe y desea pasar un valor de variable de entorno, usaría la cmd.exe sintaxis : pwsh -File .\test.ps1 -TestParam %windir%

En cambio, la ejecución pwsh -File .\test.ps1 -TestParam $env:windir en da como cmd.exe resultado que el script reciba la cadena $env:windir literal porque no tiene ningún significado especial para el shell actual cmd.exe . El $env:windir estilo de referencia de variable de entorno se puede usar dentro de un parámetro Command , ya que se interpreta como código de PowerShell.

Del mismo modo, si desea ejecutar el mismo comando desde un script de Batch, usaría %~dp0 en lugar de o $PSScriptRoot para representar el directorio de .\ ejecución actual: pwsh -File %~dp0test.ps1 -TestParam %windir%. Si en su lugar usa .\test.ps1, PowerShell producirá un error porque no encuentra la ruta de acceso literal. .\test.ps1

Nota:

El parámetro File no puede admitir scripts mediante un parámetro que espera una matriz de valores de argumento. Esto, desafortunadamente, es una limitación de cómo un comando nativo obtiene los valores de argumento. Cuando se llama a un ejecutable nativo (como powershell o pwsh), no sabe qué hacer con una matriz, por lo que se pasa como una cadena.

Cuando el archivo de script finaliza con un exit comando, el código de salida del proceso se establece en el argumento numérico usado con el exit comando . Con la terminación normal, el código de salida siempre 0es .

Para obtener más información, consulte $LASTEXITCODE en about_Automatic_Variables.

De forma similar a -Command, cuando se produce un error de terminación de script, el código de salida se establece en 1. Sin embargo, a diferencia de , -Commandcuando la ejecución se interrumpe con Ctrl+C, el código de salida es .0

Nota:

A partir de PowerShell 7.2, el parámetro File solo acepta .ps1 archivos en Windows. Si se proporciona otro tipo de archivo, se produce un error. Este comportamiento es específico de Windows. En otras plataformas, PowerShell intenta ejecutar otros tipos de archivo.

-Command | -c

Ejecuta los comandos especificados (y los parámetros) como si se hubieran escrito en el símbolo del sistema de PowerShell y, a continuación, se cierra, a menos que se especifique el NoExit parámetro.

El valor de Command puede ser -, un bloque de script o una cadena. Si el valor de Command es -, el texto del comando se lee de la entrada estándar.

El parámetro Command solo acepta un bloque de script para su ejecución cuando puede reconocer el valor pasado a Command como un tipo ScriptBlock . Esto solo es posible cuando se ejecuta pwsh desde otro host de PowerShell. El tipo ScriptBlock puede estar contenido en una variable existente, devuelta desde una expresión o analizada por el host de PowerShell como un bloque de script literal entre llaves ({}), antes de pasarse a pwsh.

pwsh -Command {Get-WinEvent -LogName security}

En cmd.exe, no hay nada como un bloque de script (o un tipo ScriptBlock), por lo que el valor pasado a Command siempre es una cadena. Puede escribir un bloque de script dentro de la cadena, pero en lugar de ejecutarlo se comporta exactamente como si se escribe en un símbolo del sistema típico de PowerShell, imprimiendo el contenido del bloque de script de vuelta.

Una cadena pasada a Command se sigue ejecutando como código de PowerShell, por lo que las llaves del bloque de script a menudo no son necesarias en primer lugar cuando se ejecuta desde cmd.exe. Para ejecutar un bloque de script alineado definido dentro de una cadena, se puede usar el operador de llamada&:

pwsh -Command "& {Get-WinEvent -LogName security}"

Si el valor de Command es una cadena, Command debe ser el último parámetro para pwsh, ya que todos los argumentos siguientes se interpretan como parte del comando que se va a ejecutar.

Cuando se llama desde una sesión de PowerShell existente, los resultados se devuelven al shell primario como objetos XML deserializados, no objetos dinámicos. Para otros shells, los resultados se devuelven como cadenas.

Si el valor de Command es -, el texto del comando se lee de la entrada estándar. Debe redirigir la entrada estándar al usar el parámetro Command con entrada estándar. Por ejemplo:

@'
"in"

"hi" |
  % { "$_ there" }

"out"
'@ | powershell -NoProfile -Command -

Este ejemplo produce el siguiente resultado:

in
hi there
out

El código de salida del proceso viene determinado por el estado del último comando (ejecutado) dentro del bloque de script. El código de salida es 0 cuando $? es $true o 1 cuando $? es $false. Si el último comando es un programa externo o un script de PowerShell que establece explícitamente un código de salida distinto de 0 o 1, ese código de salida se convierte en 1 para el código de salida del proceso. Para conservar el código de salida específico, agregue exit $LASTEXITCODE a la cadena de comandos o al bloque de script.

Para obtener más información, consulte $LASTEXITCODE en about_Automatic_Variables.

Del mismo modo, el valor 1 se devuelve cuando se produce un error de terminación de script (ejecución de terminación del espacio de ejecución), como o throw-ErrorAction Stop, o cuando se interrumpe la ejecución con Ctrl+C.

-CommandWithArgs | -cWa

Se trata de una característica experimental agregada en la versión 7.4.

Ejecuta un comando de PowerShell con argumentos. A diferencia -Commandde , este parámetro rellena la $args variable n compilada-ique el comando puede usar.

La primera cadena es el comando . Las cadenas adicionales delimitadas por espacios en blanco son los argumentos.

Por ejemplo:

pwsh -CommandWithArgs '$args | % { "arg: $_" }' arg1 arg2

Este ejemplo produce el siguiente resultado:

arg: arg1
arg: arg2

-ConfigurationName | -config

Especifica un punto de conexión de configuración en el que se ejecuta PowerShell. Puede ser cualquier punto de conexión registrado en la máquina local, incluidos los puntos de conexión remoto de PowerShell predeterminados o un punto de conexión personalizado que tenga funcionalidades específicas de rol de usuario.

Ejemplo: pwsh -ConfigurationName AdminRoles

-ConfigurationFile

Especifica una ruta de acceso de archivo de configuración de sesión (.pssc). La configuración contenida en el archivo de configuración se aplicará a la sesión de PowerShell.

Ejemplo: pwsh -ConfigurationFile "C:\ProgramData\PowerShell\MyConfig.pssc"

-CustomPipeName

Especifica el nombre que se va a usar para un servidor IPC adicional (canalización con nombre) que se usa para la depuración y otra comunicación entre procesos. Esto ofrece un mecanismo predecible para conectarse a otras instancias de PowerShell. Normalmente se usa con el parámetro CustomPipeName en Enter-PSHostProcess.

Este parámetro se introdujo en PowerShell 6.2.

Por ejemplo:

# PowerShell instance 1
pwsh -CustomPipeName mydebugpipe
# PowerShell instance 2
Enter-PSHostProcess -CustomPipeName mydebugpipe

-EncodedCommand | -e | -ec

Acepta una versión de cadena codificada en Base64-ede un comando. Use este parámetro para enviar comandos a PowerShell que requieren comillas complejas y anidadas. La representación base64 debe ser una cadena codificada con UTF-16LE.

Por ejemplo:

$command = 'dir "c:\program files" '
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
pwsh -encodedcommand $encodedCommand

-ExecutionPolicy | -ex | -ep

Establece la directiva de ejecución predeterminada para la sesión actual y la guarda en la variable de $env:PSExecutionPolicyPreference entorno. Este parámetro no cambia las directivas de ejecución configuradas de forma persistente.

Este parámetro solo se aplica a los equipos Windows. En plataformas que no son de Windows, se omite el parámetro y el valor proporcionados.

-InputFormat | -inp | -if

Describe el formato de los datos que se envían a PowerShell. Los valores válidos son "Text" (cadenas de texto) o "XML" (formato CLIXML serializado).

-Interactive | -i

Presente una solicitud interactiva al usuario. Inversa al parámetro NonInteractive.

-Login | -l

En Linux y macOS, inicia PowerShell como un shell de inicio de sesión con /bin/sh para ejecutar perfiles de inicio de sesión como /etc/profile y ~/.profile. En Windows, este modificador no hace nada.

Importante

Este parámetro debe comenzar primero para iniciar PowerShell como shell de inicio de sesión. Este parámetro se omite si se pasa en otra posición.

Para configurar pwsh como shell de inicio de sesión en sistemas operativos UNIX-like:

  • Compruebe que la ruta de acceso absoluta completa a pwsh aparece en /etc/shells

    • Esta ruta de acceso suele ser algo parecido /usr/bin/pwsh a en Linux o /usr/local/bin/pwsh en macOS.
    • Con algunos métodos de instalación, esta entrada se agregará automáticamente en el momento de la instalación.
    • Si pwsh no está presente en /etc/shells, use un editor para anexar la ruta de acceso a pwsh en la última línea. Esto requiere privilegios elevados para editar.

  • Use la utilidad chsh para establecer el shell pwshdel usuario actual en :

    chsh -s /usr/bin/pwsh

Advertencia

La configuración pwsh como shell de inicio de sesión no se admite actualmente en Subsistema de Windows para Linux (WSL) e intentar establecer pwsh como shell de inicio de sesión puede provocar que no se pueda iniciar WSL de forma interactiva.

-MTA

Inicie PowerShell mediante un apartamento multiproceso. Este modificador solo está disponible en Windows. El uso de este parámetro en plataformas que no son windows produce un error.

-NoExit | -noe

No se cierra después de ejecutar comandos de inicio.

Ejemplo: pwsh -NoExit -Command Get-Date

-NoLogo | -nol

Oculta el banner al iniciar sesiones interactivas.

-NonInteractive | -noni

Este modificador se usa para crear sesiones que no deben requerir la entrada del usuario. Esto es útil para los scripts que se ejecutan en tareas programadas o canalizaciones de CI/CD. Cualquier intento de usar características interactivas, como Read-Host o avisos de confirmación, da como resultado errores de terminación de instrucciones en lugar de colgar.

-NoProfile | -nop

No carga los perfiles de PowerShell.

-NoProfileLoadTime

Oculta el texto del tiempo de carga del perfil de PowerShell que se muestra al iniciarse cuando el tiempo de carga supera los 500 milisegundos.

-OutputFormat | -o | -of

Determina cómo se formatea la salida de PowerShell. Los valores válidos son "Text" (cadenas de texto) o "XML" (formato CLIXML serializado).

Ejemplo: pwsh -o XML -c Get-Date

Cuando se llama dentro de una sesión de PowerShell, se obtienen objetos deserializados como resultados en lugar de cadenas sin formato. Cuando se llama desde otros shells, la salida tiene el formato de datos de cadena como texto CLIXML.

-SettingsFile | -settings

Invalida el archivo de configuración del ide powershell.config.json del sistema-wpara la sesión. De forma predeterminada, la configuración del ide del sistema-wse lee desde en powershell.config.json el $PSHOME directorio .

Tenga en cuenta que el punto de conexión especificado por el -ConfigurationName argumento no usa esta configuración.

Ejemplo: pwsh -SettingsFile c:\myproject\powershell.config.json

-SSHServerMode | -sshs

Se usa en sshd_config para ejecutar PowerShell como subsistema SSH. No está pensado ni es compatible con ningún otro uso.

-STA

Inicie PowerShell mediante un apartamento de un solo subproceso. Este es el valor predeterminado. Este modificador solo está disponible en la plataforma Windows. El uso de este parámetro en plataformas que no son windows produce un error.

-Version | -v

Muestra la versión de PowerShell. Se omiten parámetros adicionales.

-WindowStyle | -w

Establece el estilo de ventana de la sesión. Los valores válidos son Normal, Minimizada, Maximizada y Oculta. Este parámetro solo se aplica a Windows. El uso de este parámetro en plataformas que no son windows produce un error.

-WorkingDirectory | -wd | -wo

Establece el directorio de trabajo inicial ejecutando en el inicio. Se admite cualquier ruta de acceso de archivo de PowerShell válida.

Para iniciar PowerShell en el directorio principal, use: pwsh -WorkingDirectory ~

-Help, -?, /?

Muestra ayuda para pwsh. Si está escribiendo un comando pwsh en PowerShell, anteponga los parámetros de comando con un guión (-), no una barra diagonal (/).