PowerShell@2: tarea de PowerShell v2

Use esta tarea para ejecutar un script de PowerShell en Linux, macOS o Windows.

Nota

De forma predeterminada, PowerShell v2 usa PowerShell Core para agentes de Linux y Windows PowerShell para agentes de Windows. Para usar la versión más reciente de PowerShell en agentes de Windows, establezca el pwsh parámetro trueen . PowerShell Core se usará en su lugar.

Syntax

# PowerShell v2
# Run a PowerShell script on Linux, macOS, or Windows.
- task: PowerShell@2
  inputs:
    #targetType: 'filePath' # 'filePath' | 'inline'. Type. Default: filePath.
    filePath: # string. Required when targetType = filePath. Script Path. 
    #arguments: # string. Optional. Use when targetType = filePath. Arguments. 
    #script: # string. Required when targetType = inline. Script. 
  # Preference Variables
    #errorActionPreference: 'stop' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. ErrorActionPreference. Default: stop.
    #warningPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. WarningPreference. Default: default.
    #informationPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. InformationPreference. Default: default.
    #verbosePreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. VerbosePreference. Default: default.
    #debugPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. DebugPreference. Default: default.
    #progressPreference: 'silentlyContinue' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. ProgressPreference. Default: silentlyContinue.
  # Advanced
    #failOnStderr: false # boolean. Fail on Standard Error. Default: false.
    #showWarnings: false # boolean. Show warnings as Azure DevOps warnings. Default: false.
    #ignoreLASTEXITCODE: false # boolean. Ignore $LASTEXITCODE. Default: false.
    #pwsh: false # boolean. Use PowerShell Core. Default: false.
    #workingDirectory: # string. Working Directory. 
    #runScriptInSeparateScope: false # boolean. Run script in the separate scope. Default: false.

Entradas

targetType - Tipo
string. Valores permitidos: filePath (Ruta de acceso del archivo), inline. Valor predeterminado: filePath.

Especifica el tipo de script para que se ejecute la tarea: un script insertado o una ruta de acceso a un .ps1 archivo.

filePath - Ruta de acceso del script
string. Necesario cuando targetType = filePath.

Especifica la ruta de acceso del script que se va a ejecutar. Debe ser una ruta de acceso completa o relativa a $(System.DefaultWorkingDirectory).

arguments - Argumentos
string. Opcional. Use cuando targetType = filePath.

Especifica los argumentos pasados al script de PowerShell. Los argumentos pueden ser parámetros ordinales o parámetros con nombre. Por ejemplo, -Name someName -Path -Value "Some long string value".

arguments no se usa cuando targetType se establece en inline.

script - Guión
string. Necesario cuando targetType = inline. Valor predeterminado: # Write your PowerShell commands here.\n\nWrite-Host "Hello World".

Especifica el contenido del script. La longitud máxima de script insertada admitida es de 20000 caracteres. Use un script de un archivo si desea usar un script más largo.

errorActionPreference - ErrorActionPreference
string. Valores permitidos: default, stop, continue, silentlyContinue. Valor predeterminado: stop.

Antepone la línea $ErrorActionPreference = 'VALUE' en la parte superior del script.

warningPreference - AdvertenciaPreferencia
string. Valores permitidos: default, stop, continue, silentlyContinue. Valor predeterminado: default.

Cuando no se establece en Default, antepone la línea $WarningPreference = 'VALUE' en la parte superior del script.

informationPreference - InformationPreference
string. Valores permitidos: default, stop, continue, silentlyContinue. Valor predeterminado: default.

Cuando no se establece en Default, antepone la línea $InformationPreference = 'VALUE' en la parte superior del script.

verbosePreference - VerbosePreference
string. Valores permitidos: default, stop, continue, silentlyContinue. Valor predeterminado: default.

Cuando no se establece en Default, antepone la línea $VerbosePreference = 'VALUE' en la parte superior del script.

debugPreference - DepurarPreferencia
string. Valores permitidos: default, stop, continue, silentlyContinue. Valor predeterminado: default.

Cuando no se establece en Default, antepone la línea $DebugPreference = 'VALUE' en la parte superior del script.

progressPreference - ProgressPreference
string. Valores permitidos: default, stop, continue, silentlyContinue. Valor predeterminado: silentlyContinue.

Cuando no se establece en Default, antepone la línea $ProgressPreference = 'VALUE' en la parte superior del script.

failOnStderr - Error en el error estándar
boolean. Valor predeterminado: false.

Si el valor de este valor booleano es true, se produce un error en la tarea si se escriben errores en la canalización de errores o si se escriben datos en el flujo de error estándar. De lo contrario, la tarea se basa en el código de salida para determinar el error.

showWarnings - Mostrar advertencias como advertencias de Azure DevOps
boolean. Valor predeterminado: false.

Si el valor se establece trueen y el script escribe advertencias, las advertencias aparecerán como advertencias en los registros de canalización.

ignoreLASTEXITCODE - Omitir $LASTEXITCODE
boolean. Valor predeterminado: false.

Si el valor se establece falseen , la línea if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } se anexa al final del script. Esto hará que el último código de salida de un comando externo se propague como código de salida de powershell. De lo contrario, la línea no se anexa al final del script.

pwsh - Uso de PowerShell Core
boolean. Valor predeterminado: false.

Si esto es true, las tareas que se ejecutan en agentes de Windows usarán pwsh.exe desde la ruta de acceso en lugar de powershell.exe.

