about_PowerShell_exe

Descripción breve

Explica cómo usar la interfaz de powershell.exe la línea de comandos. Muestra los parámetros de la línea de comandos y describe la sintaxis.

Descripción larga

Para obtener información sobre las opciones de línea de comandos para PowerShell 7, consulte about_Pwsh.

SINTAXIS

PowerShell[.exe]
    [-PSConsoleFile <file> | -Version <version>]
    [-NoLogo]
    [-NoExit]
    [-Sta]
    [-Mta]
    [-NoProfile]
    [-NonInteractive]
    [-InputFormat {Text | XML}]
    [-OutputFormat {Text | XML}]
    [-WindowStyle <style>]
    [-EncodedArguments <Base64EncodedArguments>]
    [-EncodedCommand <Base64EncodedCommand>]
    [-ConfigurationName <string>]
    [-File - | <filePath> <args>]
    [-ExecutionPolicy <ExecutionPolicy>]
    [-Command - | { <script-block> [-args <arg-array>] }
                | { <string> [<CommandParameters>] } ]

PowerShell[.exe] -Help | -? | /?

Parámetros

Todos los parámetros no distinguen mayúsculas de minúsculas.

-File - | <filePath><args>

El valor de File puede ser - o una ruta de acceso a archivos y parámetros opcionales. Si el valor de File es -, los comandos se leen de la entrada estándar.

Si el valor de File es una ruta de acceso a archivos, el script 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 esa 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. Todos los valores que se escriben después del parámetro File se interpretan como la ruta de acceso de archivo de script y los parámetros pasados a ese script. Por ejemplo: -File .\Get-Script.ps1 -Domain Central

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 Get-Script.ps1 archivo de script: -File .\Get-Script.ps1 -All

En raras ocasiones, es posible que tenga que proporcionar un valor booleano para un parámetro. No es posible pasar un valor booleano explícito para un parámetro switch al ejecutar un script de esta manera. Esta limitación se quitó en PowerShell 6 (pwsh.exe).

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 : powershell.exe -File .\test.ps1 -TestParam %windir%

En cambio, la ejecución powershell.exe -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 usa .\test.ps1 en su lugar, PowerShell produce 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.

Si el valor de File es -, los comandos se leen de la entrada estándar. La ejecución powershell -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. Al leer desde la entrada estándar, las instrucciones de entrada se ejecutan una instrucción a la vez como si estuvieran tipadas en el símbolo del sistema de PowerShell. Si una instrucción no se analiza correctamente, la instrucción no se ejecuta. El código de salida del proceso viene determinado por el estado del último comando (ejecutado). Con la ejecución correcta, el código de salida siempre 0es . 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 .

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 Para obtener más información, consulte $LASTEXITCODE en about_Automatic_Variables.

-Command

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 powershell.exe 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 powershell.exe.

powershell -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 insertado definido dentro de una cadena, se puede usar el operador & de llamada:

powershell.exe -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 -, los comandos se leen 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

Al leer desde la entrada estándar, la entrada se analiza y ejecuta una instrucción a la vez, como si estuvieran tipadas en el símbolo del sistema de PowerShell. Si el código de entrada no se analiza correctamente, la instrucción no se ejecuta. A menos que use el -NoExit parámetro , la sesión de PowerShell se cierra cuando no hay más entradas para leer desde la entrada estándar.

El código de salida del proceso viene determinado por el estado del último comando (ejecutado) dentro de la entrada. 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. 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.

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.

-ConfigurationName <string>

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.

-EncodedArguments Base64EncodedArguments <>

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

-EncodedCommand <Base64EncodedCommand>

Acepta una versión de cadena con codificación Base 64 de un comando. Use este parámetro para enviar comandos a PowerShell que requieran comillas complejas o llaves. La cadena debe tener formato mediante codificación de caracteres UTF-16LE.

-ExecutionPolicy <ExecutionPolicy>

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 la directiva de ejecución de PowerShell establecida en el Registro. Para obtener más información sobre las directivas de ejecución de PowerShell, incluida una lista de los valores válidos, vea about_Execution_Policies.

-InputFormat {Text | XML}

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).

-Mta

Inicia PowerShell con un contenedor multiproceso. Este parámetro se incorporó en PowerShell 3.0. En PowerShell 2.0, el valor predeterminado es el contenedor multiproceso (MTA). En PowerShell 3.0, el valor predeterminado es el contenedor uniproceso (STA).

-NoExit

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

-NonInteractive

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.

-NoLogo

Oculta la pancarta de copyright al inicio.

-NoProfile

No carga el perfil de PowerShell.

-OutputFormat {Text | XML}

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

-PSConsoleFile <FilePath>

Carga el archivo de consola de PowerShell especificado. Escriba la ruta de acceso y el nombre del archivo de consola. Para crear un archivo de consola, use el cmdlet Export-Console en PowerShell.

-Sta

Inicia PowerShell con un contenedor uniproceso. En Windows PowerShell 2.0, el valor predeterminado es el contenedor multiproceso (MTA). En Windows PowerShell 3.0, el valor predeterminado es el contenedor uniproceso (STA).

-Versión <de PowerShell>

Inicia la versión especificada de PowerShell. Los valores válidos son 2.0 y 3.0. La versión que especifique debe estar instalada en el sistema. Si Windows PowerShell 3.0 está instalado en el equipo, "3.0" es la versión predeterminada. De lo contrario, "2.0" es la versión predeterminada. Para obtener más información, consulte Instalación de PowerShell.

-Estilo de ventana WindowStyle <>

Establece el estilo de ventana de la sesión. Los valores válidos son Normal, Minimized, Maximized y Hidden.

-Help, -?, /?

Muestra ayuda para PowerShell.exe. Si escribe un PowerShell.exe comando en una sesión de PowerShell, anteponga los parámetros de comando con un guión (-), no una barra diagonal (/). Puede usar un guión o una barra diagonal en cmd.exe.

COMENTARIOS

Nota de solución de problemas: En PowerShell 2.0, al iniciar algunos programas desde la consola de PowerShell se produce un error con un LastExitCode de 0xc0000142.

EJEMPLOS

# Create a new PowerShell session and load a saved console file
PowerShell -PSConsoleFile sqlsnapin.psc1

# Create a new PowerShell V2 session with text input, XML output, and no logo
PowerShell -Version 2.0 -NoLogo -InputFormat text -OutputFormat XML

# Execute a PowerShell Command in a session
PowerShell -Command "Get-EventLog -LogName security"

# Run a script block in a session
PowerShell -Command {Get-EventLog -LogName security}

# An alternate way to run a command in a new session
PowerShell -Command "& {Get-EventLog -LogName security}"

# To use the -EncodedCommand parameter:
$command = "dir 'c:\program files' "
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
powershell.exe -encodedCommand $encodedCommand