Udostępnij za pośrednictwem


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 , aby utworzyć PSSession (trwałe połączenie) na komputerze zdalnym, a następnie użyć parametru sesji , aby uruchomić polecenie w PSSession. Aby uruchomić polecenie w rozłączonej sesji, użyj parametru InDisconnectedSession. Aby uruchomić polecenie w zadaniu w tle, użyj parametru AsJob.

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 określa sesję zapisaną w zmiennej .

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 i Session parametrów . Pokazuje, jak używać sesji do uruchamiania serii poleceń, które współużytkujące te same dane.

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 korzystające z parametru sesji , aby uruchomić oba polecenia w tej samej sesji. Ponieważ oba polecenia są uruchamiane w tej samej sesji, wartość $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 , aby wyświetlić właściwość PsComputerName dowolnych obiektów, których dotyczy problem.

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 to pozycja 0, a parametr filtru to pozycja 1.

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 przekazuje wartości tablicy do pozycji parametrów dla path i Filter.

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 na komputerze lokalnym i komputerze zdalnym.

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 określa Client skonfigurować ustawienie klienta CredSSP na komputerze lokalnym.

tworzy obiekt PSSession dla serwera Server02 i przechowuje obiekt w zmiennej .

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 określa Server skonfigurować ustawienie serwera CredSSP na komputerze zdalnym.

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 z wartością CredSSP i parametrem Credential z wartością Domain01\Admin01.

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ść OutputBufferingMode jest ustawiona na , a wartość IdleTimeout jest ustawiona na 12 godzin.

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 obiekt docelowy zdalny może zwrócić instrukcję, aby przekierować do innego identyfikatora URI. Domyślnie program PowerShell nie przekierowuje połączeń, ale można użyć tego parametru, aby umożliwić mu przekierowanie połączenia.

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 TrustedHosts komputera lokalnego listy TrustedHosts. Aby uzyskać instrukcje dotyczące dodawania nazwy komputera do listy trustedHosts , zobacz How to Add a Computer to the Trusted Host List(Jak dodać komputer do listy zaufanych hostó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-Credentialcmdlet. 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 , chyba że musisz. Port ustawiony w poleceniu ma zastosowanie do wszystkich komputerów lub sesji, na których jest uruchamiane polecenie. Ustawienie alternatywnego portu może uniemożliwić uruchomienie polecenia na wszystkich komputerach.

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ą obiekty PSSession lub polecenie, które tworzy lub pobiera obiektów, takich jak lub polecenia.

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

ScriptBlock

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.

PSSession

Jeśli używasz parametru InDisconnectedSession, to polecenie cmdlet zwraca obiekt PSSession.

Object

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 PSSession przy użyciu parametru InDisconnectedSession stan sesji jest Odłączony, a dostępność jest Brak. Wartość właściwości State jest względna względem bieżącej sesji. Wartość Rozłączone oznacza, że PSSession nie jest połączona z bieżącą sesją. Nie oznacza to jednak, że PSSession jest odłączony od wszystkich sesji. Może być połączony z inną sesją. Aby określić, czy można nawiązać połączenie z sesją, czy ponownie nawiązać połączenie, użyj właściwości Availability.

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:

  1. Opcje wiersza polecenia
  2. plik konfiguracji użytkownika (~/.ssh/config)
  3. 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).