PowerShell@2 – PowerShell v2-Aufgabe

Verwenden Sie diese Aufgabe, um ein PowerShell-Skript unter Linux, macOS oder Windows auszuführen.

Hinweis

PowerShell v2 verwendet standardmäßig PowerShell Core für Linux-Agents und Windows PowerShell für Windows-Agents. Um die neueste Version von PowerShell unter Windows-Agents zu verwenden, legen Sie den pwsh Parameter auf fest true. Stattdessen wird PowerShell Core verwendet.

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.

Eingaben

targetType - Typ
string. Zulässige Werte: filePath (Dateipfad), inline. Standardwert. filePath.

Gibt den Typ des Skripts für die auszuführende Aufgabe an: ein Inlineskript oder ein Pfad zu einer .ps1 Datei.

filePath - Skriptpfad
string. Erforderlich, wenn targetType = filePath.

Gibt den Pfad des auszuführenden Skripts an. Muss ein vollqualifizierter Pfad oder relativ zu $(System.DefaultWorkingDirectory) sein.

arguments - Argumente
string. Optional. Verwenden Sie , wenn targetType = filePath.

Gibt die Argumente an, die an das PowerShell-Skript übergeben werden. Argumente können Ordnungsparameter oder benannte Parameter sein. Beispiel: -Name someName -Path -Value "Some long string value".

arguments wird nicht verwendet, wenn targetType auf inlinefestgelegt ist.

script - Skript
string. Erforderlich, wenn targetType = inline. Standardwert. # Write your PowerShell commands here.\n\nWrite-Host "Hello World".

Gibt den Inhalt des Skripts an. Die maximale unterstützte Inlineskriptlänge beträgt 20000 Zeichen. Verwenden Sie ein Skript aus einer Datei, wenn Sie ein längeres Skript verwenden möchten.

errorActionPreference - ErrorActionPreference
string. Zulässige Werte: default, stop, continue, silentlyContinue. Standardwert. stop.

Stellt die Zeile $ErrorActionPreference = 'VALUE' oben im Skript vor.

warningPreference - WarnungPreference
string. Zulässige Werte: default, stop, continue, silentlyContinue. Standardwert. default.

Wenn nicht auf Defaultfestgelegt ist, wird die Zeile $WarningPreference = 'VALUE' am oberen Rand des Skripts vorangestellt.

informationPreference - InformationenPräference
string. Zulässige Werte: default, stop, continue, silentlyContinue. Standardwert. default.

Wenn nicht auf Defaultfestgelegt ist, wird die Zeile $InformationPreference = 'VALUE' am oberen Rand des Skripts vorangestellt.

verbosePreference - AusführlichVorschau
string. Zulässige Werte: default, stop, continue, silentlyContinue. Standardwert. default.

Wenn nicht auf Defaultfestgelegt ist, wird die Zeile $VerbosePreference = 'VALUE' am oberen Rand des Skripts vorangestellt.

debugPreference - DebugPreference
string. Zulässige Werte: default, stop, continue, silentlyContinue. Standardwert. default.

Wenn nicht auf Defaultfestgelegt ist, wird die Zeile $DebugPreference = 'VALUE' am oberen Rand des Skripts vorangestellt.

progressPreference - ProgressPreference
string. Zulässige Werte: default, stop, continue, silentlyContinue. Standardwert. silentlyContinue.

Wenn nicht auf Defaultfestgelegt ist, wird die Zeile $ProgressPreference = 'VALUE' am oberen Rand des Skripts vorangestellt.

failOnStderr - Fehler beim Standardfehler
boolean. Standardwert. false.

Wenn der Wert dieses booleschen Werts ist, schlägt truedie Aufgabe fehl, wenn Fehler in die Fehlerpipeline geschrieben werden oder wenn Daten in den Standardfehlerstream geschrieben werden. Andernfalls basiert die Aufgabe auf dem Exitcode, um den Fehler zu ermitteln.

showWarnings - Anzeigen von Warnungen als Azure DevOps-Warnungen
boolean. Standardwert. false.

Wenn der Wert auf truefestgelegt ist und Ihr Skript Warnungen schreibt, werden die Warnungen in Pipelineprotokollen als Warnungen angezeigt.

ignoreLASTEXITCODE - $LASTEXITCODE ignorieren
boolean. Standardwert. false.

Wenn der Wert auf falsefestgelegt ist, wird die Zeile if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } an das Ende Ihres Skripts angefügt. Dadurch wird der letzte Exitcode eines externen Befehls als Exitcode von powershellweitergegeben. Andernfalls wird die Zeile nicht an das Ende Ihres Skripts angefügt.

pwsh - Verwenden von PowerShell Core
boolean. Standardwert. false.

