PowerShellOnTargetMachines@3 — program PowerShell na maszynach docelowych w wersji 3

Artykuł
01/29/2025

To zadanie służy do wykonywania skryptów programu PowerShell na maszynach zdalnych przy użyciu programu PSSession i Invoke-Command na potrzeby komunikacji zdalnej.

To zadanie służy do wykonywania skryptów programu PowerShell na maszynach zdalnych. Ta wersja zadania używa programu PSSession i Invoke-Command do komunikacji zdalniej.

Składnia

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

# PowerShell on Target Machines v3
# Execute PowerShell scripts on remote machine(s). This version of the task uses 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.

Dane wejściowe

Machines - Maszyny
string. Wymagane.

Określa rozdzielaną przecinkami listę nazw FQDN maszyny lub adresów IP i opcjonalnie zawiera numer portu. Może to być:

Nazwa grupy zasobów platformy Azure.
Rozdzielana przecinkami lista nazw maszyn. Przykład: dbserver.fabrikam.com,dbserver_int.fabrikam.com:5986,192.168.34:5986
Zmienna wyjściowa z poprzedniego zadania.

Jeśli nie określisz portu, zostanie użyty domyślny port usługi WinRM. Zależy to od skonfigurowanego protokołu. W przypadku usługi WinRM 2.0 domyślnym portem HTTP jest 5985 , a domyślnym portem HTTPS jest 5986.

UserName - Nazwę użytkownika
string.

Określa nazwę użytkownika domeny lub lokalnego konta administracyjnego na hostach docelowych.

Obsługiwane są formaty, takie jak username, domain\username, machine-name\usernamei .\username .
Formaty nazwy UPN, takie jak username@domain.com i wbudowane konta systemowe, takie jak NT Authority\System , nie są obsługiwane.

UserPassword - Hasło
string.

Określa hasło dla maszyn docelowych. Zmienne zdefiniowane w definicjach kompilacji/wydania są $(passwordVariable) akceptowane. Możesz oznaczyć typ zmiennej jako secret , aby ją zabezpieczyć.

ScriptType - Typ skryptu
string. Dozwolone wartości: FilePath (ścieżka pliku), Inline. Wartość domyślna: Inline.

Określa typ skryptu do wykonania: wbudowany lub ścieżka pliku.

ScriptPath - Ścieżka pliku skryptu
string. Wymagane, gdy ScriptType = FilePath.

Określa lokalizację skryptu programu PowerShell na maszynach docelowych lub w ścieżce UNC, takiej jak C:\BudgetIT\Web\Deploy\Website.ps1, która powinna być dostępna z maszyny docelowej.

InlineScript - Skrypt
string. Wymagane, gdy ScriptType = Inline. Wartość domyślna: # Write your powershell commands here.\n\nWrite-Output "Hello World".

ScriptArguments - Argumenty skryptu
string. Opcjonalny. Użyj polecenia , gdy ScriptType = FilePath.

Określa argumenty skryptu programu PowerShell. Mogą być porządkowe lub nazwane parametry, takie jak -testParam test. Na przykład: -applicationPath $(applicationPath), , -password $(vmpassword)-username $(vmusername).

InitializationScript - Skrypt inicjowania
string. Opcjonalny. Użyj polecenia , gdy ScriptType = FilePath.

Określa lokalizację skryptu danych dla rozszerzenia DSC na maszynach docelowych lub w ścieżce UNC, na przykład C:\BudgetIT\Web\Deploy\WebsiteConfiguration.ps1. Zaleca się używanie argumentów zamiast skryptu inicjowania.

SessionVariables - Zmienne sesji
string. Opcjonalny. Użyj polecenia , gdy ScriptType = FilePath.

Służy do konfigurowania zmiennych sesji dla skryptów programu PowerShell.
Określa listę rozdzielaną przecinkami, taką jak $varx=valuex, $vary=valuey. Najczęściej używane w celu zapewnienia zgodności z poprzednimi wersjami usługi wydania. Zaleca się używanie argumentów zamiast zmiennych sesji.

CommunicationProtocol - Protokół
string. Dozwolone wartości: Http, Https. Wartość domyślna: Https.

Określa protokół do użycia dla połączenia usługi WinRM z maszynami. Wartość domyślna to HTTPS.

AuthenticationMechanism - Uwierzytelniania
string. Dozwolone wartości: Default, Credssp. Wartość domyślna: Default.

Określa mechanizm uwierzytelniania używany do tworzenia pssession. W przypadku CredSSP uwierzytelniania pola nazwy użytkownika i hasła są obowiązkowe.

NewPsSessionOptionArguments - Parametry opcji sesji
string. Wartość domyślna: -SkipCACheck -IdleTimeout 7200000 -OperationTimeout 0 -OutputBufferingMode Block.

Zaawansowane opcje sesji zdalnej (New-PSSessionOption). Na przykład , -SkipCACheck-SkipCNCheck, , -SkipRevocationCheckitp. Zobacz pełną listę wszystkich opcji sesji, aby dowiedzieć się więcej.

ErrorActionPreference - ErrorActionPreference
string. Dozwolone wartości: stop, continue, silentlyContinue. Wartość domyślna: stop.

Poprzedza wiersz $ErrorActionPreference = 'VALUE' w górnej części skryptu.

failOnStderr - Błąd standardowy kończy się niepowodzeniem
boolean. Wartość domyślna: false.

