PowerShell@2 – PowerShell v2-Aufgabe

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

Hinweis

Standardmäßig verwendet PowerShell v2 PowerShell Core für Linux-Agents und Windows PowerShell für Windows-Agents. Um die neueste Version von PowerShell für Windows-Agents zu verwenden, legen Sie den parameter pwsh auf truefest. 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.

Eingänge

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. Wahlfrei. Wird verwendet, 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 maximal 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 voran.

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

Wenn sie nicht auf Defaultfestgelegt ist, wird die Zeile $WarningPreference = 'VALUE' oben im Skript vorangestellt.

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

Wenn sie nicht auf Defaultfestgelegt ist, wird die Zeile $InformationPreference = 'VALUE' oben im Skript vorangestellt.

verbosePreference - VerbosePreference-
string. Zulässige Werte: default, stop, continue, silentlyContinue. Standardwert: default.

Wenn sie nicht auf Defaultfestgelegt ist, wird die Zeile $VerbosePreference = 'VALUE' oben im Skript vorangestellt.

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

Wenn sie nicht auf Defaultfestgelegt ist, wird die Zeile $DebugPreference = 'VALUE' oben im Skript vorangestellt.

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

Wenn sie nicht auf Defaultfestgelegt ist, wird die Zeile $ProgressPreference = 'VALUE' oben im Skript vorangestellt.

failOnStderr - fehler bei Standardfehler-
boolean. Standardwert: false.

Wenn der Wert dieses booleschen Werts trueist, schlägt die Aufgabe fehl, wenn Fehler in die Fehlerpipeline geschrieben werden oder daten in den Standardfehlerdatenstrom geschrieben werden. Andernfalls basiert die Aufgabe auf dem Beendigungscode, um fehler zu ermitteln.

showWarnings - Warnungen als Azure DevOps-Warnungen anzeigen
boolean. Standardwert: false.

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

ignoreLASTEXITCODE - ignorieren $LASTEXITCODE
boolean. Standardwert: false.

Wenn der Wert auf falsefestgelegt ist, wird die Zeile if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } am Ende des Skripts angefügt. Dies führt dazu, dass der letzte Exitcode von einem externen Befehl als Exitcode von powershellweitergegeben wird. Andernfalls wird die Zeile nicht am Ende des Skripts angefügt.

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

Wenn dies zutrifft, verwenden Aufgaben, die unter Windows-Agents ausgeführt werden, pwsh.exe von Ihrem Pfad anstelle von powershell.exe.

workingDirectory - Arbeitsverzeichnis-
string.

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

runScriptInSeparateScope - Skript ausführen im separaten Bereich
boolean. Standardwert: false.

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

Aufgabensteuerungsoptionen

Alle Aufgaben verfügen zusätzlich zu ihren Aufgabeneingaben über Steuerungsoptionen. Weitere Informationen finden Sie unter Steuerelementoptionen und allgemeinen Aufgabeneigenschaften.

Ausgabevariablen

Keiner.

Bemerkungen

Jede PowerShell-Sitzung dauert nur für die Dauer des Auftrags, in dem sie ausgeführt wird. Aufgaben, die davon abhängen, was bootstrapped wurde, müssen sich im gleichen Auftrag wie der Bootstrap befinden.

Aufgabenverknüpfungen

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

• powershell wird entweder mit Windows PowerShell (unter Windows) oder pwsh (Linux und macOS) ausgeführt.
• pwsh führt PowerShell Core aus, der plattformübergreifenden 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 der Buildvariablen in einem Skript.

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

Übergeben geheimer Pipelineschlüssel im Skript, geheimer Schlüssel ist jedoch nicht in Pipelineprotokollen maskiert

Beachten Sie, dass PowerShell Fehlermeldungen ausschneidet. Wenn Sie also Pipelineschlüssel in einem Skript verwenden, können die geheimen Schlüssel gekürzt und verfügbar gemacht werden. Beispiel: Inlineskript unten:

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

Es kann eine Ausnahme wie: 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 dem Pipelineschlüssel in Quellcodezeilen in Fehlermeldungen angezeigt werden können.

Beispiele

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

Aufrufen eines Skripts aus einer Datei

Im Folgenden finden Sie eine PowerShell-Beispieldatei mit dem Namen 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 wie folgt in Ihrer Pipeline 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 den Build nicht ausführen soll, fügen Sie dem Skript exit 1 hinzu.

- 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

Erstellen eines PowerShell-Skripts test2.ps1:

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

Rufen Sie in Ihrer YAML-Pipeline Folgendes auf:

- 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, Classic Build, Classic Release
Läuft auf	Agent, DeploymentGroup
Anforderungen	Nichts
Funktionen	Dieser Vorgang erfüllt keine Anforderungen für nachfolgende Vorgänge im Auftrag.
Befehlseinschränkungen	Jegliche
Settable-Variablen	Jegliche
Agentversion	2.115.0 oder höher
Vorgangskategorie	Nützlichkeit

Siehe auch

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