Wenn dies der Fall ist, werden Aufgaben, die auf Windows-Agents ausgeführt werden, von Ihrem Pfad anstelle von powershell.exeverwendetpwsh.exe.

workingDirectory - Arbeitsverzeichnis
string.

Gibt das Arbeitsverzeichnis an, in dem das Skript ausgeführt wird. Wenn kein Wert angegeben wird, lautet $(Build.SourcesDirectory)das Arbeitsverzeichnis .

runScriptInSeparateScope - Ausführen eines Skripts im separaten Bereich
boolean. Standardwert. false.

Diese Eingabe ermöglicht das Ausführen von PowerShell-Skripts mit dem & Operator anstelle des Standardoperators .. Wenn diese Eingabe auf truefestgelegt ist, wird das Skript in einem separaten Bereich ausgeführt, und globale PowerShell-Variablen werden nicht aktualisiert.

Optionen für die Vorgangskontrolle

Alle Vorgänge verfügen zusätzlich zu ihren Eingaben über Steuerungsoptionen. Weitere Informationen finden Sie unter Steuerungsoptionen und allgemeine Aufgabeneigenschaften.

Ausgabevariablen

Keine.

Hinweise

Jede PowerShell-Sitzung bleibt nur für die Dauer des Auftrags, in dem sie ausgeführt wird, bestehen. Vorgänge, die davon abhängen, welches Bootstrapping stattgefunden hat, müssen sich im selben Auftrag wie der Bootstrap befinden.

Aufgabenverknüpfungen

PowerShell@2 verfügt über zwei Verknüpfungen in YAML: steps.powershell und steps.pwsh.

• powershellwird entweder mit Windows PowerShell (unter Windows) oder pwsh (Linux und macOS) ausgeführt.
• pwsh führt PowerShell Core aus, die plattformübergreifende Edition von PowerShell, die auf .NET Core basiert.

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.

Festlegen einer Variablen, damit sie von nachfolgenden Skripts und Aufgaben gelesen werden kann

Weitere Informationen zum Definieren von Buildvariablen in einem Skript finden Sie unter Definieren und Ändern Ihrer Buildvariablen in einem Skript.

Weitere Informationen zum Definieren von Releasevariablen in einem Skript finden Sie unter Definieren und Ändern ihrer Releasevariablen in einem Skript.

Übergeben von Pipelinegeheimnissen im Skript, aber geheimnis ist nicht in Pipelineprotokollen maskiert

Beachten Sie, dass PowerShell Fehlermeldungen abschneidet. Wenn Sie also Pipelinegeheimnisse in einem Skript verwenden, können die Geheimnisse gekürzt und verfügbar gemacht werden. Beispiel: Im folgenden Inlineskript:

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

Es könnte eine Ausnahme wie folgende geben: At <path_to_temp_script_file>:4 char:3:

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

Um dieses Problem zu vermeiden, können Sie diese Ausnahmen auf Skriptebene behandeln oder Fälle vermeiden, in der Pipelinegeheimnisse in Quellcodezeilen in Fehlermeldungen angezeigt werden können.

Beispiele

• Aufrufen eines Skripts aus einer Datei
• Schreiben einer Warnung
• Schreiben eines Fehlers
• Aufrufen eines PowerShell-Skripts mit mehreren Argumenten

Aufrufen eines Skripts aus einer Datei

Im Folgenden finden Sie eine PowerShell-Beispieldatei namens test.ps1 im Stammverzeichnis Ihres Repositorys.

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

Sie können dieses Skript in Ihrer Pipeline wie folgt aufrufen.

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

Schreiben einer Warnung

- 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

Schreiben eines Fehlers

- 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

Wenn dieser Fehler beim Build fehlschlägt, fügen Sie dem Skript hinzu exit 1 .

- 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

Aufrufen eines PowerShell-Skripts mit mehreren Argumenten

PowerShell-Skript erstellen test2.ps1:

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

Nehmen Sie in Ihrer YAML-Pipeline folgenden Aufruf vor:

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

Anforderungen

Anforderung	BESCHREIBUNG
Pipelinetypen	YAML, Klassischer Build, klassisches Release
Wird ausgeführt auf	Agent, DeploymentGroup
Forderungen	Keine
Capabilities	Diese Aufgabe erfüllt keine Anforderungen an nachfolgende Aufgaben im Auftrag.
Befehlseinschränkungen	Any
Setzbare Variablen	Any
Agent-Version	2.115.0 oder höher
Aufgabenkategorie	Hilfsprogramm

Weitere Informationen

• Verwenden eines PowerShell-Skripts zum Anpassen Ihrer Pipeline – ApplyVersionToAssemblies.ps1
• Weitere Informationen zu PowerShell-Skripts
  • Skripting mit WindowsPowerShell
  • Microsoft Script Center (the Scripting Guys)
  • PowerShell.org