PowerShell@2 - Tâche PowerShell v2

Utilisez cette tâche pour exécuter un script PowerShell sur Linux, macOS ou Windows.

Notes

Par défaut, PowerShell v2 utilise PowerShell Core pour les agents Linux et Windows PowerShell pour les agents Windows. Pour utiliser la dernière version de PowerShell sur les agents Windows, définissez le paramètre sur pwshtrue. PowerShell Core sera ensuite utilisé à la place.

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.

Entrées

targetType - Type
string. Valeurs autorisées : filePath (Chemin du fichier), inline. Valeur par défaut : filePath.

Spécifie le type de script pour la tâche à exécuter : un script inline ou un chemin d’accès à un .ps1 fichier.

filePath - Chemin d’accès du script
string. Nécessaire lorsque targetType = filePath.

Spécifie le chemin d’accès du script à exécuter. Doit être un chemin d’accès complet ou relatif à $(System.DefaultWorkingDirectory).

arguments - Arguments
string. facultatif. Utilisez quand targetType = filePath.

Spécifie les arguments passés au script PowerShell. Les arguments peuvent être des paramètres ordinaux ou des paramètres nommés. Par exemple : -Name someName -Path -Value "Some long string value".

arguments n’est pas utilisé lorsque targetType est défini sur inline.

script - Script
string. Nécessaire lorsque targetType = inline. Valeur par défaut : # Write your PowerShell commands here.\n\nWrite-Host "Hello World".

Spécifie le contenu du script. La longueur maximale prise en charge du script inline est de 2 0000 caractères. Utilisez un script à partir d’un fichier si vous souhaitez utiliser un script plus long.

errorActionPreference - ErrorActionPreference
string. Valeurs autorisées : default, stop, continue, silentlyContinue. Valeur par défaut : stop.

Ajoute la ligne $ErrorActionPreference = 'VALUE' en haut de votre script.

warningPreference - WarningPreference
string. Valeurs autorisées : default, stop, continue, silentlyContinue. Valeur par défaut : default.

Lorsque la valeur n’est Defaultpas définie sur , ajoute la ligne $WarningPreference = 'VALUE' en haut de votre script.

informationPreference - InformationPreference
string. Valeurs autorisées : default, stop, continue, silentlyContinue. Valeur par défaut : default.

Lorsque la valeur n’est Defaultpas définie sur , ajoute la ligne $InformationPreference = 'VALUE' en haut de votre script.

verbosePreference - VerbosePreference
string. Valeurs autorisées : default, stop, continue, silentlyContinue. Valeur par défaut : default.

Lorsque la valeur n’est Defaultpas définie sur , ajoute la ligne $VerbosePreference = 'VALUE' en haut de votre script.

debugPreference - DebugPreference
string. Valeurs autorisées : default, stop, continue, silentlyContinue. Valeur par défaut : default.

Lorsque la valeur n’est Defaultpas définie sur , ajoute la ligne $DebugPreference = 'VALUE' en haut de votre script.

progressPreference - ProgressPreference
string. Valeurs autorisées : default, stop, continue, silentlyContinue. Valeur par défaut : silentlyContinue.

Lorsque la valeur n’est Defaultpas définie sur , ajoute la ligne $ProgressPreference = 'VALUE' en haut de votre script.

failOnStderr - Échec en cas d’erreur standard
boolean. Valeur par défaut : false.

Si la valeur de cette valeur booléenne est true, la tâche échoue si des erreurs sont écrites dans le pipeline d’erreurs ou si des données sont écrites dans le flux d’erreurs standard. Sinon, la tâche s’appuie sur le code de sortie pour déterminer l’échec.

showWarnings - Afficher les avertissements sous forme d’avertissements Azure DevOps
boolean. Valeur par défaut : false.

Si la valeur est définie sur trueet que votre script écrit des avertissements, les avertissements s’affichent sous forme d’avertissements dans les journaux de pipeline.

ignoreLASTEXITCODE - Ignorer $LASTEXITCODE
boolean. Valeur par défaut : false.

Si la valeur est définie sur false, la ligne if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } est ajoutée à la fin de votre script. Cela entraîne la propagation du dernier code de sortie d’une commande externe en tant que code de sortie de powershell. Sinon, la ligne n’est pas ajoutée à la fin de votre script.

