PowerShellOnTargetMachines@3 - PowerShell op doelmachines v3-taak

Artikel
2025-03-24

Gebruik deze taak om PowerShell-scripts uit te voeren op externe machines met behulp van PSSession en Invoke-Command voor externe communicatie.

Syntaxis

# PowerShell on target machines v3
# Execute PowerShell scripts on remote machines using PSSession and Invoke-Command for remoting.
- task: PowerShellOnTargetMachines@3
  inputs:
    Machines: # string. Required. Machines. 
    #UserName: # string. Username. 
    #UserPassword: # string. Password. 
  # Script options
    #ScriptType: 'Inline' # 'FilePath' | 'Inline'. Script Type. Default: Inline.
    #ScriptPath: # string. Required when ScriptType = FilePath. Script File Path. 
    InlineScript: # string. Required when ScriptType = Inline. Script. 
    #ScriptArguments: # string. Optional. Use when ScriptType = FilePath. Script Arguments. 
    #InitializationScript: # string. Optional. Use when ScriptType = FilePath. Initialization script. 
    #SessionVariables: # string. Optional. Use when ScriptType = FilePath. Session Variables. 
  # PSSession options
    #CommunicationProtocol: 'Https' # 'Http' | 'Https'. Protocol. Default: Https.
    #AuthenticationMechanism: 'Default' # 'Default' | 'Credssp'. Authentication. Default: Default.
    #NewPsSessionOptionArguments: '-SkipCACheck -IdleTimeout 7200000 -OperationTimeout 0 -OutputBufferingMode Block' # string. Session Option parameters. Default: -SkipCACheck -IdleTimeout 7200000 -OperationTimeout 0 -OutputBufferingMode Block.
  # Error handling options
    #ErrorActionPreference: 'stop' # 'stop' | 'continue' | 'silentlyContinue'. ErrorActionPreference. Default: stop.
    #failOnStderr: false # boolean. Fail on Standard Error. Default: false.
    #ignoreLASTEXITCODE: false # boolean. Ignore $LASTEXITCODE. Default: false.
  # Advanced
    #WorkingDirectory: # string. Working Directory. 
    #RunPowershellInParallel: true # boolean. Run PowerShell in Parallel. Default: true.

Invoer

Machines - Machines
string. Verplicht.

Hiermee geeft u een door komma's gescheiden lijst met FQDN's of IP-adressen van computers op, en eventueel het poortnummer. Dit kan zijn:

De naam van een Azure-resourcegroep.
Een door komma's gescheiden lijst met computernamen. Voorbeeld: dbserver.fabrikam.com,dbserver_int.fabrikam.com:5986,192.168.34:5986
Een uitvoervariabele van een vorige taak.

Als u geen poort opgeeft, wordt de standaard WinRM-poort gebruikt. Dit is afhankelijk van het protocol dat u hebt geconfigureerd. Voor WinRM 2.0 is de standaard-HTTP-poort 5985 en is de standaard HTTPS-poort 5986.

UserName - gebruikersnaam
string.

Hiermee geeft u de gebruikersnaam van een domein of een lokaal beheerdersaccount op de doelhost(s).

Indelingen zoals username, domain\username, machine-name\usernameen .\username worden ondersteund.
UPN-indelingen zoals username@domain.com en ingebouwde systeemaccounts zoals NT Authority\System worden niet ondersteund.

UserPassword - wachtwoord
string.

Hiermee geeft u het wachtwoord voor de doelmachines. Variabelen die zijn gedefinieerd in build-/releasedefinities als $(passwordVariable) worden geaccepteerd. U kunt het variabeletype markeren als secret om het te beveiligen.

ScriptType - scripttype
string. Toegestane waarden: FilePath (bestandspad), Inline. Standaardwaarde: Inline.

Hiermee geeft u het type script dat moet worden uitgevoerd: Inline of Bestandspad.