Jeśli ustawiono wartość true, nie powiedzie się, jeśli jakiekolwiek błędy zostaną zapisane w potoku błędów lub jeśli jakiekolwiek dane zostaną zapisane w strumieniu błędu standardowego. W przeciwnym razie zadanie opiera się na kodzie zakończenia w celu określenia błędu.

ignoreLASTEXITCODE - Ignoruj $LASTEXITCODE
boolean. Wartość domyślna: false.

Jeśli ustawiono wartość false, wiersz if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } jest wykonywany na końcu skryptu. Powoduje to propagację ostatniego kodu zakończenia z zewnętrznego polecenia jako kodu zakończenia programu PowerShell. W przeciwnym razie wiersz nie jest wykonywany na końcu skryptu.

WorkingDirectory - Katalog roboczy
string.

Określa katalog roboczy, w którym jest uruchamiany skrypt.

RunPowershellInParallel - Uruchamianie programu PowerShell równolegle
boolean. Wartość domyślna: true.

Jeśli ustawiono wartość true, uruchamia skrypty programu PowerShell równolegle na maszynach docelowych.

Opcje sterowania zadaniami

Wszystkie zadania mają opcje sterowania oprócz danych wejściowych zadań podrzędnych. Aby uzyskać więcej informacji, zobacz Opcje sterowania i typowe właściwości zadań.

Zmienne wyjściowe

Brak.

Uwagi

To zadanie służy do wykonywania skryptów programu PowerShell na maszynach zdalnych.

To zadanie może uruchamiać zarówno skrypty programu PowerShell, jak i skrypty DSC programu PowerShell:

W przypadku skryptów programu PowerShell na komputerach musi być zainstalowany program PowerShell 2.0 lub nowszy.
W przypadku skryptów DSC programu PowerShell komputery muszą mieć zainstalowaną najnowszą wersję Windows Management Framework. Jest on instalowany domyślnie w Windows 8.1, Windows Server 2012 R2 i kolejnych wersjach.

Wymagania wstępne

To zadanie używa zdalnego zarządzania systemem Windows (WinRM) do uzyskiwania dostępu do lokalnych komputerów fizycznych lub komputerów wirtualnych, które są przyłączone do domeny lub przyłączone do grupy roboczej.

Aby skonfigurować usługę WinRM dla lokalnych komputerów fizycznych lub maszyn wirtualnych

Wykonaj kroki opisane w temacie Przyłączone do domeny

Aby skonfigurować usługę WinRM dla usługi Microsoft Azure Virtual Machines

Usługa Azure Virtual Machines wymaga usługi WinRM do korzystania z protokołu HTTPS. Możesz użyć certyfikatu testowego z podpisem własnym. W takim przypadku agent automatyzacji nie zweryfikuje autentyczności certyfikatu jako wystawionego przez zaufany urząd certyfikacji.

Klasyczny Virtual Machines platformy Azure. Podczas tworzenia klasycznej maszyny wirtualnej na podstawie Azure Portal maszyna wirtualna jest już skonfigurowana dla usługi WinRM za pośrednictwem protokołu HTTPS, a domyślny port 5986 został już otwarty w zaporze i certyfikat z podpisem własnym zainstalowany na maszynie. Dostęp do tych maszyn wirtualnych można uzyskać bez konieczności dalszej konfiguracji. Istniejące klasyczne maszyny wirtualne można również wybrać przy użyciu zadania wdrażania grupy zasobów platformy Azure .
Grupa zasobów platformy Azure. Jeśli masz już grupę zasobów platformy Azure zdefiniowaną w Azure Portal, musisz ją skonfigurować tak, aby korzystała z protokołu HTTPS usługi WinRM. Musisz otworzyć port 5986 w zaporze i zainstalować certyfikat z podpisem własnym.

Aby dynamicznie wdrażać grupy zasobów platformy Azure zawierające maszyny wirtualne, użyj zadania Wdrażania grupy zasobów platformy Azure . To zadanie ma pole wyboru o nazwie Włącz wymagania wstępne wdrożenia. Wybierz tę opcję, aby automatycznie skonfigurować protokół HTTPS usługi WinRM na maszynach wirtualnych, otworzyć port 5986 w zaporze i zainstalować certyfikat testowy. Maszyny wirtualne są następnie gotowe do użycia w zadaniu wdrażania.

Co nowego w tej wersji zadania

Używa programu PSSession i invoke-command do wykonywania komunikacji bezpośredniej na maszynach docelowych.
Dodano obsługę wykonywania skryptów wbudowanych.
Obsługiwane są uwierzytelnianie domyślne i CredSSP.
Dodano opcje obsługi błędów: ErrorActionPreference, ignoreLASTEXITCODE i Fail on Standard Error (Błąd standardowy).

Wymagania

Wymaganie	Opis
Typy potoków	YAML, kompilacja klasyczna, wersja klasyczna
Działa na	Agent, DeploymentGroup
Wymagania	Brak
Możliwości	To zadanie nie spełnia żadnych wymagań dotyczących kolejnych zadań w zadaniu.
Ograniczenia poleceń	Dowolne
Zmienne w formie tabeli settable	Dowolne
Wersja agenta	2.134.0 lub nowsza
Kategoria zadania	Wdrażanie

Udostępnij za pośrednictwem