pwsh - Utiliser PowerShell Core
boolean. Valeur par défaut : false.

Si cela est vrai, les tâches exécutées sur les agents Windows utilisent pwsh.exe à partir de votre chemin d’accès au lieu de powershell.exe.

workingDirectory - Répertoire de travail
string.

Spécifie le répertoire de travail dans lequel le script est exécuté. Si aucune valeur n’est spécifiée, le répertoire de travail est $(Build.SourcesDirectory).

runScriptInSeparateScope - Exécuter le script dans l’étendue distincte
boolean. Valeur par défaut : false.

Cette entrée permet d’exécuter des scripts PowerShell à l’aide & de l’opérateur au lieu de la valeur par défaut .. Si cette entrée est définie sur true, le script est exécuté dans une étendue distincte et les variables PowerShell globales ne sont pas mises à jour.

Options de contrôle de la tâche

Toutes les tâches ont des options de contrôle en plus de leurs entrées de tâches. Pour plus d’informations, consultez Options de contrôle et propriétés de tâche courantes.

Variables de sortie

Aucun.

Notes

Chaque session PowerShell existe uniquement pendant la durée du travail dans lequel elle s’exécute. Les tâches qui dépendent des éléments démarrés doivent se trouver dans le même travail que le démarrage.

Raccourcis de tâche

PowerShell@2 comporte deux raccourcis dans YAML : steps.powershell et steps.pwsh.

• powershells’exécute à l’aide de Windows PowerShell (sur Windows) ou pwsh (Linux et macOS).
• pwsh exécute PowerShell Core, l’édition multiplateforme de PowerShell basée sur .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.

Définir une variable afin qu’elle puisse être lue par les scripts et tâches suivants

Pour en savoir plus sur la définition de variables de build dans un script, consultez Définir et modifier vos variables de build dans un script.

Pour en savoir plus sur la définition de variables de mise en production dans un script, consultez Définir et modifier vos variables de mise en production dans un script.

Passage de secrets de pipeline dans un script, mais le secret n’est pas masqué dans les journaux de pipeline

N’oubliez pas que PowerShell supprime les messages d’erreur. Par conséquent, si vous utilisez des secrets de pipeline dans un script, les secrets peuvent être supprimés et exposés. Par exemple, dans le script inline ci-dessous :

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

Il peut y avoir une exception comme : At <path_to_temp_script_file>:4 char:3

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

Pour éviter ce problème, vous pouvez gérer ces exceptions au niveau du script ou éviter les cas où des secrets de pipeline peuvent apparaître dans les lignes de code source dans les messages d’erreur.

Exemples

• Appeler un script à partir d’un fichier
• Écrire un avertissement
• Écrire une erreur
• Appeler un script PowerShell avec plusieurs arguments

Appeler un script à partir d’un fichier

Voici un exemple de fichier PowerShell nommé test.ps1 situé à la racine de votre dépôt.

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

Vous pouvez appeler ce script dans votre pipeline comme suit.

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

Écrire un avertissement

- 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

Écrire une erreur

- 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 vous souhaitez que cette erreur échoue à la build, ajoutez exit 1 au 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

Appeler un script PowerShell avec plusieurs arguments

Créer un script PowerShell test2.ps1 :

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

Dans votre pipeline YAML, appelez :

- 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'

Configuration requise

Condition requise	Description
Types de pipelines	YAML, build classique, version classique
S’exécute sur	Agent, DeploymentGroup
Demandes	None
Capabilities	Cette tâche ne répond à aucune demande pour les tâches suivantes dans le travail.
Restrictions de commande	Quelconque
Variables paramétrables	Quelconque
Version de l’agent	2.115.0 ou version ultérieure
Catégorie de la tâche	Utilitaire

Voir aussi

• Utiliser un script PowerShell pour personnaliser votre pipeline - ApplyVersionToAssemblies.ps1
• En savoir plus sur les scripts PowerShell
  • Écriture de scripts avec Windows PowerShell
  • Centre de scripts Microsoft (the Scripting Guys)
  • PowerShell.org