ScriptPath - scriptbestandspad
string. Vereist wanneer ScriptType = FilePath.

Hiermee geeft u de locatie van het PowerShell-script op de doelcomputers of op een UNC-pad, zoals C:\BudgetIT\Web\Deploy\Website.ps1, dat toegankelijk moet zijn vanaf de doelcomputer.

InlineScript - script
string. Vereist wanneer ScriptType = Inline. Standaardwaarde: # Write your powershell commands here.\n\nWrite-Output "Hello World".

ScriptArguments - scriptargumenten
string. Facultatief. Gebruiken wanneer ScriptType = FilePath.

Hiermee geeft u de argumenten voor het PowerShell-script. Kan ordinale of benoemde parameters zijn, zoals -testParam test. Bijvoorbeeld: -applicationPath $(applicationPath), -username $(vmusername), -password $(vmpassword).

InitializationScript - initialisatiescript
string. Facultatief. Gebruiken wanneer ScriptType = FilePath.

Hiermee geeft u de locatie van het gegevensscript voor de DSC op de doelcomputers of op een UNC-pad, zoals C:\BudgetIT\Web\Deploy\WebsiteConfiguration.ps1. Het is raadzaam argumenten te gebruiken in plaats van een initialisatiescript.

SessionVariables - sessievariabelen
string. Facultatief. Gebruiken wanneer ScriptType = FilePath.

Wordt gebruikt voor het instellen van de sessievariabelen voor de PowerShell-scripts.
Hiermee geeft u een door komma's gescheiden lijst op, zoals $varx=valuex, $vary=valuey. Meestal gebruikt voor achterwaartse compatibiliteit met eerdere versies van de releaseservice. Het is raadzaam argumenten te gebruiken in plaats van sessievariabelen.

CommunicationProtocol - Protocol
string. Toegestane waarden: Http, Https. Standaardwaarde: Https.

Hiermee geeft u het protocol dat moet worden gebruikt voor de WinRM-serviceverbinding met de machine(s). De standaardwaarde is HTTPS.

AuthenticationMechanism - verificatie
string. Toegestane waarden: Default, Credssp. Standaardwaarde: Default.

Hiermee geeft u het verificatiemechanisme op dat wordt gebruikt voor het maken van de PSSession. Voor CredSSP verificatie zijn de velden gebruikersnaam en wachtwoord verplicht.

parameters voor NewPsSessionOptionArguments - sessieoptie
string. Standaardwaarde: -SkipCACheck -IdleTimeout 7200000 -OperationTimeout 0 -OutputBufferingMode Block.

Geavanceerde opties voor een externe sessie (New-PSSessionOption). Bijvoorbeeld -SkipCACheck, -SkipCNCheck, -SkipRevocationCheck, enzovoort. Zie een volledige lijst met alle sessieopties voor meer informatie.

ErrorActionPreference - ErrorActionPreference
string. Toegestane waarden: stop, continue, silentlyContinue. Standaardwaarde: stop.

Hiermee wordt de regel $ErrorActionPreference = 'VALUE' boven aan het script voorbereid.

failOnStderr - mislukt bij standaardfout
boolean. Standaardwaarde: false.

Als deze optie is ingesteld op true, mislukt het als er fouten naar de foutpijplijn worden geschreven of als er gegevens naar de standaardfoutstroom worden geschreven. Anders is de taak afhankelijk van de afsluitcode om de fout te bepalen.

ignoreLASTEXITCODE - $LASTEXITCODE negeren
boolean. Standaardwaarde: false.

Als dit is ingesteld op false, wordt de regel if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } aan het einde van het script uitgevoerd. Hierdoor wordt de laatste afsluitcode van een externe opdracht doorgegeven als de afsluitcode van PowerShell. Anders wordt de regel niet uitgevoerd aan het einde van het script.

WorkingDirectory - werkmap
string.

Hiermee geeft u de werkmap waarin het script wordt uitgevoerd.

