Invoke-Command
Выполняет команды на локальных и удаленных компьютерах.
Синтаксис
Invoke-Command
[-ScriptBlock] <ScriptBlock>
[-NoNewScope]
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[[-Session] <PSSession[]>]
[-ThrottleLimit <Int32>]
[-AsJob]
[-HideComputerName]
[-JobName <String>]
[-ScriptBlock] <ScriptBlock>
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[[-Session] <PSSession[]>]
[-ThrottleLimit <Int32>]
[-AsJob]
[-HideComputerName]
[-JobName <String>]
[-FilePath] <String>
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[[-ComputerName] <String[]>]
[-Credential <PSCredential>]
[-Port <Int32>]
[-UseSSL]
[-ConfigurationName <String>]
[-ApplicationName <String>]
[-ThrottleLimit <Int32>]
[-AsJob]
[-InDisconnectedSession]
[-SessionName <String[]>]
[-HideComputerName]
[-JobName <String>]
[-FilePath] <String>
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-EnableNetworkAccess]
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
[[-ComputerName] <String[]>]
[-Credential <PSCredential>]
[-Port <Int32>]
[-UseSSL]
[-ConfigurationName <String>]
[-ApplicationName <String>]
[-ThrottleLimit <Int32>]
[-AsJob]
[-InDisconnectedSession]
[-SessionName <String[]>]
[-HideComputerName]
[-JobName <String>]
[-ScriptBlock] <ScriptBlock>
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-EnableNetworkAccess]
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[-CertificateThumbprint <String>]
[<CommonParameters>]
Invoke-Command
[-Credential <PSCredential>]
[-ConfigurationName <String>]
[-ThrottleLimit <Int32>]
[[-ConnectionUri] <Uri[]>]
[-AsJob]
[-InDisconnectedSession]
[-HideComputerName]
[-JobName <String>]
[-ScriptBlock] <ScriptBlock>
[-AllowRedirection]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-EnableNetworkAccess]
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[-CertificateThumbprint <String>]
[<CommonParameters>]
Invoke-Command
[-Credential <PSCredential>]
[-ConfigurationName <String>]
[-ThrottleLimit <Int32>]
[[-ConnectionUri] <Uri[]>]
[-AsJob]
[-InDisconnectedSession]
[-HideComputerName]
[-JobName <String>]
[-FilePath] <String>
[-AllowRedirection]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-EnableNetworkAccess]
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[<CommonParameters>]
Invoke-Command
-Credential <PSCredential>
[-ThrottleLimit <Int32>]
[-AsJob]
[-HideComputerName]
[-ScriptBlock] <ScriptBlock>
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[-VMGuid] <Guid[]>
[<CommonParameters>]
Invoke-Command
-Credential <PSCredential>
[-ThrottleLimit <Int32>]
[-AsJob]
[-HideComputerName]
[-ScriptBlock] <ScriptBlock>
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
-VMName <String[]>
[<CommonParameters>]
Invoke-Command
-Credential <PSCredential>
[-ThrottleLimit <Int32>]
[-AsJob]
[-HideComputerName]
[-FilePath] <String>
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[-VMGuid] <Guid[]>
[<CommonParameters>]
Invoke-Command
-Credential <PSCredential>
[-ThrottleLimit <Int32>]
[-AsJob]
[-HideComputerName]
[-FilePath] <String>
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
-VMName <String[]>
[<CommonParameters>]
Описание
Командлет Invoke-Command
выполняет команды на локальном или удаленном компьютере и возвращает все выходные данные команд, включая ошибки. С помощью одной Invoke-Command
команды можно выполнять команды на нескольких компьютерах.
Чтобы выполнить одну команду на удаленном компьютере, используйте параметр ComputerName. Чтобы выполнить ряд связанных команд, которые совместно используют данные, используйте New-PSSession
командлет для создания PSSession (постоянное подключение) на удаленном компьютере, а затем используйте параметр Session для Invoke-Command
выполнения команды в PSSession. Чтобы выполнить команду в отключенном сеансе, используйте параметр InDisconnectedSession. Чтобы выполнить команду в фоновом задании, используйте параметр AsJob.
Вы также можете использовать Invoke-Command
на локальном компьютере блок скрипта в качестве команды. PowerShell запускает блок скрипта немедленно в дочернем область текущего область.
Прежде чем использовать Invoke-Command
для выполнения команд на удаленном компьютере, прочтите about_Remote.
В некоторых примерах кода используется сплаттинг для уменьшения длины строки. Дополнительные сведения см. в разделе about_Splatting.
Примеры
Пример 1. Запуск скрипта на сервере
В этом примере скрипт запускается Test.ps1
на компьютере Server01.
Invoke-Command -FilePath c:\scripts\test.ps1 -ComputerName Server01
Параметр FilePath указывает скрипт, расположенный на локальном компьютере. Скрипт выполняется на удаленном компьютере, и результаты возвращаются на локальный компьютер.
Пример 2. Выполнение команды на удаленном сервере
В этом примере выполняется Get-Culture
команда на удаленном компьютере Server01.
Invoke-Command -ComputerName Server01 -Credential Domain01\User01 -ScriptBlock { Get-Culture }
Параметр ComputerName указывает имя удаленного компьютера. Параметр Credential используется для выполнения команды в контексте безопасности Domain01\User01, пользователя, имеющего разрешение на выполнение команд. Параметр ScriptBlock указывает команду, выполняемую на удаленном компьютере.
В ответ PowerShell запрашивает пароль и метод проверки подлинности для учетной записи User01. Затем на компьютере Server01 запускается команда и возвращается результат.
Пример 3. Выполнение команды в постоянном подключении
В этом примере выполняется та же Get-Culture
команда в сеансе с использованием постоянного подключения на удаленном компьютере с именем Server02.
$s = New-PSSession -ComputerName Server02 -Credential Domain01\User01
Invoke-Command -Session $s -ScriptBlock {Get-Culture}
Командлет New-PSSession
создает сеанс на удаленном компьютере Server02 и сохраняет его в переменной $s
. Как правило, сеанс создается только при выполнении ряда команд на удаленном компьютере.
Командлет Invoke-Command
выполняет команду на Get-Culture
сервере Server02. Параметр Session указывает сеанс, сохраненный в переменной $s
.
В ответ PowerShell выполняет команду в сеансе на компьютере Server02.
Пример 4. Использование сеанса для выполнения ряда команд, которые совместно используют данные
В этом примере сравниваются эффекты использования параметров ComputerName и СеансаInvoke-Command
. В нем показано, как использовать сеанс для запуска ряда команд с общими данными.
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
Первые две команды используют параметр ComputerName для Invoke-Command
выполнения команд на удаленном компьютере Server02. Первая команда использует Get-Process
командлет , чтобы получить процесс PowerShell на удаленном компьютере и сохранить его в переменной $p
. Вторая команда получает значение свойства VirtualMemorySize процесса PowerShell.
При использовании параметра ComputerName PowerShell создает новый сеанс для выполнения команды.
Сеанс закрывается по завершении выполнения команды. Переменная $p
была создана в одном соединении, но не существует в соединении, созданном для второй команды.
Проблема решается путем создания постоянного сеанса на удаленном компьютере, а затем выполнения обеих команд в одном сеансе.
Командлет New-PSSession
создает постоянный сеанс на компьютере Server02 и сохраняет сеанс в переменной $s
. Следующие Invoke-Command
строки используют параметр Session для выполнения обеих команд в одном сеансе. Так как обе команды выполняются в одном сеансе $p
, значение остается активным.
Пример 5. Ввод команды, хранящейся в локальной переменной
В этом примере показано, как создать команду, которая хранится в виде блока скрипта в локальной переменной. При сохранении блока скрипта в локальной переменной можно указать переменную в качестве значения параметра ScriptBlock .
$command = { Get-EventLog -LogName "Windows PowerShell" |
Where-Object {$_.Message -like "*certificate*"} }
Invoke-Command -ComputerName S1, S2 -ScriptBlock $command
Переменная $command
хранит Get-EventLog
команду, отформатированную как блок скрипта. Выполняет Invoke-Command
команду, хранящуюся на $command
удаленных компьютерах S1 и S2.
Пример 6. Выполнение одной команды на нескольких компьютерах
В этом примере показано, как использовать Invoke-Command
для выполнения одной команды на нескольких компьютерах.
$parameters = @{
ComputerName = "Server01", "Server02", "TST-0143", "localhost"
ConfigurationName = 'MySession.PowerShell'
ScriptBlock = { Get-EventLog "Windows PowerShell" }
}
Invoke-Command @parameters
Параметр ComputerName задает разделенный запятыми список имен компьютеров. Список компьютеров включает значение localhost, представляющее локальный компьютер. Параметр ConfigurationName указывает альтернативную конфигурацию сеанса. Параметр ScriptBlock запускается Get-EventLog
для получения журналов событий Windows PowerShell с каждого компьютера.
Пример 7. Получение версии ведущего приложения на нескольких компьютерах
В этом примере возвращается версия ведущего приложения PowerShell, работающего на 200 удаленных компьютерах.
$version = Invoke-Command -ComputerName (Get-Content Machines.txt) -ScriptBlock {(Get-Host).Version}
Так как выполняется только одна команда, вам не нужно создавать постоянные подключения к каждому из компьютеров. Вместо этого команда использует параметр ComputerName для указания компьютеров. Чтобы указать компьютеры, он использует Get-Content
командлет для получения содержимого файла Machine.txt, файла имен компьютеров.
Командлет Invoke-Command
выполняет Get-Host
команду на удаленных компьютерах. Он использует точечную нотацию для получения свойства Version узла PowerShell.
Эти команды выполняются по одному. После завершения выполнения команд выходные данные команд со всех компьютеров сохраняются в переменной $version
. В выходные данные включается имя компьютера, с которого были получены данные.
Пример 8. Запуск фонового задания на нескольких удаленных компьютерах
В этом примере выполняется команда на двух удаленных компьютерах. Команда Invoke-Command
использует параметр AsJob , чтобы команда выполнялись как фоновое задание. Команды выполняются на удаленных компьютерах, но задание существует на локальном компьютере. Результаты передаются на локальный компьютер.
$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
Командлет New-PSSession
создает сеансы на удаленных компьютерах Server01 и Server02. Командлет Invoke-Command
выполняет фоновое задание в каждом из сеансов. Команда с помощью параметра AsJob выполняет команду как фоновое задание. Эта команда возвращает объект задания, который содержит два дочерних объекта задания: один для каждого из заданий, запущенных на двух удаленных компьютерах.
Команда Get-Job
сохраняет объект задания в переменной $j
. Затем $j
переменная передается в Format-List
командлет для отображения всех свойств объекта задания в списке. Последняя команда получает результаты заданий. Он передает объект задания в $j
Receive-Job
командлет и сохраняет результаты в переменной $results
.
Пример 9. Включение локальных переменных в выполнение команды на удаленном компьютере
В этом примере показано, как включить значения локальных переменных в команду, запущенную на удаленном компьютере. Команда использует модификатор Using
область для идентификации локальной переменной в удаленной команде. По умолчанию предполагается, что все переменные определяются в удаленном сеансе. Модификатор Using
область появился в PowerShell 3.0. Дополнительные сведения о модификаторе Using
область см. в разделе about_Remote_Variables и about_Scopes.
$Log = "Windows PowerShell"
Invoke-Command -ComputerName Server01 -ScriptBlock { Get-EventLog -LogName $Using:Log -Newest 10 }
Переменная $Log
сохраняет имя журнала событий, Windows PowerShell. Командлет Invoke-Command
выполняется Get-EventLog
на сервере Server01, чтобы получить десять новейших событий из журнала событий. Значением параметра LogName является $Log
переменная, которая имеет префикс модификатора Using
область, чтобы указать, что он был создан в локальном сеансе, а не в удаленном сеансе.
Пример 10. Скрытие имени компьютера
В этом примере показан эффект использования параметра HideComputerName объекта Invoke-Command
.
HideComputerName не изменяет объект, возвращаемый этим командлетом. Он изменяет только дисплей. Командлеты Format по-прежнему можно использовать для отображения свойства PsComputerName любого из затронутых объектов.
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 -ScriptBlock {Get-Process PowerShell} -HideComputerName
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
Первые две команды используют Invoke-Command
для выполнения Get-Process
команды для процесса PowerShell. В выходных данных первой команды содержится свойство PsComputerName с именем компьютера, на котором запущена команда. Выходные данные второй команды, которая использует HideComputerName, не включают столбец PsComputerName .
Пример 11. Использование ключевое слово Param в блоке скрипта
Ключевое слово Param
и параметр ArgumentList используются для передачи значений переменных именованным параметрам в блоке скрипта. В этом примере отображаются имена файлов, которые начинаются с буквы a
.pdf
и имеют расширение .
Дополнительные сведения о ключевое слово см. в Param
разделе 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
использует параметр ScriptBlock , определяющий две переменные, $param1
и $param2
. Get-ChildItem
использует именованные параметры, Name и Include с именами переменных. ArgumentList передает значения переменным.
Пример 12. Использование автоматической переменной $args в блоке скрипта
Автоматическая $args
переменная и параметр ArgumentList используются для передачи значений массива в позиции параметров в блоке скрипта. В этом примере отображается содержимое .txt
файлов каталога сервера. Параметр Get-ChildItem
Path имеет позицию 0, а параметр Filter — позицию 1.
Дополнительные сведения о переменной см. в $args
разделе 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
использует параметр ScriptBlock и Get-ChildItem
задает значения массива $args[0]
и $args[1]
. ArgumentList передает значения массива $args
в Get-ChildItem
позиции параметров Path и Filter.
Пример 13. Запуск скрипта на всех компьютерах, перечисленных в текстовом файле
В этом примере используется Invoke-Command
командлет для выполнения скрипта Sample.ps1
на всех компьютерах, перечисленных Servers.txt
в файле . Команда использует параметр FilePath, чтобы указать файл скрипта. Эта команда позволяет запускать скрипт на удаленных компьютерах, даже если файл скрипта недоступен для удаленных компьютеров.
Invoke-Command -ComputerName (Get-Content Servers.txt) -FilePath C:\Scripts\Sample.ps1 -ArgumentList Process, Service
При отправке команды содержимое Sample.ps1
файла копируется в блок скрипта, а блок скрипта выполняется на каждом из удаленных компьютеров. Эта процедура эквивалентна использованию параметра ScriptBlock для отправки содержимого скрипта.
Пример 14. Выполнение команды на удаленном компьютере с помощью URI
В этом примере показано, как выполнить команду на удаленном компьютере, который определяется универсальным кодом ресурса (URI). В этом примере выполняется Set-Mailbox
команда на удаленном сервере Exchange Server.
$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
В первой строке Get-Credential
используется командлет для хранения учетных данных Windows Live ID в переменной $LiveCred
. PowerShell предлагает пользователю ввести учетные данные Windows Live ID.
Переменная $parameters
представляет собой хэш-таблицу, содержащую параметры, передаваемые в Invoke-Command
командлет . Командлет Invoke-Command
выполняет Set-Mailbox
команду, используя конфигурацию сеанса Microsoft.Exchange . Параметр ConnectionURI указывает URL-адрес конечной точки сервера Exchange Server. Параметр Credential указывает учетные данные, хранящиеся в переменной $LiveCred
. Параметр AuthenticationMechanism указывает способ использования обычной проверки подлинности. Параметр ScriptBlock указывает блок скрипта, который содержит команду.
Пример 15. Использование параметра сеанса
В этом примере показано, как создать и использовать параметр SessionOption .
$so = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
Invoke-Command -ComputerName server01 -UseSSL -ScriptBlock { Get-HotFix } -SessionOption $so -Credential server01\user01
Командлет New-PSSessionOption
создает объект параметра сеанса, который приводит к тому, что удаленный конец не проверяет центр сертификации, каноническое имя и отзыв Списки при оценке входящего подключения HTTPS. Объект SessionOption сохраняется в переменной $so
.
Примечание
Отключение этих проверок удобно для устранения неполадок, но, очевидно, небезопасно.
Командлет Invoke-Command
выполняет Get-HotFix
команду удаленно. Параметр SessionOption получает $so
переменную .
Пример 16. Управление перенаправлением URI в удаленной команде
В этом примере показано, как использовать параметры AllowRedirection и SessionOption для управления перенаправлением URI в удаленной команде.
$max = New-PSSessionOption -MaximumRedirection 1
$parameters = @{
ConnectionUri = "https://ps.exchangelabs.com/PowerShell"
ScriptBlock = { Get-Mailbox dan }
AllowRedirection = $true
SessionOption = $max
}
Invoke-Command @parameters
Командлет New-PSSessionOption
создает объект PSSessionOption , который сохраняется в переменной $max
. Команда использует параметр MaximumRedirection, чтобы задать для свойства MaximumConnectionRedirectionCount объекта PSSessionOption значение 1.
Командлет Invoke-Command
выполняет Get-Mailbox
команду на удаленном Microsoft Exchange Server. Параметр AllowRedirection предоставляет явное разрешение на перенаправление подключения к альтернативной конечной точке. Параметр SessionOption использует объект сеанса, хранящийся в переменной $max
.
В результате, если удаленный компьютер, указанный в параметре ConnectionURI , возвращает сообщение перенаправления, PowerShell перенаправляет подключение, но если новое назначение возвращает другое сообщение перенаправления, значение счетчика перенаправления, равное 1, превышается и Invoke-Command
возвращает неустранимую ошибку.
Пример 17. Доступ к общей сетевой папке в удаленном сеансе
В этом примере показано, как получить доступ к сетевой папке из удаленного сеанса. Для демонстрации примера используются три компьютера. Server01 — локальный компьютер, Server02 — удаленный компьютер, а Net03 — сетевая папка. Server01 подключается к Server02, а затем Server02 выполняет второй прыжок к Net03 для доступа к сетевой папке. Дополнительные сведения о том, как удаленное взаимодействие PowerShell поддерживает прыжки между компьютерами, см. в статье Создание второго прыжка в удаленном взаимодействии PowerShell.
Необходимое делегирование поставщика поддержки безопасности учетных данных (CredSSP) включено в параметрах клиента на локальном компьютере и в параметрах службы на удаленном компьютере. Для выполнения команд в этом примере необходимо быть членом группы Администраторы на локальном и удаленном компьютерах.
Enable-WSManCredSSP -Role Client -DelegateComputer Server02
$s = New-PSSession Server02
Invoke-Command -Session $s -ScriptBlock {Enable-WSManCredSSP -Role Server -Force}
$parameters = @{
Session = $s
ScriptBlock = { Get-Item \\Net03\Scripts\LogFiles.ps1 }
Authentication = "CredSSP"
Credential = "Domain01\Admin01"
}
Invoke-Command @parameters
Командлет Enable-WSManCredSSP
включает делегирование CredSSP с локального компьютера Server01 на удаленный компьютер Server02. Параметр Role указывает клиент для настройки параметра клиента CredSSP на локальном компьютере.
New-PSSession
создает объект PSSession для Server02 и сохраняет объект в переменной $s
.
Командлет Invoke-Command
использует $s
переменную для подключения к удаленному компьютеру Server02. Параметр ScriptBlock выполняется Enable-WSManCredSSP
на удаленном компьютере. Параметр Role указывает server для настройки параметра сервера CredSSP на удаленном компьютере.
Переменная $parameters
содержит значения параметров для подключения к сетевой папке. Командлет Invoke-Command
выполняет Get-Item
команду в сеансе в $s
. Эта команда получает скрипт из общей сетевой \\Net03\Scripts
папки. Команда использует параметр Authentication со значением CredSSP и параметр Credential со значением Domain01\Admin01.
Пример 18. Запуск скриптов на многих удаленных компьютерах
В этом примере выполняется скрипт на более чем ста компьютерах. Чтобы свести к минимуму влияние на локальный компьютер, она подключается к каждому компьютеру, запускает скрипт, а затем отключается. Скрипт продолжает выполняться в отключенных сеансах.
$parameters = @{
ComputerName = (Get-Content -Path C:\Test\Servers.txt)
InDisconnectedSession = $true
FilePath = "\\Scripts\Public\ConfigInventory.ps1"
SessionOption = @{OutputBufferingMode="Drop";IdleTimeout=43200000}
}
Invoke-Command @parameters
Команда использует Invoke-Command
для запуска скрипта. Значение параметра ComputerName — это Get-Content
команда, которая получает имена удаленных компьютеров из текстового файла. Параметр InDisconnectedSession отключает сеансы сразу при запуске команды. Значение параметра FilePath — это скрипт, который Invoke-Command
выполняется на каждом компьютере.
Значение SessionOption — это хэш-таблица. Значение OutputBufferingMode имеет значение Drop , а значение IdleTimeout — 43200000 миллисекунд (12 часов).
Чтобы получить результаты команд и скриптов, которые выполняются в отключенных сеансах, используйте Receive-PSSession
командлет .
Параметры
-AllowRedirection
Разрешает перенаправление данного соединения на альтернативный URI.
При использовании параметра ConnectionURI удаленный компьютер может вернуть инструкцию для перенаправления на другой URI. По умолчанию PowerShell не перенаправляет подключения, но вы можете использовать этот параметр, чтобы разрешить ему перенаправлять подключение.
Можно также ограничить количество перенаправлений соединение, изменив значение параметра сеанса MaximumConnectionRedirectionCount. Используйте параметр MaximumRedirection командлета New-PSSessionOption
или задайте свойство MaximumConnectionRedirectionCount переменной $PSSessionOption
предпочтения. Значение по умолчанию — 5.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ApplicationName
Определяет сегмент имени приложения в URI соединения. Используйте этот параметр, чтобы указать имя приложения, если в команде не используется параметр ConnectionURI .
Значение по умолчанию — это значение переменной $PSSessionApplicationName
предпочтения на локальном компьютере. Если эта переменная предпочтения не определена, значение по умолчанию — WSMAN. Это значение подходит для большинства случаев Дополнительные сведения см. в разделе about_Preference_Variables.
Служба удаленного управления Windows (WinRM) использует имя приложения для выбора прослушивателя для обслуживания запроса на подключение. Значение этого параметра должно совпадать со значением свойства URLPrefix прослушивателя на удаленном компьютере.
Type: | String |
Position: | Named |
Default value: | $PSSessionApplicationName if set on the local computer, otherwise WSMAN |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-ArgumentList
Предоставляет значения локальных переменных в команде. Переменные в команде заменяются этими значениями до выполнения команды на удаленном компьютере. Введите значения в список с разделителями-запятыми. Значения связаны с переменными в порядке их перечисления. Псевдоним для ArgumentList — Args.
Значения в параметре ArgumentList могут быть фактическими значениями, например 1024, или ссылками на локальные переменные, например $max
.
Чтобы использовать локальные переменные в команде, воспользуйтесь следующим форматом команды:
{param($<name1>[, $<name2>]...) <command-with-local-variables>} -ArgumentList <value>
-или- <local-variable>
В ключевое слово параметров перечислены локальные переменные, используемые в команде . ArgumentList предоставляет значения переменных в порядке их перечисления.
Type: | Object[] |
Aliases: | Args |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-AsJob
Указывает, что этот командлет выполняет команду в качестве фонового задания на удаленном компьютере. Используйте этот параметр для выполнения команд, которые занимают много времени.
При использовании параметра AsJob команда возвращает объект, представляющий задание, а затем отображает командную строку. Можно продолжить работу в рамках данного сеанса, пока задание завершается. Для управления заданием используйте *-Job
командлеты. Чтобы получить результаты задания, используйте Receive-Job
командлет .
Параметр AsJob напоминает использование командлета Invoke-Command
для удаленного запуска командлета Start-Job
. Однако при использовании AsJob задание создается на локальном компьютере, даже если оно выполняется на удаленном компьютере. Результаты удаленного задания автоматически возвращаются на локальный компьютер.
Дополнительные сведения о фоновых заданиях PowerShell см. в разделе about_Jobs и about_Remote_Jobs.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Authentication
Указывает механизм, используемый для проверки подлинности учетных данных пользователя. Проверка подлинности CredSSP доступна только в Windows Vista, Windows Server 2008 и более поздних версиях операционной системы Windows.
Ниже приведены допустимые значения для этого параметра.
- Default
- Basic
- Credssp
- Digest (дайджест)
- Kerberos
- Согласование
- NegotiateWithImplicitCredential
Значение по умолчанию — Default.
Дополнительные сведения о значениях этого параметра см. в разделе AuthenticationMechanism Enumeration.
Внимание!
Аутентификация CredSSP, в рамках которой учетные данные пользователя передаются на удаленный компьютер для проверки, предназначена для команд, требующих аутентификацию нескольких ресурсов, например для доступа к удаленной сетевой папке. Этот механизм повышает риск безопасности удаленной операции. Если удаленный компьютер скомпрометирован, учетные данные, передаваемые ему, могут использоваться для управления сетевым сеансом. Дополнительные сведения см. в разделе Поставщик поддержки безопасности учетных данных.
Type: | AuthenticationMechanism |
Accepted values: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
Position: | Named |
Default value: | Default |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CertificateThumbprint
Задает цифровой сертификат с открытым ключом (X509) учетной записи пользователя, который располагает разрешением для подключения к отсоединенному сеансу. Введите отпечаток сертификата.
Сертификаты используются при проверке подлинности на основе сертификата клиента. Они могут быть сопоставлены только с локальными учетными записями пользователей и не работают с учетными записями домена.
Чтобы получить отпечаток сертификата, используйте Get-Item
команду или Get-ChildItem
на диске PowerShell Cert: .
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ComputerName
Указывает компьютеры, на которых выполняется команда. По умолчанию это локальный компьютер.
При использовании параметра ComputerName PowerShell создает временное подключение, которое используется только для выполнения указанной команды, а затем закрывается. Если требуется постоянное подключение, используйте параметр Session .
Введите имя NetBIOS, IP-адрес или полное доменное имя одного или нескольких компьютеров в списке с разделителями запятыми. Чтобы указать локальный компьютер, введите имя компьютера, localhost или точку (.
).
Чтобы использовать IP-адрес в значении ComputerName, команда должна включать параметр Credential . Компьютер должен быть настроен для транспорта HTTPS или IP-адрес удаленного компьютера должен быть включен в список TrustedHosts WinRM локального компьютера. Инструкции по добавлению имени компьютера в список TrustedHosts см. в статье How to Add a Computer to the Trusted Host List.
В Windows Vista и более поздних версиях операционной системы Windows, чтобы включить локальный компьютер в значение ComputerName, необходимо запустить PowerShell с помощью параметра Запуск от имени администратора .
Type: | String[] |
Aliases: | Cn |
Position: | 0 |
Default value: | Local computer |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ConfigurationName
Указывает конфигурацию сеанса, используемую для нового сеанса PSSession.
Введите имя конфигурации или полное имя ресурса (URI) для конфигурации сеанса. Если указать только имя конфигурации, в начале добавляется следующий универсальный код ресурса (URI) схемы: https://schemas.microsoft.com/PowerShell
.
Конфигурация сеанса для сеанса размещается на удаленном компьютере. Если указанная конфигурация сеанса не существует на удаленном компьютере, команда завершается ошибкой.
Значение по умолчанию — это значение переменной $PSSessionConfigurationName
предпочтения на локальном компьютере. Если эта переменная предпочтения не задана, по умолчанию используется Microsoft.PowerShell. Дополнительные сведения см. в разделе about_Preference_Variables.
Type: | String |
Position: | Named |
Default value: | $PSSessionConfigurationName if set on the local computer, otherwise Microsoft.PowerShell |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-ConnectionUri
Задает универсальный код ресурса (URI), который определяет конечную точку подключения сеанса. Значение URI должно быть указано полностью.
Строка имеет следующий формат:
<Transport>://<ComputerName>:<Port>/<ApplicationName>
Значение по умолчанию определяется следующим образом.
https://localhost:5985/WSMAN
Если URI подключения не указан, можно использовать параметры UseSSL и Port , чтобы указать значения URI подключения.
Допустимые значения для сегмента Transport идентификатора URI: HTTP и HTTPS. Если вы указываете URI подключения с сегментом транспорта, но не указываете порт, сеанс создается со стандартными портами: 80 для HTTP и 443 для HTTPS. Чтобы использовать порты по умолчанию для удаленного взаимодействия PowerShell, укажите порт 5985 для HTTP или 5986 для HTTPS.
Если конечный компьютер перенаправляет подключение на другой универсальный код ресурса (URI), PowerShell запрещает перенаправление, если в команде не используется параметр AllowRedirection .
Type: | Uri[] |
Aliases: | URI, CU |
Position: | 0 |
Default value: | https://localhost:5985/WSMAN |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Credential
Указывает учетную запись пользователя с разрешением на выполнение этого действия. По умолчанию используется текущий пользователь.
Введите имя пользователя, например User01 или Domain01\User01. Или введите объект PSCredential , например объект, созданный командлетом Get-Credential
. При вводе имени пользователя этот командлет запрашивает пароль.
Type: | PSCredential |
Position: | Named |
Default value: | Current user |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-EnableNetworkAccess
Указывает, что этот командлет добавляет интерактивный маркер безопасности в сеансы замыкания на себя. Интерактивный маркер позволяет выполнять в петлевом сеансе команды, которые получают данные с других компьютеров. Например, можно выполнить команду в сеансе, который копирует XML-файлы с удаленного компьютера на локальный.
Сеанс замыкания на себя — это сеанс PSSession , который создается и заканчивается на одном компьютере. Чтобы создать сеанс замыкания на себя, опустите параметр ComputerName или задайте для его значения точку (.
), localhost или имя локального компьютера.
По умолчанию сеансы замыкания на себя создаются с помощью сетевого маркера, который может не предоставить достаточные разрешения для проверки подлинности на удаленных компьютерах.
Параметр EnableNetworkAccess действует только в петлевых сеансах. Если при создании сеанса на удаленном компьютере используется enableNetworkAccess , команда будет выполнена успешно, но параметр игнорируется.
Удаленный доступ можно разрешить в сеансе замыкания на себя, используя значение CredSSP параметра Authentication , которое делегирует учетные данные сеанса другим компьютерам.
Чтобы защитить компьютер от вредоносного доступа, отключенные сеансы замыкания на себя с интерактивными маркерами, созданными с помощью EnableNetworkAccess, можно повторно подключить только с компьютера, на котором был создан сеанс. Отключенные сеансы, использующие проверку подлинности CredSSP, можно повторно подключить с других компьютеров. Для получения дополнительной информации см. Disconnect-PSSession
.
Этот параметр появился в PowerShell 3.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-FilePath
Указывает локальный скрипт, который этот командлет выполняет на одном или нескольких удаленных компьютерах. Введите путь и имя файла скрипта или отправьте путь к скрипту в Invoke-Command
. Скрипт должен находиться на локальном компьютере или в каталоге, к которому локальный компьютер может получить доступ. Используйте ArgumentList , чтобы указать значения параметров в скрипте.
При использовании этого параметра PowerShell преобразует содержимое указанного файла скрипта в блок скрипта, передает блок скрипта на удаленный компьютер и запускает его на удаленном компьютере.
Type: | String |
Aliases: | PSPath |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-HideComputerName
Указывает, что этот командлет пропускает имя компьютера каждого объекта на выходном экране. По умолчанию имя компьютера, создавшего объект, отображается на экране.
Этот параметр влияет только на отображение выходных данных. Объект не изменяется.
Type: | SwitchParameter |
Aliases: | HCN |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-InDisconnectedSession
Указывает, что этот командлет выполняет команду или скрипт в отключенном сеансе.
При использовании параметра Invoke-Command
InDisconnectedSession создает постоянный сеанс на каждом удаленном компьютере, запускает команду, указанную параметром ScriptBlock или FilePath, а затем отключается от сеанса. Команды продолжают выполняться в отключенных сеансах. InDisconnectedSession позволяет выполнять команды без поддержания подключения к удаленным сеансам. Так как сеанс отключается перед возвратом результатов, InDisconnectedSession гарантирует, что все результаты команды будут возвращены в повторно подключенном сеансе, а не разделены между сеансами.
InDisconnectedSession нельзя использовать с параметром Session или AsJob.
Команды, использующие InDisconnectedSession , возвращают объект PSSession , представляющий отключенный сеанс. Они не возвращают выходные данные команды. Чтобы подключиться к отключенным сеансам Connect-PSSession
, используйте командлеты или Receive-PSSession
. Чтобы получить результаты команд, которые выполнялись в сеансе, используйте Receive-PSSession
командлет . Чтобы выполнить команды, которые создают выходные данные в отключенном сеансе, задайте для параметра сеанса OutputBufferingMode значение Drop. Если вы планируете подключиться к отключенным сеансам, установите время ожидания простоя в сеансе, чтобы оно предоставляло достаточно времени для подключения перед удалением сеанса.
Режим буферизации выходных данных и время ожидания простоя можно задать в параметре SessionOption или в переменной $PSSessionOption
предпочтения. Дополнительные сведения о параметрах сеанса см. в разделе New-PSSessionOption
и about_Preference_Variables.
Дополнительные сведения о функции отключенных сеансов см. в разделе about_Remote_Disconnected_Sessions.
Этот параметр появился в PowerShell 3.0.
Type: | SwitchParameter |
Aliases: | Disconnected |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-InputObject
Указывает входные данные команды. Введите переменную, которая содержит объекты, или команду или выражение, которое возвращает объекты.
При использовании параметра InputObject используйте автоматическую $Input
переменную в значении параметра ScriptBlock для представления входных объектов.
Type: | PSObject |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-JobName
Указывает понятное имя для фонового задания. По умолчанию задания называются Job<n>
, где <n>
— порядковый номер.
Если в команде используется параметр JobName , команда выполняется как задание и Invoke-Command
возвращает объект задания, даже если вы не включили AsJob в команду.
Дополнительные сведения о фоновых заданиях PowerShell см. в разделе about_Jobs.
Type: | String |
Position: | Named |
Default value: | Job<n> |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NoNewScope
Указывает, что этот командлет выполняет указанную команду в текущем область. По умолчанию Invoke-Command
команды выполняются в собственных область.
Этот параметр допустим только в командах, которые выполняются в текущем сеансе, т. е. в командах, которые пропускают как параметр ComputerName, так и параметр Session.
Этот параметр появился в PowerShell 3.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Port
Указывает сетевой порт на удаленном компьютере, который используется для этой команды. Для подключения к удаленному компьютеру требуется, чтобы он прослушивал порт, используемый соединением. По умолчанию используются порты 5985, которые являются портом WinRM для HTTP, и 5986, который является портом WinRM для HTTPS.
Перед использованием другого порта настройте прослушиватель WinRM на удаленном компьютере для прослушивания порта. Чтобы настроить прослушиватель, введите в командной строке PowerShell следующие две команды:
Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse
New-Item -Path WSMan:\Localhost\listener -Transport http -Address * -Port \<port-number\>
Не используйте параметр Port , если это не требуется. Порт, который задается в команде, применяется ко всем компьютерам или сеансам, в которых выполняется команда. Альтернативный порт может помешать выполнению команды на всех компьютерах.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ScriptBlock
Указывает выполняющиеся команды. Заключите команды в фигурные скобки { }
, чтобы создать блок скрипта.
Это обязательный параметр.
По умолчанию все переменные в команде вычисляются на удаленном компьютере. Чтобы включить локальные переменные в команду, используйте ArgumentList.
Type: | ScriptBlock |
Aliases: | Command |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Session
Задает массив сеансов, в которых этот командлет выполняет команду . Введите переменную, содержащую объекты PSSession , или команду, которая создает или получает объекты PSSession , например New-PSSession
команду или Get-PSSession
.
При создании PSSession PowerShell устанавливает постоянное подключение к удаленному компьютеру. Используйте PSSession для выполнения ряда связанных команд, которые совместно используют данные. Чтобы выполнить одну команду или ряд несвязанных команд, используйте параметр ComputerName . Дополнительные сведения см. в разделе about_PSSessions.
Type: | PSSession[] |
Position: | 0 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionName
Задает понятное имя для отключенного сеанса. Имя можно использовать для ссылки на сеанс в последующих командах, таких как Get-PSSession
команда . Этот параметр допустим только при использовании с параметром InDisconnectedSession.
Этот параметр появился в PowerShell 3.0.
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionOption
Задает дополнительные параметры для сеанса. Введите объект SessionOption , например создаваемый с помощью New-PSSessionOption
командлета, или хэш-таблицу, в которой ключи являются именами параметров сеанса, а значения — значениями параметров сеанса.
Значения по умолчанию для параметров определяются значением $PSSessionOption
переменной предпочтения, если она задана. В противном случае значения по умолчанию задаются параметрами, указанными в конфигурации сеанса.
Значения параметров сеанса имеют приоритет над значениями по умолчанию для сеансов, заданных в переменной $PSSessionOption
предпочтения и в конфигурации сеанса. Однако они не имеют приоритета над максимальными значениями, квотами или ограничениями, установленными в конфигурации сеанса.
Описание параметров сеанса, которые включают значения по умолчанию, см. в разделе New-PSSessionOption
. Сведения о переменной предпочтения см. в $PSSessionOption
разделе about_Preference_Variables.
Дополнительные сведения о конфигурациях сеансов см. в разделе about_Session_Configurations.
Type: | PSSessionOption |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ThrottleLimit
Указывает максимальное число одновременных подключений, которые можно установить для запуска этой команды. Если этот параметр не указан или имеет значение 0, используется значение по умолчанию — 32.
Предел регулирования применяется только к текущему командлету, а не к сеансу или компьютеру.
Type: | Int32 |
Position: | Named |
Default value: | 32 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseSSL
Указывает, что этот командлет использует протокол SSL для установки подключения к удаленному компьютеру. По умолчанию SSL не используется.
WS-Management шифрует все содержимое PowerShell, передаваемое по сети. Параметр UseSSL — это дополнительная защита, которая отправляет данные по протоколу HTTPS, а не ПО HTTP.
Если вы используете этот параметр, но SSL недоступен на порте, используемом для команды, команда завершается ошибкой.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-VMId
Указывает массив идентификаторов виртуальных машин.
Type: | Guid[] |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-VMName
Указывает массив имен виртуальных машин.
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Входные данные
Команду в блоке скрипта можно передать по конвейеру Invoke-Command
в . Используйте автоматическую $Input
переменную для представления входных объектов в команде .
Выходные данные
System.Management.Automation.PSRemotingJob, System.Management.Automation.Runspaces.PSSession, or the output of the invoked command
Этот командлет возвращает объект задания, если используется параметр AsJob . Если указать параметр InDisconnectedSession , Invoke-Command
возвращается объект PSSession . В противном случае он возвращает выходные данные вызванной команды, которая является значением параметра ScriptBlock .
Примечания
В Windows Vista и более поздних версиях операционной системы Windows, чтобы использовать параметр Invoke-Command
ComputerName для выполнения команды на локальном компьютере, необходимо запустить PowerShell с помощью параметра Запуск от имени администратора.
При выполнении команд на нескольких компьютерах PowerShell подключается к компьютерам в том порядке, в котором они отображаются в списке. Однако выходные данные команды отображаются в том порядке, в котором они получены с удаленных компьютеров, что может отличаться.
Ошибки, которые возникают в результате выполнения команды, Invoke-Command
включаются в результаты команды.
Ошибки, являющиеся неустранимыми в локальной команде, рассматриваются как устранимые в удаленной команде. Эта стратегия гарантирует, что неустранимые ошибки на одном компьютере не закрывают команду на всех компьютерах, на которых она выполняется. Такой подход используется, даже если удаленная команда выполняется на одном компьютере.
Если удаленный компьютер не входит в домен, которому доверяет локальный компьютер, возможно, он не сможет проверить подлинность учетных данных пользователя. Чтобы добавить удаленный компьютер в список доверенных узлов в WS-Management, используйте следующую команду в WSMAN
поставщике, где <Remote-Computer-Name>
— это имя удаленного компьютера:
Set-Item -Path WSMan:\Localhost\Client\TrustedHosts -Value \<Remote-Computer-Name\>
При отключении PSSession с помощью параметра InDisconnectedSession состояние сеанса будет отключено , а доступность — None. Значение свойства State определяется текущим сеансом. Значение Disconnected означает, что PSSession не подключен к текущему сеансу. Однако это не означает, что PSSession отключен от всех сеансов. Он может быть подключен к другому сеансу. Определить возможность подключения или повторного подключения к сеансу позволяет свойство Availability.
Если свойство Availability имеет значение None, подключиться к сеансу можно. Значение Busy указывает, что вы не можете подключиться к PSSession , так как оно подключено к другому сеансу. Дополнительные сведения о значениях свойства State сеансов см. в разделе RunspaceState. Дополнительные сведения о значениях свойства Availability сеансов см. в разделе RunspaceAvailability.