workingDirectory - Directorio de trabajo
string.

Especifica el directorio de trabajo donde se ejecuta el script. Si no se especifica un valor, el directorio de trabajo es $(Build.SourcesDirectory).

runScriptInSeparateScope - Ejecutar script en el ámbito independiente
boolean. Valor predeterminado: false.

Esta entrada permite ejecutar scripts de PowerShell mediante & el operador en lugar del predeterminado .. Si esta entrada está establecida trueen , el script se ejecutará en un ámbito independiente y las variables de PowerShell con ámbito global no se actualizarán.

Opciones de control de tareas

Todas las tareas tienen opciones de control además de las entradas de tareas. Para obtener más información, vea Opciones de control y propiedades de tareas comunes.

Variables de salida

Ninguno.

Comentarios

Cada sesión de PowerShell solo dura el tiempo que dura el trabajo en el que se ejecuta. Las tareas que dependen de lo que se ha arrancado deben estar en el mismo trabajo que el arranque.

Métodos abreviados de tareas

PowerShell@2 tiene dos accesos directos en YAML: steps.powershell y steps.pwsh.

• powershellse ejecuta mediante Windows PowerShell (en Windows) o pwsh (Linux y macOS).
• pwsh ejecuta PowerShell Core, la edición multiplataforma de PowerShell basada en .NET Core.

steps:
- powershell: # Run a script in Windows PowerShell on Windows, and pwsh on Linux and macOS.
- pwsh: # Run a script in PowerShell Core on Windows, macOS, and Linux.

Establezca una variable para que los scripts y tareas posteriores puedan leerla.

Para obtener más información sobre cómo definir variables de compilación en un script, consulte Definición y modificación de las variables de compilación en un script.

Para más información sobre cómo definir variables de versión en un script, consulte Definición y modificación de las variables de versión en un script.

Pasar secretos de canalización en el script, pero el secreto no está enmascarado en los registros de canalización

Tenga en cuenta que PowerShell corta los mensajes de error, por lo que si usa secretos de canalización en un script, los secretos se podrían recortar y exponer. Por ejemplo, en el script insertado siguiente:

./script.ps1 --arg1 value1 --arg2 <some_secret_which_will_be_masked_here>

Podría haber una excepción como: : At <path_to_temp_script_file>:4 char:3

+   ./script.ps1 --arg1 value1 --arg2 <unmasked_part_of_original_secret> ...
+   ~~~~~~~~~~
    + <Additional exception details>

Para evitar este problema, puede controlar estas excepciones en un nivel de script o evitar casos en los que los secretos de canalización podrían aparecer en líneas de código fuente dentro de mensajes de error.

Ejemplos

• Invocación de un script desde un archivo
• Escritura de una advertencia
• Escritura de un error
• Llamada al script de PowerShell con varios argumentos

Invocación de un script desde un archivo

A continuación se muestra un archivo de PowerShell de ejemplo denominado test.ps1 ubicado en la raíz del repositorio.

Write-Host "Hello World from $Env:AGENT_NAME."
Write-Host "My ID is $Env:AGENT_ID."
Write-Host "AGENT_WORKFOLDER contents:"
gci $Env:AGENT_WORKFOLDER
Write-Host "AGENT_BUILDDIRECTORY contents:"
gci $Env:AGENT_BUILDDIRECTORY
Write-Host "BUILD_SOURCESDIRECTORY contents:"
gci $Env:BUILD_SOURCESDIRECTORY
Write-Host "Over and out."

Puede invocar este script en la canalización de la siguiente manera.

steps:
- task: PowerShell@2
  inputs:
    targetType: 'filePath'
    filePath: 'test.ps1'

Escritura de una advertencia

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: Write-Host "##vso[task.LogIssue type=warning;]This is the warning"
    # Writes a warning to build summary and to log in yellow text

Escritura de un error

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: Write-Host "##vso[task.LogIssue type=error;]This is the error"
    # Writes an error to build summary and to log in red text

Si desea que se produzca un error en la compilación, agregue exit 1 al script.

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      Write-Host "##vso[task.LogIssue type=error;]This is the error"
      exit 1
    # Writes an error to build summary and to log in red text

Llamada al script de PowerShell con varios argumentos

Creación de un script de PowerShell test2.ps1:

param ($input1, $input2)
Write-Host "$input1 $input2"

En la canalización de YAML, llame a:

- task: PowerShell@2
  inputs:
    targetType: 'filePath'
    filePath: $(System.DefaultWorkingDirectory)\test2.ps1
    arguments: > # Use this to avoid newline characters in multiline string
      -input1 "Hello"
      -input2 "World"
  displayName: 'Print Hello World'

Requisitos

Requisito	Descripción
Tipos de canalización	YAML, compilación clásica, versión clásica
Se ejecuta en	Agente, DeploymentGroup
Peticiones	None
Capabilities	Esta tarea no satisface ninguna demanda de tareas posteriores en el trabajo.
Restricciones de comandos	Any
Variables que se pueden establecer	Any
Versión del agente	2.115.0 o superior
Categoría de la tarea:	Utilidad

Consulte también

• Uso de un script de PowerShell para personalizar la canalización: ApplyVersionToAssemblies.ps1
• Más información sobre los scripts de PowerShell
  • Scripting con Windows PowerShell
  • Centro de scripts de Microsoft (los tipos del scripting)
  • PowerShell.org