Invoke-Command
Uruchamia polecenia na komputerach lokalnych i zdalnych.
Składnia
Invoke-Command
[-ScriptBlock] <scriptblock>
[-NoNewScope]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[[-Session] <PSSession[]>]
[-ScriptBlock] <scriptblock>
[-ThrottleLimit <int>]
[-AsJob]
[-HideComputerName]
[-JobName <string>]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[[-Session] <PSSession[]>]
[-FilePath] <string>
[-ThrottleLimit <int>]
[-AsJob]
[-HideComputerName]
[-JobName <string>]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[[-ComputerName] <string[]>]
[-ScriptBlock] <scriptblock>
[-Credential <pscredential>]
[-Port <int>]
[-UseSSL]
[-ConfigurationName <string>]
[-ApplicationName <string>]
[-ThrottleLimit <int>]
[-AsJob]
[-InDisconnectedSession]
[-SessionName <string[]>]
[-HideComputerName]
[-JobName <string>]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-EnableNetworkAccess]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[-CertificateThumbprint <string>]
[<CommonParameters>]
Invoke-Command
[[-ComputerName] <string[]>]
[-FilePath] <string>
[-Credential <pscredential>]
[-Port <int>]
[-UseSSL]
[-ConfigurationName <string>]
[-ApplicationName <string>]
[-ThrottleLimit <int>]
[-AsJob]
[-InDisconnectedSession]
[-SessionName <string[]>]
[-HideComputerName]
[-JobName <string>]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-EnableNetworkAccess]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[[-ConnectionUri] <uri[]>]
[-ScriptBlock] <scriptblock>
[-Credential <pscredential>]
[-ConfigurationName <string>]
[-ThrottleLimit <int>]
[-AsJob]
[-InDisconnectedSession]
[-HideComputerName]
[-JobName <string>]
[-AllowRedirection]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-EnableNetworkAccess]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[-CertificateThumbprint <string>]
[<CommonParameters>]
Invoke-Command
[[-ConnectionUri] <uri[]>]
[-FilePath] <string>
[-Credential <pscredential>]
[-ConfigurationName <string>]
[-ThrottleLimit <int>]
[-AsJob]
[-InDisconnectedSession]
[-HideComputerName]
[-JobName <string>]
[-AllowRedirection]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-EnableNetworkAccess]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[-VMId] <guid[]>
[-ScriptBlock] <scriptblock>
-Credential <pscredential>
[-ConfigurationName <string>]
[-ThrottleLimit <int>]
[-AsJob]
[-HideComputerName]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[-ScriptBlock] <scriptblock>
-Credential <pscredential>
-VMName <string[]>
[-ConfigurationName <string>]
[-ThrottleLimit <int>]
[-AsJob]
[-HideComputerName]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[-VMId] <guid[]>
[-FilePath] <string>
-Credential <pscredential>
[-ConfigurationName <string>]
[-ThrottleLimit <int>]
[-AsJob]
[-HideComputerName]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[-FilePath] <string>
-Credential <pscredential>
-VMName <string[]>
[-ConfigurationName <string>]
[-ThrottleLimit <int>]
[-AsJob]
[-HideComputerName]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[-ScriptBlock] <scriptblock>
-HostName <string[]>
[-Port <int>]
[-AsJob]
[-HideComputerName]
[-JobName <string>]
[-UserName <string>]
[-KeyFilePath <string>]
[-Subsystem <string>]
[-ConnectingTimeout <int>]
[-SSHTransport]
[-Options <hashtable>]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[-ScriptBlock] <scriptblock>
-ContainerId <string[]>
[-ConfigurationName <string>]
[-ThrottleLimit <int>]
[-AsJob]
[-HideComputerName]
[-JobName <string>]
[-RunAsAdministrator]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[-FilePath] <string>
-ContainerId <string[]>
[-ConfigurationName <string>]
[-ThrottleLimit <int>]
[-AsJob]
[-HideComputerName]
[-JobName <string>]
[-RunAsAdministrator]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[-ScriptBlock] <scriptblock>
-SSHConnection <hashtable[]>
[-AsJob]
[-HideComputerName]
[-JobName <string>]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
-FilePath <string>
-HostName <string[]>
[-AsJob]
[-HideComputerName]
[-UserName <string>]
[-KeyFilePath <string>]
[-Subsystem <string>]
[-ConnectingTimeout <int>]
[-SSHTransport]
[-Options <hashtable>]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
-FilePath <string>
-SSHConnection <hashtable[]>
[-AsJob]
[-HideComputerName]
[-RemoteDebug]
[-InputObject <psobject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Opis
Polecenie cmdlet Invoke-Command
uruchamia polecenia na komputerze lokalnym lub zdalnym i zwraca wszystkie dane wyjściowe z poleceń, w tym błędy. Za pomocą jednego polecenia Invoke-Command
można uruchamiać polecenia na wielu komputerach.
Aby uruchomić jedno polecenie na komputerze zdalnym, użyj parametru ComputerName. Aby uruchomić serię powiązanych poleceń, które udostępniają dane, użyj polecenia cmdlet
Można również użyć Invoke-Command
na komputerze lokalnym do uruchomienia bloku skryptu jako polecenia. Program PowerShell uruchamia blok skryptu natychmiast w zakresie podrzędnym bieżącego zakresu.
Przed użyciem Invoke-Command
do uruchamiania poleceń na komputerze zdalnym przeczytaj about_Remote.
Począwszy od programu PowerShell 6.0, można użyć protokołu Secure Shell (SSH), aby nawiązać połączenie z poleceniami i wywoływać je na komputerach zdalnych. Protokół SSH musi być zainstalowany na komputerze lokalnym, a komputer zdalny musi być skonfigurowany przy użyciu punktu końcowego protokołu SSH programu PowerShell. Zaletą sesji zdalnej programu PowerShell opartej na protokole SSH jest to, że działa na wielu platformach (Windows, Linux, macOS). W przypadku sesji opartej na protokole SSH należy użyć parametrów HostName lub SSHConnection w celu określenia komputera zdalnego i odpowiednich informacji o połączeniu. Aby uzyskać więcej informacji na temat konfigurowania komunikacji zdalnej SSH programu PowerShell, zobacz komunikacji zdalnej programu PowerShell za pośrednictwem protokołu SSH.
Niektóre przykłady kodu używają fragmentowania, aby zmniejszyć długość wiersza. Aby uzyskać więcej informacji, zobacz about_Splatting.
Przykłady
Przykład 1. Uruchamianie skryptu na serwerze
W tym przykładzie jest uruchamiany skrypt Test.ps1
na komputerze Server01.
Invoke-Command -FilePath c:\scripts\test.ps1 -ComputerName Server01
Parametr FilePath określa skrypt znajdujący się na komputerze lokalnym. Skrypt jest uruchamiany na komputerze zdalnym, a wyniki są zwracane do komputera lokalnego.
Przykład 2. Uruchamianie polecenia na serwerze zdalnym
W tym przykładzie uruchomiono polecenie Get-Culture
na komputerze zdalnym Server01.
Invoke-Command -ComputerName Server01 -Credential Domain01\User01 -ScriptBlock {
Get-Culture
}
Parametr ComputerName określa nazwę komputera zdalnego. Parametr Credential służy do uruchamiania polecenia w kontekście zabezpieczeń Domain01\User01, użytkownik, który ma uprawnienia do uruchamiania poleceń. Parametr ScriptBlock określa polecenie do uruchomienia na komputerze zdalnym.
W odpowiedzi program PowerShell żąda hasła i metody uwierzytelniania dla konta User01. Następnie uruchamia polecenie na komputerze Server01 i zwraca wynik.
Przykład 3. Uruchamianie polecenia w trwałym połączeniu
Ten przykład uruchamia to samo polecenie Get-Culture
w sesji przy użyciu połączenia trwałego na komputerze zdalnym o nazwie Server02.
$s = New-PSSession -ComputerName Server02 -Credential Domain01\User01
Invoke-Command -Session $s -ScriptBlock { Get-Culture }
Polecenie cmdlet New-PSSession
tworzy sesję na komputerze zdalnym Server02 i zapisuje ją w zmiennej $s
. Zazwyczaj sesję można utworzyć tylko wtedy, gdy uruchamiasz serię poleceń na komputerze zdalnym.
Polecenie cmdlet Invoke-Command
uruchamia polecenie Get-Culture
na serwerze Server02. Parametr sesji
W odpowiedzi program PowerShell uruchamia polecenie w sesji na komputerze Server02.
Przykład 4. Uruchamianie serii poleceń współużytkujących dane za pomocą sesji
W tym przykładzie porównaliśmy efekty używania parametrów ComputerName
Invoke-Command -ComputerName Server02 -ScriptBlock { $p = Get-Process PowerShell }
Invoke-Command -ComputerName Server02 -ScriptBlock { $p.VirtualMemorySize }
$s = New-PSSession -ComputerName Server02
Invoke-Command -Session $s -ScriptBlock { $p = Get-Process PowerShell }
Invoke-Command -Session $s -ScriptBlock { $p.VirtualMemorySize }
17930240
Dwa pierwsze polecenia używają parametru ComputerNameInvoke-Command
do uruchamiania poleceń na komputerze zdalnym Server02. Pierwsze polecenie używa polecenia cmdlet Get-Process
w celu pobrania procesu programu PowerShell na komputerze zdalnym i zapisania go w zmiennej $p
. Drugie polecenie pobiera wartość właściwości VirtualMemorySize procesu programu PowerShell.
W przypadku używania parametru ComputerName program PowerShell tworzy nową sesję do uruchomienia polecenia.
Sesja jest zamykana po zakończeniu wykonywania polecenia. Zmienna $p
została utworzona w jednym połączeniu, ale nie istnieje w połączeniu utworzonym dla drugiego polecenia.
Problem jest rozwiązywany przez utworzenie trwałej sesji na komputerze zdalnym, a następnie uruchomienie obu poleceń w tej samej sesji.
Polecenie cmdlet New-PSSession
tworzy trwałą sesję na komputerze Server02 i zapisuje sesję w zmiennej $s
. Wiersze $p
pozostaje aktywna.
Przykład 5. Wywoływanie polecenia z blokiem skryptu przechowywanym w zmiennej
W tym przykładzie pokazano, jak uruchomić polecenie przechowywane jako blok skryptu w zmiennej. Po zapisaniu bloku skryptu w zmiennej można określić zmienną jako wartość parametru ScriptBlock.
$command = {
Get-WinEvent -LogName PowerShellCore/Operational |
Where-Object -FilterScript { $_.Message -like '*certificate*' }
}
Invoke-Command -ComputerName S1, S2 -ScriptBlock $command
Zmienna $command
przechowuje polecenie Get-WinEvent
sformatowane jako blok skryptu.
Invoke-Command
uruchamia polecenie przechowywane w $command
na komputerach zdalnych S1 i S2.
Przykład 6. Uruchamianie pojedynczego polecenia na kilku komputerach
W tym przykładzie pokazano, jak używać Invoke-Command
do uruchamiania jednego polecenia na wielu komputerach.
$parameters = @{
ComputerName = 'Server01', 'Server02', 'TST-0143', 'localhost'
ConfigurationName = 'MySession.PowerShell'
ScriptBlock = { Get-WinEvent -LogName PowerShellCore/Operational }
}
Invoke-Command @parameters
Parametr ComputerName określa rozdzielaną przecinkami listę nazw komputerów. Lista komputerów zawiera wartość localhost, która reprezentuje komputer lokalny. Parametr ConfigurationName określa konfigurację sesji alternatywnej. Parametr ScriptBlock jest uruchamiany Get-WinEvent
w celu pobrania dzienników zdarzeń programu PowerShellCore/Operational z każdego komputera.
Przykład 7. Pobieranie wersji programu hosta na wielu komputerach
W tym przykładzie jest pobierana wersja programu hosta programu PowerShell uruchomiona na 200 komputerach zdalnych.
$version = Invoke-Command -ComputerName (Get-Content Machines.txt) -ScriptBlock {
(Get-Host).Version
}
Ponieważ jest uruchamiane tylko jedno polecenie, nie trzeba tworzyć trwałych połączeń z każdym z komputerów. Zamiast tego polecenie używa parametru ComputerName, aby wskazać komputery. Aby określić komputery, używa polecenia cmdlet Get-Content
do pobrania zawartości pliku Machine.txt, pliku nazw komputerów.
Polecenie cmdlet Invoke-Command
uruchamia polecenie Get-Host
na komputerach zdalnych. Używa notacji kropkowej, aby uzyskać właściwość Version hosta programu PowerShell.
Te polecenia są uruchamiane pojedynczo. Po zakończeniu wykonywania poleceń dane wyjściowe poleceń ze wszystkich komputerów są zapisywane w zmiennej $version
. Dane wyjściowe zawierają nazwę komputera, z którego pochodzą dane.
Przykład 8. Uruchamianie zadania w tle na kilku komputerach zdalnych
W tym przykładzie uruchomiono polecenie na dwóch komputerach zdalnych. Polecenie Invoke-Command
używa parametru AsJob, aby polecenie było uruchamiane jako zadanie w tle. Polecenia są uruchamiane na komputerach zdalnych, ale zadanie istnieje na komputerze lokalnym. Wyniki są przesyłane na komputer lokalny.
$s = New-PSSession -ComputerName Server01, Server02
Invoke-Command -Session $s -ScriptBlock { Get-EventLog system } -AsJob
Id Name State HasMoreData Location Command
--- ---- ----- ----- ----------- ---------------
1 Job1 Running True Server01,Server02 Get-EventLog system
$j = Get-Job
$j | Format-List -Property *
HasMoreData : True
StatusMessage :
Location : Server01,Server02
Command : Get-EventLog system
JobStateInfo : Running
Finished : System.Threading.ManualResetEvent
InstanceId : e124bb59-8cb2-498b-a0d2-2e07d4e030ca
Id : 1
Name : Job1
ChildJobs : {Job2, Job3}
Output : {}
Error : {}
Progress : {}
Verbose : {}
Debug : {}
Warning : {}
StateChanged :
$results = $j | Receive-Job
Polecenie cmdlet New-PSSession
tworzy sesje na komputerach zdalnych Server01 i Server02. Polecenie cmdlet Invoke-Command
uruchamia zadanie w tle w każdej sesji. Polecenie używa parametru AsJob, aby uruchomić polecenie jako zadanie w tle. To polecenie zwraca obiekt zadania, który zawiera dwa obiekty podrzędne zadania, jeden dla każdego z zadań uruchamianych na dwóch komputerach zdalnych.
Polecenie Get-Job
zapisuje obiekt zadania w zmiennej $j
. Zmienna $j
jest następnie potokowana do polecenia cmdlet Format-List
w celu wyświetlenia wszystkich właściwości obiektu zadania na liście. Ostatnie polecenie pobiera wyniki zadań. Potokuje obiekt zadania w $j
do polecenia cmdlet Receive-Job
i przechowuje wyniki w zmiennej $results
.
Przykład 9: uwzględnianie zmiennych lokalnych w poleceniu uruchamianym na komputerze zdalnym
W tym przykładzie pokazano, jak uwzględnić wartości zmiennych lokalnych w poleceniu uruchamianym na komputerze zdalnym. Polecenie używa modyfikatora zakresu Using
do identyfikowania zmiennej lokalnej w poleceniu zdalnym. Domyślnie wszystkie zmienne są definiowane w sesji zdalnej. Modyfikator Using
zakresu został wprowadzony w programie PowerShell 3.0. Aby uzyskać więcej informacji o modyfikatorze zakresu Using
, zobacz about_Remote_Variables i about_Scopes.
$Log = 'PowerShellCore/Operational'
Invoke-Command -ComputerName Server01 -ScriptBlock {
Get-WinEvent -LogName $Using:Log -MaxEvents 10
}
Zmienna $Log
przechowuje nazwę dziennika zdarzeń, PowerShellCore/Operational. Polecenie cmdlet Invoke-Command
uruchamia Get-WinEvent
na serwerze Server01, aby pobrać dziesięć najnowszych zdarzeń z dziennika zdarzeń. Wartość parametru LogName to zmienna $Log
poprzedzona modyfikatorem zakresu Using
wskazująca, że została utworzona w sesji lokalnej, a nie w sesji zdalnej.
Przykład 10: Ukrywanie nazwy komputera
W tym przykładzie pokazano efekt użycia parametru HideComputerNameInvoke-Command
.
HideComputerName nie zmienia obiektu zwracany przez to polecenie cmdlet. Zmienia tylko ekran. Nadal możesz użyć poleceń cmdlet format
Invoke-Command -ComputerName S1, S2 -ScriptBlock { Get-Process PowerShell }
PSComputerName Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
-------------- ------- ------ ----- ----- ----- ------ -- -----------
S1 575 15 45100 40988 200 4.68 1392 PowerShell
S2 777 14 35100 30988 150 3.68 67 PowerShell
Invoke-Command -ComputerName S1, S2 -HideComputerName -ScriptBlock {
Get-Process PowerShell
}
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
575 15 45100 40988 200 4.68 1392 PowerShell
777 14 35100 30988 150 3.68 67 PowerShell
Dwa pierwsze polecenia używają Invoke-Command
do uruchomienia Get-Process
polecenia dla procesu programu PowerShell. Dane wyjściowe pierwszego polecenia zawierają właściwość PsComputerName zawierającą nazwę komputera, na którym uruchomiono polecenie. Dane wyjściowe drugiego polecenia, które używa HideComputerName, nie zawierają kolumny PsComputerName.
Przykład 11: używanie słowa kluczowego Param w bloku skryptu
Słowo kluczowe Param
i parametr ArgumentList są używane do przekazywania wartości zmiennych do nazwanych parametrów w bloku skryptu. W tym przykładzie są wyświetlane nazwy plików rozpoczynające się literą a
i mają rozszerzenie .pdf
.
Aby uzyskać więcej informacji na temat słowa kluczowego Param
, zobacz about_Language_Keywords.
$parameters = @{
ComputerName = 'Server01'
ScriptBlock = {
Param ($param1, $param2)
Get-ChildItem -Name $param1 -Include $param2
}
ArgumentList = 'a*', '*.pdf'
}
Invoke-Command @parameters
aa.pdf
ab.pdf
ac.pdf
az.pdf
Invoke-Command
używa parametru ScriptBlock, który definiuje dwie zmienne, $param1
i $param2
.
Get-ChildItem
używa nazwanych parametrów, Name i Include z nazwami zmiennych.
ArgumentList przekazuje wartości do zmiennych.
Przykład 12: używanie zmiennej automatycznej $args w bloku skryptu
Zmienna automatyczna $args
i ArgumentList parametr są używane do przekazywania wartości tablicy do pozycji parametrów w bloku skryptu. W tym przykładzie jest wyświetlana zawartość katalogu serwera .txt
plików. Parametr ścieżki
Aby uzyskać więcej informacji na temat zmiennej $args
, zobacz about_Automatic_Variables
$parameters = @{
ComputerName = 'Server01'
ScriptBlock = { Get-ChildItem $args[0] $args[1] }
ArgumentList = 'C:\Test', '*.txt*'
}
Invoke-Command @parameters
Directory: C:\Test
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 6/12/2019 15:15 128 alog.txt
-a--- 7/27/2019 15:16 256 blog.txt
-a--- 9/28/2019 17:10 64 zlog.txt
Invoke-Command
używa parametru ScriptBlock i Get-ChildItem
określa wartości tablicy $args[0]
i $args[1]
. ArgumentList
Przykład 13: Uruchamianie skryptu na wszystkich komputerach wymienionych w pliku tekstowym
W tym przykładzie użyto polecenia cmdlet Invoke-Command
do uruchomienia skryptu Sample.ps1
na wszystkich komputerach wymienionych w pliku Servers.txt
. Polecenie używa parametru FilePath w celu określenia pliku skryptu. To polecenie umożliwia uruchomienie skryptu na komputerach zdalnych, nawet jeśli plik skryptu nie jest dostępny dla komputerów zdalnych.
$parameters = @{
ComputerName = (Get-Content Servers.txt)
FilePath = 'C:\Scripts\Sample.ps1'
ArgumentList = 'Process', 'Service'
}
Invoke-Command @parameters
Po przesłaniu polecenia zawartość pliku Sample.ps1
jest kopiowana do bloku skryptu, a blok skryptu jest uruchamiany na każdym komputerze zdalnym. Ta procedura jest równoważna użyciu parametru ScriptBlock w celu przesłania zawartości skryptu.
Przykład 14: Uruchamianie polecenia na komputerze zdalnym przy użyciu identyfikatora URI
W tym przykładzie pokazano, jak uruchomić polecenie na komputerze zdalnym zidentyfikowanym przez identyfikator URI (Uniform Resource Identifier). W tym konkretnym przykładzie jest uruchamiane polecenie Set-Mailbox
na zdalnym serwerze Exchange.
$LiveCred = Get-Credential
$parameters = @{
ConfigurationName = 'Microsoft.Exchange'
ConnectionUri = 'https://ps.exchangelabs.com/PowerShell'
Credential = $LiveCred
Authentication = 'Basic'
ScriptBlock = { Set-Mailbox Dan -DisplayName 'Dan Park' }
}
Invoke-Command @parameters
Pierwszy wiersz używa polecenia cmdlet Get-Credential
do przechowywania poświadczeń identyfikatora Windows Live w zmiennej $LiveCred
. Program PowerShell monituje użytkownika o wprowadzenie poświadczeń identyfikatora Windows Live ID.
Zmienna $parameters
to tabela skrótów zawierająca parametry, które mają zostać przekazane do polecenia cmdlet Invoke-Command
. Polecenie cmdlet Invoke-Command
uruchamia polecenie Set-Mailbox
przy użyciu konfiguracji sesji Microsoft.Exchange. Parametr ConnectionURI określa adres URL punktu końcowego serwera Exchange. Parametr Credential określa poświadczenia przechowywane w zmiennej $LiveCred
. Parametr AuthenticationMechanism określa użycie uwierzytelniania podstawowego. Parametr ScriptBlock określa blok skryptu zawierający polecenie .
Przykład 15. Użyj opcji sesji
W tym przykładzie pokazano, jak utworzyć i użyć parametru SessionOption.
$so = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
$parameters = @{
ComputerName = 'server01'
UseSSL = $true
ScriptBlock = { Get-HotFix }
SessionOption = $so
Credential = 'server01\user01'
}
Invoke-Command @parameters
Polecenie cmdlet New-PSSessionOption
tworzy obiekt opcji sesji, który powoduje, że zdalny koniec nie weryfikuje urzędu certyfikacji, nazwy kanonicznej i list odwołania podczas oceniania przychodzącego połączenia HTTPS. Obiekt SessionOption jest zapisywany w zmiennej $so
.
Nuta
Wyłączenie tych testów jest wygodne w przypadku rozwiązywania problemów, ale oczywiście nie jest bezpieczne.
Polecenie cmdlet Invoke-Command
uruchamia zdalnie polecenie Get-HotFix
. Parametr SessionOption otrzymuje zmienną $so
.
Przykład 16: Zarządzanie przekierowaniem identyfikatora URI w poleceniu zdalnym
W tym przykładzie pokazano, jak używać parametrów AllowRedirection i SessionOption do zarządzania przekierowaniem identyfikatora URI w zdalnym poleceniu.
$max = New-PSSessionOption -MaximumRedirection 1
$parameters = @{
ConnectionUri = 'https://ps.exchangelabs.com/PowerShell'
ScriptBlock = { Get-Mailbox dan }
AllowRedirection = $true
SessionOption = $max
}
Invoke-Command @parameters
Polecenie cmdlet New-PSSessionOption
tworzy obiekt PSSessionOption zapisany w zmiennej $max
. Polecenie używa parametru MaximumRedirection, aby ustawić właściwość MaximumConnectionRedirectionCount obiektu PSSessionOption na 1.
Polecenie cmdlet Invoke-Command
uruchamia polecenie Get-Mailbox
na zdalnym serwerze Microsoft Exchange Server. Parametr AllowRedirection zapewnia jawne uprawnienia do przekierowywania połączenia do alternatywnego punktu końcowego. Parametr SessionOption używa obiektu sesji przechowywanego w zmiennej $max
.
W związku z tym, jeśli komputer zdalny określony przez Identyfikator ConnectionURI zwraca komunikat przekierowania, program PowerShell przekierowuje połączenie, ale jeśli nowy obiekt docelowy zwróci inny komunikat przekierowania, wartość liczby przekierowań 1 zostanie przekroczona, a Invoke-Command
zwróci błąd niepowodujący zakończenia.
Przykład 17: Uzyskiwanie dostępu do udziału sieciowego w sesji zdalnej
W tym przykładzie pokazano, jak uzyskać dostęp do udziału sieciowego z sesji zdalnej. Do zademonstrowania przykładu służą trzy komputery. Serwer01 jest komputerem lokalnym, Server02 jest komputerem zdalnym, a Net03 zawiera udział sieciowy. Serwer01 nawiązuje połączenie z serwerem Server02, a następnie serwer02 wykonuje drugi przeskok do net03 w celu uzyskania dostępu do udziału sieciowego. Aby uzyskać więcej informacji o tym, jak komunikacja zdalna programu PowerShell obsługuje przeskoki między komputerami, zobacz Tworzenie drugiego przeskoku w programie PowerShell remoting.
Wymagane delegowanie dostawcy obsługi zabezpieczeń poświadczeń (CredSSP) jest włączone w ustawieniach klienta na komputerze lokalnym i w ustawieniach usługi na komputerze zdalnym. Aby uruchomić polecenia w tym przykładzie, musisz być członkiem grupy administratorzy
Enable-WSManCredSSP -Role Client -DelegateComputer Server02
$s = New-PSSession Server02
Invoke-Command -Session $s -ScriptBlock { Enable-WSManCredSSP -Role Server -Force }
$parameters = @{
ComputerName = 'Server02'
ScriptBlock = { Get-Item \\Net03\Scripts\LogFiles.ps1 }
Authentication = 'CredSSP'
Credential = 'Domain01\Admin01'
}
Invoke-Command @parameters
Polecenie cmdlet Enable-WSManCredSSP
umożliwia delegowanie CredSSP z komputera lokalnego Server01 do komputera zdalnego Server02. Parametr roli
Polecenie cmdlet Invoke-Command
używa zmiennej $s
do nawiązywania połączenia z komputerem zdalnym Server02. Parametr ScriptBlock jest uruchamiany Enable-WSManCredSSP
na komputerze zdalnym. Parametr roli
Zmienna $parameters
zawiera wartości parametrów do nawiązania połączenia z udziałem sieciowym. Polecenie cmdlet Invoke-Command
uruchamia polecenie Get-Item
w sesji w $s
. To polecenie pobiera skrypt z udziału sieciowego \\Net03\Scripts
. Polecenie używa parametru Authentication
Przykład 18: Uruchamianie skryptów na wielu komputerach zdalnych
W tym przykładzie skrypt jest uruchamiany na ponad stu komputerach. Aby zminimalizować wpływ na komputer lokalny, łączy się z każdym komputerem, uruchamia skrypt, a następnie rozłącza się z każdym komputerem. Skrypt nadal działa w rozłączonych sesjach.
$parameters = @{
ComputerName = (Get-Content -Path C:\Test\Servers.txt)
InDisconnectedSession = $true
FilePath = '\\Scripts\Public\ConfigInventory.ps1'
SessionOption = @{
OutputBufferingMode = 'Drop'
IdleTimeout = [timespan]::FromHours(12)
}
}
Invoke-Command @parameters
Polecenie używa Invoke-Command
do uruchomienia skryptu. Wartość parametru ComputerName to polecenie Get-Content
, które pobiera nazwy komputerów zdalnych z pliku tekstowego. Parametr InDisconnectedSession rozłącza sesje natychmiast po uruchomieniu polecenia. Wartość parametru FilePath jest skryptem, który Invoke-Command
działa na każdym komputerze.
Wartość SessionOption jest tabelą skrótów. Wartość
Aby uzyskać wyniki poleceń i skryptów uruchamianych w rozłączonych sesjach, użyj polecenia cmdlet Receive-PSSession
.
Przykład 19: Uruchamianie polecenia na komputerze zdalnym przy użyciu protokołu SSH
W tym przykładzie pokazano, jak uruchomić polecenie na komputerze zdalnym przy użyciu protokołu Secure Shell (SSH). Jeśli na komputerze zdalnym skonfigurowano protokół SSH w celu wyświetlenia monitu o podanie haseł, zostanie wyświetlony monit o hasło. W przeciwnym razie konieczne będzie użycie uwierzytelniania użytkowników opartego na kluczach SSH.
Invoke-Command -HostName UserA@LinuxServer01 -ScriptBlock { Get-MailBox * }
Przykład 20: Uruchamianie polecenia na komputerze zdalnym przy użyciu protokołu SSH i określanie klucza uwierzytelniania użytkownika
W tym przykładzie pokazano, jak uruchomić polecenie na komputerze zdalnym przy użyciu protokołu SSH i określić plik klucza na potrzeby uwierzytelniania użytkownika. Nie zostanie wyświetlony monit o podanie hasła, chyba że uwierzytelnianie klucza zakończy się niepowodzeniem, a komputer zdalny jest skonfigurowany do zezwalania na podstawowe uwierzytelnianie hasłem.
$parameters = @{
HostName = 'UserA@LinuxServer01'
ScriptBlock = { Get-MailBox * }
KeyFilePath = '/UserA/UserAKey_rsa'
}
Invoke-Command
Przykład 21: Uruchamianie pliku skryptu na wielu komputerach zdalnych przy użyciu protokołu SSH jako zadania
W tym przykładzie pokazano, jak uruchomić plik skryptu na wielu komputerach zdalnych przy użyciu protokołu SSH i zestawu parametrów SSHConnection. Parametr SSHConnection przyjmuje tablicę tabel skrótów zawierających informacje o połączeniu dla każdego komputera. W tym przykładzie wymagane jest, aby docelowe komputery zdalne miały skonfigurowany protokół SSH do obsługi uwierzytelniania użytkowników opartego na kluczach.
$sshConnections = @(
@{
HostName = "WinServer1"
UserName = "Domain\UserA"
KeyFilePath = "C:\Users\UserA\id_rsa"
}
@{
HostName = "UserB@LinuxServer5"
KeyFilePath = "/Users/UserB/id_rsa"
}
)
$results = Invoke-Command -FilePath c:\Scripts\GetInfo.ps1 -SSHConnection $sshConnections
Przykład 22: Nawiązywanie połączenia z zdalną sesją SSH przy użyciu opcji SSH
W tym przykładzie pokazano, jak uruchomić plik skryptu na zdalnym komputerze z systemem Linux przy użyciu opcji SSH. Parametr Options przyjmuje tabelę skrótów wartości, które są przekazywane jako opcje do bazowego polecenia ssh
nawiązane połączenie z systemem zdalnym.
$options = @{
Port=22
User = 'UserB'
Host = 'LinuxServer5'
}
$results = Invoke-Command -FilePath c:\Scripts\CollectEvents.ps1 -KeyFilePath '/Users/UserB/id_rsa' -Options $options
Parametry
-AllowRedirection
Umożliwia przekierowanie tego połączenia do alternatywnego identyfikatora URI (Uniform Resource Identifier).
W przypadku używania parametru identyfikatora ConnectionURI
Możesz również ograniczyć liczbę przekierowań połączenia, zmieniając wartość opcji MaximumConnectionRedirectionCount sesji. Użyj parametru MaximumRedirection polecenia cmdlet New-PSSessionOption
lub ustaw właściwość MaximumConnectionRedirectionCount zmiennej preferencji $PSSessionOption
. Wartość domyślna to 5.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-ApplicationName
Określa segment nazwy aplikacji identyfikatora URI połączenia. Użyj tego parametru, aby określić nazwę aplikacji, jeśli nie używasz parametru ConnectionURI w poleceniu .
Wartość domyślna to wartość zmiennej $PSSessionApplicationName
preferencji na komputerze lokalnym. Jeśli ta zmienna preferencji nie jest zdefiniowana, wartość domyślna to WSMAN. Ta wartość jest odpowiednia dla większości zastosowań. Aby uzyskać więcej informacji, zobacz about_Preference_Variables.
Usługa WinRM używa nazwy aplikacji, aby wybrać odbiornik do obsługi żądania połączenia. Wartość tego parametru powinna być zgodna z wartością właściwości URLPrefix odbiornika na komputerze zdalnym.
Typ: | String |
Position: | Named |
Domyślna wartość: | $PSSessionApplicationName if set on the local computer, otherwise WSMAN |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | True |
Akceptowanie symboli wieloznacznych: | False |
-ArgumentList
Dostarcza wartości parametrów dla skryptblock. Parametry w bloku skryptu są przekazywane według pozycji z wartości tablicy dostarczonej do ArgumentList. Jest to nazywaneplatting tablicy. Aby uzyskać więcej informacji na temat zachowania argumentlist, zobacz about_Splatting.
Typ: | Object[] |
Aliasy: | Args |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-AsJob
Wskazuje, że to polecenie cmdlet uruchamia polecenie jako zadanie w tle na komputerze zdalnym. Użyj tego parametru, aby uruchomić polecenia, które zajmują dużo czasu.
Gdy używasz parametru AsJob, polecenie zwraca obiekt reprezentujący zadanie, a następnie wyświetla wiersz polecenia. Możesz kontynuować pracę w sesji, gdy zadanie zostanie zakończone. Aby zarządzać zadaniem, użyj poleceń cmdlet *-Job
. Aby uzyskać wyniki zadania, użyj polecenia cmdlet Receive-Job
.
Parametr AsJob przypomina polecenie cmdlet Invoke-Command
do zdalnego uruchamiania polecenia cmdlet Start-Job
. Jednak przy AsJobzadanie jest tworzone na komputerze lokalnym, mimo że zadanie jest uruchamiane na komputerze zdalnym. Wyniki zadania zdalnego są automatycznie zwracane do komputera lokalnego.
Aby uzyskać więcej informacji na temat zadań w tle programu PowerShell, zobacz about_Jobs i about_Remote_Jobs.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-Authentication
Określa mechanizm używany do uwierzytelniania poświadczeń użytkownika. Uwierzytelnianie CredSSP jest dostępne tylko w systemach Windows Vista, Windows Server 2008 i nowszych wersjach systemu operacyjnego Windows.
Dopuszczalne wartości tego parametru są następujące:
- Domyślny
- Podstawowy
- Credssp
- Trawić
- Kerberos
- Negocjować
- NegotiateWithImplicitCredential
Wartość domyślna to Wartość domyślna.
Aby uzyskać więcej informacji na temat wartości tego parametru, zobacz AuthenticationMechanism Enumeration.
Ostrożność
Uwierzytelnianie dostawcy obsługi zabezpieczeń poświadczeń (CredSSP), w którym poświadczenia użytkownika są przekazywane do komputera zdalnego do uwierzytelnienia, jest przeznaczone dla poleceń wymagających uwierzytelniania w więcej niż jednym zasobie, takich jak uzyskiwanie dostępu do zdalnego udziału sieciowego. Ten mechanizm zwiększa ryzyko bezpieczeństwa operacji zdalnej. W przypadku naruszenia zabezpieczeń komputera zdalnego poświadczenia przekazywane do niego mogą służyć do kontrolowania sesji sieciowej. Aby uzyskać więcej informacji, zobacz Credential Security Support Provider.
Typ: | AuthenticationMechanism |
Dopuszczalne wartości: | Basic, Default, Credssp, Digest, Kerberos, Negotiate, NegotiateWithImplicitCredential |
Position: | Named |
Domyślna wartość: | Default |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-CertificateThumbprint
Określa certyfikat cyfrowego klucza publicznego (X509) konta użytkownika, które ma uprawnienia do nawiązywania połączenia z rozłączonej sesji. Wprowadź odcisk palca certyfikatu.
Certyfikaty są używane w uwierzytelnianiu opartym na certyfikatach klienta. Mogą być mapowane tylko na konta użytkowników lokalnych i nie działają z kontami domeny.
Aby uzyskać odcisk palca certyfikatu, użyj polecenia Get-Item
lub Get-ChildItem
w dysku Certyfikat programu PowerShell.
Typ: | String |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-ComputerName
Określa komputery, na których jest uruchamiane polecenie. Wartość domyślna to komputer lokalny.
W przypadku używania parametru ComputerName program PowerShell tworzy tymczasowe połączenie, które jest używane tylko do uruchamiania określonego polecenia, a następnie jest zamykane. Jeśli potrzebujesz połączenia trwałego, użyj parametru Session.
Wpisz nazwę NETBIOS, adres IP lub w pełni kwalifikowaną nazwę domeny co najmniej jednego komputera na liście rozdzielanej przecinkami. Aby określić komputer lokalny, wpisz nazwę komputera, localhost lub kropkę (.
).
Aby użyć adresu IP w wartości ComputerName, polecenie musi zawierać parametr Credential. Komputer musi być skonfigurowany do transportu HTTPS lub adres IP komputera zdalnego musi być uwzględniony w
W systemie Windows Vista i nowszych wersjach systemu operacyjnego Windows, aby uwzględnić komputer lokalny w wartości ComputerName, należy uruchomić program PowerShell przy użyciu Uruchom jako administrator opcji.
Typ: | String[] |
Aliasy: | Cn |
Position: | 0 |
Domyślna wartość: | Local computer |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-ConfigurationName
Określa konfigurację sesji, która jest używana dla nowej PSSession.
Wprowadź nazwę konfiguracji lub w pełni kwalifikowany identyfikator URI zasobu dla konfiguracji sesji. Jeśli określisz tylko nazwę konfiguracji, następujący identyfikator URI schematu jest poprzedzany: http://schemas.microsoft.com/PowerShell
.
W przypadku używania z protokołem SSH ten parametr określa podsystem do użycia na obiekcie docelowym zgodnie z definicją w sshd_config
. Wartością domyślną protokołu SSH jest podsystem powershell
.
Konfiguracja sesji dla sesji znajduje się na komputerze zdalnym. Jeśli określona konfiguracja sesji nie istnieje na komputerze zdalnym, polecenie zakończy się niepowodzeniem.
Wartość domyślna to wartość zmiennej $PSSessionConfigurationName
preferencji na komputerze lokalnym. Jeśli ta zmienna preferencji nie jest ustawiona, wartość domyślna to Microsoft.PowerShell. Aby uzyskać więcej informacji, zobacz about_Preference_Variables.
Typ: | String |
Position: | Named |
Domyślna wartość: | $PSSessionConfigurationName if set on the local computer, otherwise Microsoft.PowerShell |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | True |
Akceptowanie symboli wieloznacznych: | False |
-ConnectingTimeout
Określa czas w milisekundach dozwolony do ukończenia początkowego połączenia SSH. Jeśli połączenie nie zostanie ukończone w określonym czasie, zostanie zwrócony błąd.
Ten parametr został wprowadzony w programie PowerShell 7.2
Typ: | Int32 |
Position: | Named |
Domyślna wartość: | Unlimited |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-ConnectionUri
Określa jednolity identyfikator zasobu (URI), który definiuje punkt końcowy połączenia sesji. Identyfikator URI musi być w pełni kwalifikowany.
Format tego ciągu jest następujący:
<Transport>://<ComputerName>:<Port>/<ApplicationName>
Wartość domyślna jest następująca:
http://localhost:5985/WSMAN
Jeśli nie określisz identyfikatora URI połączenia, możesz użyć UseSSL i parametrów Port, aby określić wartości identyfikatora URI połączenia.
Prawidłowe wartości segmentu Transport identyfikatora URI to HTTP i HTTPS. Jeśli określisz identyfikator URI połączenia z segmentem Transport, ale nie określisz portu, sesja zostanie utworzona przy użyciu portów standardów: 80 dla protokołu HTTP i 443 dla protokołu HTTPS. Aby użyć domyślnych portów komunikacji zdalnej programu PowerShell, określ port 5985 dla protokołu HTTP lub 5986 dla protokołu HTTPS.
Jeśli komputer docelowy przekierowuje połączenie do innego identyfikatora URI, program PowerShell uniemożliwia przekierowanie, chyba że użyjesz parametru AllowRedirection w poleceniu .
Typ: | Uri[] |
Aliasy: | URI, CU |
Position: | 0 |
Domyślna wartość: | http://localhost:5985/WSMAN |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-ContainerId
Określa tablicę identyfikatorów kontenerów.
Typ: | String[] |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | True |
Akceptowanie danych wejściowych potoku: | True |
Akceptowanie symboli wieloznacznych: | False |
-Credential
Określa konto użytkownika, które ma uprawnienia do wykonania tej akcji. Wartość domyślna to bieżący użytkownik.
Wpisz nazwę użytkownika, taką jak User01Get-Credential
cmdlet. Jeśli wpiszesz nazwę użytkownika, zostanie wyświetlony monit o wprowadzenie hasła.
Poświadczenia są przechowywane w obiekcie PSCredential , a hasło jest przechowywane jako secureString.
Nuta
Aby uzyskać więcej informacji na temat ochrony danych SecureString , zobacz Jak bezpieczny jest protokół SecureString?.
Typ: | PSCredential |
Position: | Named |
Domyślna wartość: | Current user |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | True |
Akceptowanie symboli wieloznacznych: | False |
-EnableNetworkAccess
Wskazuje, że to polecenie cmdlet dodaje interakcyjny token zabezpieczający do sesji sprzężenia zwrotnego. Token interaktywny umożliwia uruchamianie poleceń w sesji sprzężenia zwrotnego, które pobierają dane z innych komputerów. Można na przykład uruchomić polecenie w sesji, która kopiuje pliki XML z komputera zdalnego do komputera lokalnego.
Sesja sprzężenia zwrotnego to pssession, który pochodzi i kończy się na tym samym komputerze. Aby utworzyć sesję sprzężenia zwrotnego, pomiń parametr ComputerName lub ustaw jego wartość na kropkę (.
), localhost lub nazwę komputera lokalnego.
Domyślnie sesje sprzężenia zwrotnego są tworzone przy użyciu tokenu sieciowego, który może nie zapewniać wystarczających uprawnień do uwierzytelniania na komputerach zdalnych.
Parametr EnableNetworkAccess jest skuteczny tylko w sesjach sprzężenia zwrotnego. Jeśli używasz EnableNetworkAccess podczas tworzenia sesji na komputerze zdalnym, polecenie zakończy się pomyślnie, ale parametr zostanie zignorowany.
Dostęp zdalny można zezwolić na dostęp zdalny w sesji sprzężenia zwrotnego przy użyciu wartości CredSSP parametru Authentication, który deleguje poświadczenia sesji do innych komputerów.
Aby chronić komputer przed złośliwym dostępem, rozłączone sesje sprzężenia zwrotnego z tokenami interaktywnymi, które są tworzone przy użyciu EnableNetworkAccess, można ponownie połączyć tylko z komputerem, na którym została utworzona sesja. Rozłączone sesje korzystające z uwierzytelniania CredSSP można ponownie połączyć z innymi komputerami. Aby uzyskać więcej informacji, zobacz Disconnect-PSSession
.
Ten parametr został wprowadzony w programie PowerShell 3.0.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-FilePath
Określa skrypt lokalny, który to polecenie cmdlet jest uruchamiane na co najmniej jednym komputerze zdalnym. Wprowadź ścieżkę i nazwę pliku skryptu lub potok ścieżkę skryptu do Invoke-Command
. Skrypt musi istnieć na komputerze lokalnym lub w katalogu, do którego komputer lokalny może uzyskać dostęp. Użyj ArgumentList, aby określić wartości parametrów w skrycie.
W przypadku użycia tego parametru program PowerShell konwertuje zawartość określonego pliku skryptu na blok skryptu, przesyła blok skryptu na komputer zdalny i uruchamia go na komputerze zdalnym.
Typ: | String |
Aliasy: | PSPath |
Position: | 1 |
Domyślna wartość: | None |
Wymagane: | True |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-HideComputerName
Wskazuje, że to polecenie cmdlet pomija nazwę komputera każdego obiektu z wyświetlania danych wyjściowych. Domyślnie nazwa komputera, który wygenerował obiekt, jest wyświetlana na ekranie.
Ten parametr ma wpływ tylko na wyświetlanie danych wyjściowych. Nie zmienia obiektu.
Typ: | SwitchParameter |
Aliasy: | HCN |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-HostName
Określa tablicę nazw komputerów dla połączenia opartego na protokole Secure Shell (SSH). Jest to podobne do parametru ComputerName z tą różnicą, że połączenie z komputerem zdalnym jest wykonywane przy użyciu protokołu SSH, a nie windows WinRM.
Ten parametr został wprowadzony w programie PowerShell 6.0.
Typ: | String[] |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | True |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-InDisconnectedSession
Wskazuje, że to polecenie cmdlet uruchamia polecenie lub skrypt w rozłączonej sesji.
Jeśli używasz parametru InDisconnectedSession, Invoke-Command
tworzy sesję trwałą na każdym komputerze zdalnym, uruchamia polecenie określone przez parametr ScriptBlock lub FilePath, a następnie rozłącza się z sesją. Polecenia są nadal uruchamiane w rozłączonych sesjach.
InDisconnectedSession umożliwia uruchamianie poleceń bez obsługi połączenia z sesjami zdalnymi. Ponieważ sesja jest rozłączona przed zwróceniem jakichkolwiek wyników, InDisconnectedSession upewnia się, że wszystkie wyniki polecenia są zwracane do ponownie połączonej sesji, zamiast dzielenia między sesjami.
Nie można użyć InDisconnectedSession z parametrem Session lub parametrem AsJob.
Polecenia korzystające z InDisconnectedSession zwracają obiekt PSSession, który reprezentuje rozłączonej sesji. Nie zwracają danych wyjściowych polecenia. Aby nawiązać połączenie z rozłączną sesją, użyj poleceń cmdlet Connect-PSSession
lub Receive-PSSession
. Aby uzyskać wyniki poleceń uruchomionych w sesji, użyj polecenia cmdlet Receive-PSSession
. Aby uruchomić polecenia, które generują dane wyjściowe w rozłączonej sesji, ustaw wartość OutputBufferingMode sesji, aby Drop. Jeśli zamierzasz nawiązać połączenie z odłączonej sesji, ustaw limit czasu bezczynności w sesji, aby zapewnić wystarczający czas na nawiązanie połączenia przed usunięciem sesji.
Możesz ustawić tryb buforowania danych wyjściowych i limit czasu bezczynności w parametrze SessionOption lub w zmiennej preferencji $PSSessionOption
. Aby uzyskać więcej informacji na temat opcji sesji, zobacz New-PSSessionOption
i about_Preference_Variables.
Aby uzyskać więcej informacji na temat funkcji Rozłączone sesje, zobacz about_Remote_Disconnected_Sessions.
Ten parametr został wprowadzony w programie PowerShell 3.0.
Typ: | SwitchParameter |
Aliasy: | Disconnected |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-InputObject
Określa dane wejściowe polecenia . Wprowadź zmienną zawierającą obiekty lub wpisz polecenie lub wyrażenie, które pobiera obiekty.
W przypadku używania parametru InputObject użyj zmiennej automatycznej $Input
w wartości parametru ScriptBlock do reprezentowania obiektów wejściowych.
Typ: | PSObject |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | True |
Akceptowanie symboli wieloznacznych: | False |
-JobName
Określa przyjazną nazwę zadania w tle. Domyślnie zadania mają nazwę Job<n>
, gdzie <n>
jest liczbą porządkową.
Jeśli używasz parametru JobName w poleceniu, polecenie jest uruchamiane jako zadanie, a Invoke-Command
zwraca obiekt zadania, nawet jeśli w poleceniu nie zostanie uwzględniony asjob.
Aby uzyskać więcej informacji na temat zadań w tle programu PowerShell, zobacz about_Jobs.
Typ: | String |
Position: | Named |
Domyślna wartość: | Job<n> |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-KeyFilePath
Określa ścieżkę pliku klucza używaną przez protokół Secure Shell (SSH) do uwierzytelniania użytkownika na komputerze zdalnym.
Protokół SSH umożliwia uwierzytelnianie użytkowników za pośrednictwem kluczy prywatnych i publicznych jako alternatywę dla podstawowego uwierzytelniania haseł. Jeśli komputer zdalny jest skonfigurowany do uwierzytelniania za pomocą klucza, ten parametr może służyć do podania klucza identyfikującego użytkownika.
Ten parametr został wprowadzony w programie PowerShell 6.0.
Typ: | String |
Aliasy: | IdentityFilePath |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-NoNewScope
Wskazuje, że to polecenie cmdlet uruchamia określone polecenie w bieżącym zakresie. Domyślnie Invoke-Command
uruchamia polecenia we własnym zakresie.
Ten parametr jest prawidłowy tylko w poleceniach uruchamianych w bieżącej sesji, czyli polecenia pomijające parametry ComputerName i Sesja.
Ten parametr został wprowadzony w programie PowerShell 3.0.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-Options
Określa tabelę skrótu opcji SSH używanych podczas nawiązywania połączenia z zdalną sesją opartą na protokole SSH. Możliwe opcje to wszystkie wartości obsługiwane przez wersję systemu Unix polecenia ssh.
Wszystkie wartości jawnie przekazywane przez parametry mają pierwszeństwo przed wartościami przekazywanymi w Opcje tabeli skrótu. Na przykład użycie parametru Port zastępuje dowolną parę Port
klucz-wartość przekazaną w tabeli Options hashtable.
Ten parametr został dodany w programie PowerShell 7.3.
Typ: | Hashtable |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-Port
Określa port sieciowy na komputerze zdalnym, który jest używany dla tego polecenia. Aby nawiązać połączenie z komputerem zdalnym, komputer zdalny musi nasłuchiwać na porcie używanym przez połączenie. Porty domyślne to 5985 (port WinRM dla protokołu HTTP) i 5986 (port WinRM dla protokołu HTTPS).
Przed użyciem portu alternatywnego skonfiguruj odbiornik WinRM na komputerze zdalnym, aby nasłuchiwać na tym porcie. Aby skonfigurować odbiornik, wpisz następujące dwa polecenia w wierszu polecenia programu PowerShell:
Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse
New-Item -Path WSMan:\Localhost\listener -Transport http -Address * -Port \<port-number\>
Nie używaj parametru portów
Typ: | Int32 |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-RemoteDebug
Służy do uruchamiania wywoływanego polecenia w trybie debugowania w zdalnej sesji programu PowerShell.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-RunAsAdministrator
Wskazuje, że to polecenie cmdlet wywołuje polecenie jako administrator.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-ScriptBlock
Określa polecenia do uruchomienia. Dołącz polecenia w nawiasach klamrowych ({ }
), aby utworzyć blok skryptu. W przypadku używania Invoke-Command
do zdalnego uruchamiania polecenia wszystkie zmienne w poleceniu są oceniane na komputerze zdalnym.
Nuta
Parametry bloku skryptu można przekazać tylko z ArgumentList według pozycji. Nie można przekazać parametrów przełącznika według pozycji. Jeśli potrzebujesz parametru, który zachowuje się jak typ SwitchParameter, zamiast tego użyj typu logicznego.
Typ: | ScriptBlock |
Aliasy: | Command |
Position: | 0 |
Domyślna wartość: | None |
Wymagane: | True |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-Session
Określa tablicę sesji, w których to polecenie cmdlet uruchamia polecenie . Wprowadź zmienną zawierającą
Podczas tworzenia programu PSSessionprogram PowerShell ustanawia trwałe połączenie z komputerem zdalnym. Użyj PSSession, aby uruchomić serię powiązanych poleceń, które udostępniają dane. Aby uruchomić pojedyncze polecenie lub serię niepowiązanych poleceń, użyj parametru ComputerName. Aby uzyskać więcej informacji, zobacz about_PSSessions.
Typ: | PSSession[] |
Position: | 0 |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-SessionName
Określa przyjazną nazwę rozłączonej sesji. Możesz użyć nazwy , aby odwołać się do sesji w kolejnych poleceniach, takich jak Get-PSSession
polecenia. Ten parametr jest prawidłowy tylko w przypadku parametru InDisconnectedSession.
Ten parametr został wprowadzony w programie PowerShell 3.0.
Typ: | String[] |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-SessionOption
Określa opcje zaawansowane dla sesji. Wprowadź obiekt SessionOption, taki jak obiekt utworzony przy użyciu polecenia cmdlet New-PSSessionOption
lub tabela skrótu, w której klucze są nazwami opcji sesji, a wartości są wartościami opcji sesji.
Nuta
Jeśli określisz tabelę skrótu dla SessionOption, program PowerShell konwertuje tabelę skrótu na obiekt System.Management.Autiomation.Remoting.PSSessionOption. Wartości kluczy określonych w tabeli skrótów są rzutowane na zgodną właściwość obiektu. Różni się to od wywoływania New-PSSessionOption
. Na przykład wartości System.TimeSpan dla właściwości limitu czasu, takich jak IdleTimeout, przekonwertuj wartość całkowitą na znaczniki zamiast milisekund.
Aby uzyskać więcej informacji na temat obiektu PSSessionOption i jego właściwości, zobacz PSSessionOption
Wartości domyślne opcji są określane przez wartość zmiennej preferencji $PSSessionOption
, jeśli została ustawiona. W przeciwnym razie wartości domyślne są ustanawiane przez opcje ustawione w konfiguracji sesji.
Wartości opcji sesji mają pierwszeństwo przed wartościami domyślnymi sesji ustawionymi w zmiennej preferencji $PSSessionOption
i w konfiguracji sesji. Nie mają jednak pierwszeństwa przed maksymalnymi wartościami, limitami przydziału ani limitami ustawionymi w konfiguracji sesji.
Aby uzyskać opis opcji sesji, które zawierają wartości domyślne, zobacz New-PSSessionOption
. Aby uzyskać informacje o zmiennej $PSSessionOption
preferencji, zobacz about_Preference_Variables. Aby uzyskać więcej informacji na temat konfiguracji sesji, zobacz Informacje o konfiguracjach sesji.
Typ: | PSSessionOption |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-SSHConnection
Ten parametr przyjmuje tablicę tabel skrótów, w których każda tabela skrótów zawiera co najmniej jeden parametr połączenia wymagany do nawiązania połączenia protokołu Secure Shell (SSH). Parametr SSHConnection jest przydatny do tworzenia wielu sesji, w których każda sesja wymaga różnych informacji o połączeniu.
Tabela skrótów ma następujące elementy członkowskie:
- ComputerName (lub nazwa hosta )
- Port
- Nazwa użytkownika
- KeyFilePath (lub IdentityFilePath)
ComputerName (lub nazwa hosta ) jest jedyną wymaganą parą klucz-wartość.
Ten parametr został wprowadzony w programie PowerShell 6.0.
Typ: | Hashtable[] |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | True |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-SSHTransport
Wskazuje, że połączenie zdalne zostało nawiązane przy użyciu protokołu Secure Shell (SSH).
Domyślnie program PowerShell używa usługi Windows WinRM do nawiązywania połączenia z komputerem zdalnym. Ten przełącznik wymusza na programie PowerShell użycie parametru HostName do nawiązania połączenia zdalnego opartego na protokole SSH.
Ten parametr został wprowadzony w programie PowerShell 6.0.
Typ: | SwitchParameter |
Dopuszczalne wartości: | true |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-Subsystem
Określa podsystem SSH używany dla nowego PSSession.
Określa podsystem do użycia w obiekcie docelowym zgodnie z definicją w sshd_config. Podsystem uruchamia określoną wersję programu PowerShell ze wstępnie zdefiniowanymi parametrami. Jeśli określony podsystem nie istnieje na komputerze zdalnym, polecenie zakończy się niepowodzeniem.
Jeśli ten parametr nie jest używany, wartością domyślną jest podsystem powershell
.
Typ: | String |
Position: | Named |
Domyślna wartość: | powershell |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-ThrottleLimit
Określa maksymalną liczbę połączeń współbieżnych, które można ustanowić w celu uruchomienia tego polecenia. Jeśli pominiesz ten parametr lub wprowadź wartość 0, zostanie użyta wartość domyślna 32.
Limit ograniczania ma zastosowanie tylko do bieżącego polecenia, a nie do sesji ani do komputera.
Typ: | Int32 |
Position: | Named |
Domyślna wartość: | 32 |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-UserName
Określa nazwę użytkownika konta używanego do uruchamiania polecenia na komputerze zdalnym. Metoda uwierzytelniania użytkownika zależy od konfiguracji protokołu Secure Shell (SSH) na komputerze zdalnym.
Jeśli protokół SSH jest skonfigurowany do uwierzytelniania podstawowego hasła, zostanie wyświetlony monit o podanie hasła użytkownika.
Jeśli protokół SSH jest skonfigurowany do uwierzytelniania użytkownika opartego na kluczach, ścieżkę pliku klucza można podać za pośrednictwem parametru KeyFilePath i nie ma monitu o hasło. Jeśli plik klucza użytkownika klienta znajduje się w znanej lokalizacji SSH, parametr KeyFilePath nie jest wymagany do uwierzytelniania opartego na kluczach, a uwierzytelnianie użytkownika odbywa się automatycznie na podstawie nazwy użytkownika. Aby uzyskać więcej informacji, zobacz dokumentację SSH platformy dotyczącą uwierzytelniania użytkowników opartego na kluczach.
Nie jest to wymagany parametr. Jeśli parametr UserName nie zostanie określony, dla połączenia zostanie użyta bieżąca zalogowana nazwa użytkownika.
Ten parametr został wprowadzony w programie PowerShell 6.0.
Typ: | String |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-UseSSL
Wskazuje, że to polecenie cmdlet używa protokołu Secure Sockets Layer (SSL) do nawiązania połączenia z komputerem zdalnym. Domyślnie protokół SSL nie jest używany.
WS-Management szyfruje całą zawartość programu PowerShell przesyłaną przez sieć. Parametr UseSSL to dodatkowa ochrona, która wysyła dane za pośrednictwem protokołu HTTPS zamiast protokołu HTTP.
Jeśli używasz tego parametru, ale protokół SSL nie jest dostępny na porcie używanym dla polecenia, polecenie zakończy się niepowodzeniem.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-VMId
Określa tablicę identyfikatorów maszyn wirtualnych.
Typ: | Guid[] |
Aliasy: | VMGuid |
Position: | 0 |
Domyślna wartość: | None |
Wymagane: | True |
Akceptowanie danych wejściowych potoku: | True |
Akceptowanie symboli wieloznacznych: | False |
-VMName
Określa tablicę nazw maszyn wirtualnych.
Typ: | String[] |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | True |
Akceptowanie danych wejściowych potoku: | True |
Akceptowanie symboli wieloznacznych: | False |
Dane wejściowe
Możesz potokować polecenie w bloku skryptu, aby Invoke-Command
. Użyj $Input
zmiennej automatycznej, aby reprezentować obiekty wejściowe w poleceniu .
Dane wyjściowe
System.Management.Automation.PSRemotingJob
Jeśli używasz parametru AsJob, to polecenie cmdlet zwraca obiekt zadania.
Jeśli używasz parametru InDisconnectedSession, to polecenie cmdlet zwraca obiekt PSSession.
Domyślnie to polecenie cmdlet zwraca dane wyjściowe wywołanego polecenia, czyli wartość parametru ScriptBlock.
Uwagi
Program PowerShell zawiera następujące aliasy dla programu Invoke-Command
:
- Wszystkie platformy:
icm
W systemie Windows Vista i nowszych wersjach systemu operacyjnego Windows, aby użyć ComputerName parametru Invoke-Command
do uruchomienia polecenia na komputerze lokalnym, należy uruchomić program PowerShell przy użyciu opcji Uruchom jako administrator.
Po uruchomieniu poleceń na wielu komputerach program PowerShell łączy się z komputerami w kolejności ich wyświetlania na liście. Jednak dane wyjściowe polecenia są wyświetlane w kolejności, w jakiej są odbierane z komputerów zdalnych, co może być inne.
Błędy wynikające z polecenia, które Invoke-Command
uruchomienia są uwzględniane w wynikach polecenia.
Błędy, które mogłyby spowodować zakończenie błędów w poleceniu lokalnym, są traktowane jako błędy niepowodujące zakończenia w poleceniu zdalnym. Ta strategia zapewnia, że błędy zakończenia na jednym komputerze nie zamykają polecenia na wszystkich komputerach, na których jest uruchamiany. Ta praktyka jest używana nawet wtedy, gdy polecenie zdalne jest uruchamiane na jednym komputerze.
Jeśli komputer zdalny nie znajduje się w domenie zaufanej przez komputer lokalny, komputer może nie być w stanie uwierzytelnić poświadczeń użytkownika. Aby dodać komputer zdalny do listy zaufanych hostów w usłudze WS-Management, użyj następującego polecenia w dostawcy WSMAN
, gdzie <Remote-Computer-Name>
jest nazwą komputera zdalnego:
Set-Item -Path WSMan:\Localhost\Client\TrustedHosts -Value \<Remote-Computer-Name\>
Po rozłączeniu
Wartość AvailabilityNone wskazuje, że można nawiązać połączenie z sesją. Wartość Busy wskazuje, że nie można nawiązać połączenia z PSSession, ponieważ jest ona połączona z inną sesją. Aby uzyskać więcej informacji na temat wartości właściwości State sesji, zobacz RunspaceState. Aby uzyskać więcej informacji na temat wartości właściwości Availability sesji, zobacz RunspaceAvailability.
Parametry HostName i SSHConnection zostały uwzględnione w programie PowerShell 6.0. Dodano je w celu zapewnienia komunikacji zdalnej programu PowerShell na podstawie protokołu Secure Shell (SSH). Programy PowerShell i SSH są obsługiwane na wielu platformach (Windows, Linux, macOS) i komunikacji zdalnej programu PowerShell na tych platformach, na których zainstalowano i skonfigurowano program PowerShell. Jest to oddzielone od poprzedniej komunikacji równorzędnej systemu Windows, która jest oparta na usłudze WinRM, a wiele określonych funkcji i ograniczeń usługi WinRM nie ma zastosowania. Na przykład przydziały oparte na usłudze WinRM, opcje sesji, konfiguracja niestandardowego punktu końcowego i funkcje rozłączania/ponownego nawiązywania połączenia nie są obecnie obsługiwane. Aby uzyskać więcej informacji na temat konfigurowania komunikacji zdalnej SSH programu PowerShell, zobacz komunikacji zdalnej programu PowerShell za pośrednictwem protokołu SSH.
Plik wykonywalny ssh
uzyskuje dane konfiguracji z następujących źródeł w następującej kolejności:
- Opcje wiersza polecenia
- plik konfiguracji użytkownika (~/.ssh/config)
- plik konfiguracji dla całego systemu (/etc/ssh/ssh_config)
Następujące parametry polecenia cmdlet są mapowane na parametry i opcje ssh
:
Parametr polecenia cmdlet | Parametr ssh | równoważna opcja -o SSH |
---|---|---|
-KeyFilePath |
-i <KeyFilePath> |
-o IdentityFile=<KeyFilePath> |
-UserName |
-l <UserName> |
-o User=<UserName> |
-Port |
-p <Port> |
-o Port=<Port> |
-ComputerName -Subsystem |
-s <ComputerName> <Subsystem> |
-o Host=<ComputerName> |
Wszystkie wartości jawnie przekazywane przez parametry mają pierwszeństwo przed wartościami przekazywanymi w Opcje tabeli skrótu. Aby uzyskać więcej informacji na temat plików ssh_config
, zobacz ssh_config(5).