RunPowershellInParallel - PowerShell parallel uitvoeren
boolean. Standaardwaarde: true.

Als deze optie is ingesteld op true, worden de PowerShell-scripts parallel uitgevoerd op de doelcomputers.

Opties voor taakbeheer

Alle taken hebben besturingsopties naast hun taakinvoer. Zie Opties en algemene taakeigenschappenvoor meer informatie.

Uitvoervariabelen

Geen.

Opmerkingen

Gebruik deze taak om PowerShell-scripts uit te voeren op externe computers.

Met deze taak kunnen zowel PowerShell-scripts als PowerShell-DSC-scripts worden uitgevoerd:

Voor PowerShell-scripts moeten op de computers PowerShell 2.0 of hoger zijn geïnstalleerd.
Voor PowerShell-DSC scripts moeten de computers de nieuwste versie van het Windows Management Framework geïnstalleerd. Dit is standaard geïnstalleerd in Windows 8.1, Windows Server 2012 R2 en volgende versies.

Benodigdheden

Deze taak maakt gebruik van Windows Remote Management (WinRM) voor toegang tot on-premises fysieke computers of virtuele computers die lid zijn van een domein of werkgroep.

WinRM instellen voor on-premises fysieke computers of virtuele machines

Volg de stappen die worden beschreven in domein-gekoppelde

WinRM instellen voor Microsoft Azure Virtual Machines

Voor Azure Virtual Machines is WinRM vereist om het HTTPS-protocol te gebruiken. U kunt een zelfondertekend testcertificaat gebruiken. In dit geval valideert de automatiseringsagent de echtheid van het certificaat niet als uitgegeven door een vertrouwde certificeringsinstantie.

klassieke virtuele Azure-machines. Wanneer u een klassieke virtuele machine maakt vanuit Azure Portal, is de virtuele machine al ingesteld voor WinRM via HTTPS, waarbij de standaardpoort 5986 al is geopend in de firewall en een zelfondertekend certificaat dat op de machine is geïnstalleerd. Deze virtuele machines kunnen worden geopend zonder verdere configuratie vereist. Bestaande klassieke virtuele machines kunnen ook worden geselecteerd met behulp van de azure-resourcegroepimplementatie taak.
Azure-resourcegroep. Als u een Azure-resourcegroep hebt al gedefinieerd in Azure Portal, moet u deze configureren voor het gebruik van het WinRM HTTPS-protocol. U moet poort 5986 openen in de firewall en een zelfondertekend certificaat installeren.

Als u Azure-resourcegroepen met virtuele machines dynamisch wilt implementeren, gebruikt u de azure-resourcegroepimplementatie taak. Deze taak heeft een selectievakje met de naam Implementatievereisten inschakelen. Selecteer dit om het WinRM HTTPS-protocol automatisch in te stellen op de virtuele machines, poort 5986 in de firewall te openen en een testcertificaat te installeren. De virtuele machines zijn vervolgens klaar voor gebruik in de implementatietaak.

Wat is er nieuw in deze taakversie?

Gebruikt PSSession en invoke-command om externe communicatie op doelcomputers uit te voeren.
Er is ondersteuning toegevoegd voor de uitvoering van inlinescripts.
Standaard- en CredSSP-verificatie worden ondersteund.
Extra opties voor foutafhandeling: ErrorActionPreference, ignoreLASTEXITCODE en mislukken op standaardfout.

Vereisten

Voorwaarde	Beschrijving
Pijplijntypen	YAML, klassieke build, klassieke release
Wordt uitgevoerd op	Agent, DeploymentGroup
eisen	Geen
mogelijkheden	Deze taak voldoet niet aan de vereisten voor volgende taken in de taak.
opdrachtbeperkingen	Welk dan ook
variabelen instellen	Welk dan ook
Agentversie	2.134.0 of hoger
Taakcategorie	Implementeren

Delen via