Receive-PSSession

Receive-PSSession
    [-Session] <PSSession>
    [-OutTarget <OutTarget>]
    [-JobName <String>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Receive-PSSession
    [-Id] <Int32>
    [-OutTarget <OutTarget>]
    [-JobName <String>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Receive-PSSession
    [-ComputerName] <String>
    -Name <String>
    [-ApplicationName <String>]
    [-ConfigurationName <String>]
    [-OutTarget <OutTarget>]
    [-JobName <String>]
    [-Credential <PSCredential>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <String>]
    [-Port <Int32>]
    [-UseSSL]
    [-SessionOption <PSSessionOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Receive-PSSession
    [-ComputerName] <String>
    -InstanceId <Guid>
    [-ApplicationName <String>]
    [-ConfigurationName <String>]
    [-OutTarget <OutTarget>]
    [-JobName <String>]
    [-Credential <PSCredential>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <String>]
    [-Port <Int32>]
    [-UseSSL]
    [-SessionOption <PSSessionOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Receive-PSSession
    [-ConnectionUri] <Uri>
    -Name <String>
    [-ConfigurationName <String>]
    [-AllowRedirection]
    [-OutTarget <OutTarget>]
    [-JobName <String>]
    [-Credential <PSCredential>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <String>]
    [-SessionOption <PSSessionOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Receive-PSSession
    [-ConnectionUri] <Uri>
    -InstanceId <Guid>
    [-ConfigurationName <String>]
    [-AllowRedirection]
    [-OutTarget <OutTarget>]
    [-JobName <String>]
    [-Credential <PSCredential>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <String>]
    [-SessionOption <PSSessionOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Receive-PSSession
    -InstanceId <Guid>
    [-OutTarget <OutTarget>]
    [-JobName <String>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Receive-PSSession
    -Name <String>
    [-OutTarget <OutTarget>]
    [-JobName <String>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Этот командлет доступен только на платформе Windows.

Командлет Receive-PSSession получает результаты команд, выполняемых в сеансах PowerShell (PSSession), которые были отключены. Если сеанс подключен в данный момент, Receive-PSSession получает результаты команд, выполняемых при отключении сеанса. Если сеанс по-прежнему отключен, Receive-PSSession подключается к сеансу, возобновляет все команды, которые были приостановлены, и получает результаты команд, выполняемых в сеансе.

Этот командлет был введён в PowerShell 3.0.

Вы можете использовать Receive-PSSession в дополнение или вместо команды Connect-PSSession. Receive-PSSession может подключаться к любому отключенному или повторно подключенному сеансу, который был запущен в рамках других сеансов или на других компьютерах.

Receive-PSSession работает над PSSessions, которые были отключены намеренно с помощью командлета Disconnect-PSSession или параметра Invoke-CommandInDisconnectedSession. Или отключается непреднамеренно путем прерывания сети.

Если вы используете командлет Receive-PSSession для подключения к сеансу, в котором команды не выполняются или приостановлены, Receive-PSSession подключается к сеансу, но не возвращает выходные данные или ошибки.

Дополнительные сведения о функции разъединённых сеансов см. в разделе about_Remote_Disconnected_Sessions.

В некоторых примерах используется сложение для уменьшения длины строки и повышения удобочитаемости. Дополнительные сведения см. в about_Splatting.

Этот пример подключается к сеансу на удаленном компьютере и получает результаты команд, выполняемых в сеансе.

Receive-PSSession -ComputerName Server01 -Name ITTask

Receive-PSSession указывает удаленный компьютер с параметром ComputerName. Параметр имени определяет сеанс ITTask на компьютере Server01. Пример получает результаты команд, выполняемых в сеансе ITTask.

Так как команда не использует параметр OutTarget, результаты отображаются в командной строке.

Этот пример получает результаты всех команд, выполняемых во всех отключенных сеансах на двух удаленных компьютерах.

Если какой-либо сеанс не был отключен или не выполняет команды, Receive-PSSession не подключается к сеансу и не возвращает никаких выходных данных или ошибок.

Get-PSSession -ComputerName Server01, Server02 | Receive-PSSession

Get-PSSession использует параметр ComputerName для указания удаленных компьютеров. Объекты отправляются по конвейеру в Receive-PSSession.

В этом примере используется командлет Receive-PSSession для получения результатов скрипта, выполняющегося в сеансе удаленного компьютера.

$parms = @{
  ComputerName = "Server01"
  Name = "ITTask"
  OutTarget = "Job"
  JobName = "ITTaskJob01"
  Credential = "Domain01\Admin01"
}
Receive-PSSession @parms

Id     Name            State         HasMoreData     Location
--     ----            -----         -----------     --------
16     ITTaskJob01     Running       True            Server01

Команда использует параметры ComputerName и Name для идентификации отключенного сеанса. Он использует параметр OutTarget со значением Job, чтобы направлять Receive-PSSession для возврата результатов в качестве задания. Параметр JobName указывает имя задания в повторно подключенном сеансе. Параметр учетных данных запускает команду Receive-PSSession с помощью разрешений администратора домена.

В выходных данных показано, что Receive-PSSession вернул результаты в качестве задания в текущем сеансе. Чтобы получить результаты задания, используйте команду Receive-Job

В этом примере используется командлет Receive-PSSession для получения результатов задания после сбоя в работе сети, который прерывает подключение сеанса. PowerShell автоматически пытается повторно подключить сеанс один раз в секунду в течение следующих четырех минут и отказывается от усилий, только если все попытки в четырехминутном интервале завершаются ошибкой.

PS> $s = New-PSSession -ComputerName Server01 -Name AD -ConfigurationName ADEndpoint
PS> $s

Id  Name   ComputerName    State        ConfigurationName     Availability
--  ----   ------------    -----        -----------------     ------------
8   AD      Server01       Opened       ADEndpoint               Available


PS> Invoke-Command -Session $s -FilePath \\Server12\Scripts\SharedScripts\New-ADResolve.ps1

Running "New-ADResolve.ps1"

# Network outage
# Restart local computer
# Network access is not re-established within 4 minutes


PS> Get-PSSession -ComputerName Server01

Id  Name   ComputerName    State          ConfigurationName      Availability
--  ----   ------------    -----          -----------------      ------------
1  Backup  Server01        Disconnected   Microsoft.PowerShell           None
8  AD      Server01        Disconnected   ADEndpoint                     None


PS> Receive-PSSession -ComputerName Server01 -Name AD -OutTarget Job -JobName AD

Job Id   Name      State         HasMoreData     Location
--       ----      -----         -----------     --------
16       ADJob     Running       True            Server01


PS> Get-PSSession -ComputerName Server01

Id  Name    ComputerName    State         ConfigurationName     Availability
--  ----    ------------    -----         -----------------     ------------
1  Backup   Server01        Disconnected  Microsoft.PowerShell          Busy
8  AD       Server01        Opened        ADEndpoint               Available

Командлет New-PSSession создает сеанс на компьютере Server01 и сохраняет сеанс в переменной $s. Переменная $s отображает, что состояние для открыто, а доступность для доступна. Эти значения указывают, что вы подключены к сеансу и можете выполнять команды в сеансе.

Командлет Invoke-Command запускает скрипт в сеансе в переменной $s. Скрипт начинает выполнять и возвращать данные, но сетевой сбой возникает, что прерывает сеанс. Пользователь должен выйти из сеанса и перезапустить локальный компьютер.

При перезапуске компьютера пользователь запускает PowerShell и запускает команду Get-PSSession для получения сеансов на компьютере Server01. Выходные данные показывают, что сеанс AD всё ещё существует на компьютере Server01. состояние указывает, что сеанс AD отключен. Значение доступности Нет указывает, что сеанс не подключен к какому-либо клиентскому сеансу.

Командлет Receive-PSSession повторно подключается к сеансу Active Directory и получает результаты скрипта, запущенного в сеансе. Команда использует параметр OutTarget для запроса результатов задания с именем ADJob. Команда возвращает объект задания и выходные данные указывают на то, что скрипт по-прежнему выполняется.

Командлет Get-PSSession используется для проверки состояния задания. Результаты подтверждают, что командлет Receive-PSSession заново подключился к сеансу AD, который теперь открыт и доступен для выполнения команд. И скрипт возобновил выполнение и получает результаты скрипта.

В этом примере используется командлет Receive-PSSession для повторного подключения к сеансам, которые были намеренно отключены и получать результаты заданий, выполняемых в сеансах.

PS> $parms = @{
      InDisconnectedSession = $true
      ComputerName = "Server01", "Server02", "Server30"
      FilePath = "\\Server12\Scripts\SharedScripts\Get-BugStatus.ps1"
      Name = "BugStatus"
      SessionOption = @{IdleTimeout = 86400000}
      ConfigurationName = "ITTasks"
    }
PS> Invoke-Command @parms
PS> exit


PS> $s = Get-PSSession -ComputerName Server01, Server02, Server30 -Name BugStatus
PS> $s

Id  Name   ComputerName    State         ConfigurationName     Availability
--  ----   ------------    -----         -----------------     ------------
1  ITTask  Server01        Disconnected  ITTasks                       None
8  ITTask  Server02        Disconnected  ITTasks                       None
2  ITTask  Server30        Disconnected  ITTasks                       None


PS> $Results = Receive-PSSession -Session $s
PS> $s

Id  Name   ComputerName    State         ConfigurationName     Availability
--  ----   ------------    -----         -----------------     ------------
1  ITTask  Server01        Opened        ITTasks                  Available
8  ITTask  Server02        Opened        ITTasks                  Available
2  ITTask  Server30        Opened        ITTasks                  Available


PS> $Results

Bug Report - Domain 01
----------------------
ComputerName          BugCount          LastUpdated
--------------        ---------         ------------
Server01              121               Friday, December 30, 2011 5:03:34 PM

Командлет Invoke-Command запускает скрипт на трех удаленных компьютерах. Поскольку скрипт собирает и суммирует данные из нескольких баз данных, его выполнение часто занимает много времени. Команда использует параметр InDisconnectedSession, который запускает скрипты, а затем немедленно отключает сеансы. Параметр SessionOption увеличивает значение IdleTimeout для отключенного сеанса. Отключенные сеансы считаются неактивными с момента их отключения. Важно задать время ожидания простоя достаточно долго, чтобы команды могли завершиться, и вы можете повторно подключиться к сеансу. Вы можете задать IdleTimeout только при создании PSSession и изменить его только при отключении от сессии. Невозможно изменить значение IdleTimeout при подключении к PSSession или получении результатов. После выполнения команды пользователь выходит из PowerShell и закрывает компьютер.

На следующий день пользователь возобновляет Windows, запускает PowerShell и использует Get-PSSession для получения сеансов, в которых выполнялись скрипты. Команда определяет сеансы по имени компьютера, имени сеанса и имени конфигурации сеанса и сохраняет сеансы в переменной $s. Отображается значение переменной $s и показывает, что сеансы отключены, но не заняты.

Командлет Receive-PSSession подключается к сеансам в переменной $s и получает их результаты. Команда сохраняет результаты в переменной $Results. Отображается переменная $s и показывает, что сеансы подключены и доступны для команд.

Сценарий приводит к отображению переменной $Results в консоли PowerShell. Если какой-либо из результатов непредвиден, пользователь может выполнить команды в сеансах, чтобы изучить первопричину.

В этом примере показано, что происходит с заданием, выполняющимся в отключенном сеансе.

PS> $s = New-PSSession -ComputerName Server01 -Name Test
PS> $j = Invoke-Command -Session $s { 1..1500 | ForEach-Object {"Return $_"; sleep 30}} -AsJob
PS> $j

Id     Name           State         HasMoreData     Location
--     ----           -----         -----------     --------
16     Job1           Running       True            Server01


PS> $s | Disconnect-PSSession

Id Name   ComputerName    State         ConfigurationName     Availability
-- ----   ------------    -----         -----------------     ------------
1  Test   Server01        Disconnected  Microsoft.PowerShell          None


PS> $j

Id     Name           State         HasMoreData     Location
--     ----           -----         -----------     --------
16     Job1           Disconnected  True            Server01


PS> Receive-Job $j -Keep

Return 1
Return 2


PS> $s2 = Connect-PSSession -ComputerName Server01 -Name Test
PS> $j2 = Receive-PSSession -ComputerName Server01 -Name Test
PS> Receive-Job $j

Return 3
Return 4

Командлет New-PSSession создает сеанс тестирования на компьютере Server01. Команда сохраняет сеанс в переменной $s.

Командлет Invoke-Command выполняет команду в сеансе, используя переменную $s. Команда использует параметр AsJob для выполнения команды в качестве задания и создает объект задания в текущем сеансе. Команда возвращает объект задания, сохраненный в переменной $j. Переменная $j отображает объект задания.

Объект сеанса в переменной $s отправляется по конвейеру в Disconnect-PSSession и сеанс отключен.

Переменная $j отображается и демонстрирует эффект отключения объекта задания на переменной $j. Состояние задания теперь отключено.

Receive-Job выполняется в задании в переменной $j. Выходные данные показывают, что задание начало возвращать выходные данные до сеанса и задание было отключено.

Командлет Connect-PSSession выполняется в том же сеансе клиента. Команда повторно подключается к сеансу test на компьютере Server01 и сохраняет сеанс в переменной $s2.

Командлет Receive-PSSession получает результаты задания, которое выполнялось в сеансе. Так как команда выполняется в том же сеансе, Receive-PSSession возвращает результаты в качестве задания по умолчанию и повторно использует тот же объект задания. Команда сохраняет задание в переменной $j2. Командлет Receive-Job получает результаты задания в переменной $j.

Этот командлет поддерживает общие параметры: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction и -WarningVariable. Дополнительные сведения см. в разделе about_CommonParameters.

Объекты сеанса можно передать в этот командлет, например объекты, возвращаемые командлетом Get-PSSession.

Идентификаторы сеанса можно передать в этот командлет.

Вы можете передать идентификаторы экземпляров сеансов этому командлету.

Имена сеансов можно передать в этот командлет.

Если значение (по умолчанию) параметра OutTarget равно Job, Receive-PSSession возвращает объект задания.

Этот командлет возвращает результаты команд, которые выполнялись в отключенном сеансе, если таковые есть.

PowerShell включает следующие псевдонимы для Receive-PSSession:

• Все платформы:
  • rcsn

Этот командлет доступен только на платформах Windows.

Receive-PSSession получает результаты только из сеансов, которые были отключены. Только сеансы, которые подключаются к компьютерам или завершаются на компьютерах с PowerShell 3.0 или более поздними версиями, могут быть отключены и повторно подключены.

Если команды, выполняемые в отключенном сеансе, не создавали результаты или если результаты уже были возвращены в другой сеанс, Receive-PSSession не создает никаких выходных данных.

Режим буферизации выходных данных сеанса определяет, как команды в сеансе управляют выходными данными при отключении сеанса. Если значение параметра OutputBufferingMode сеанса— Drop, а выходной буфер заполнен, команда начинает удалять выходные данные. Receive-PSSession не удается восстановить эти выходные данные. Дополнительные сведения о параметре режима буферизации выходных данных можно найти в статьях справки к командлетам New-PSSessionOption и New-PSTransportOption.

Невозможно изменить значение времени ожидания простоя PSSession при подключении к PSSession или при получении результатов. Параметр SessionOptionReceive-PSSession принимает объект SessionOption, имеющий значение IdleTimeout. Однако значение IdleTimeout объекта SessionOption и значение IdleTimeout переменной $PSSessionOption игнорируются при подключении к PSSession или получении результатов.

• Вы можете задать и изменить время ожидания PSSession при создании PSSessionс помощью командлетов New-PSSession или Invoke-Command, а также при отключении от PSSession.
• Свойство IdleTimeout PSSession имеет решающее значение для отключенных сеансов, так как определяет, сколько времени сеанс отключен на удаленном компьютере сохраняется. Отключенные сеансы считаются неактивными с момента отключения, даже если команды выполняются в отключенном сеансе.

При запуске задания в удаленном сеансе с помощью параметра AsJob командлета Invoke-Command объект задания создается в текущем сеансе, даже если задание выполняется в удаленном сеансе. При отключении удаленного сеанса объект задания в текущем сеансе отключен от задания. Объект задания содержит все результаты, возвращенные в него, но не получает новые результаты от задания в отключенном сеансе.

Если другой клиент подключается к сеансу, который содержит выполняемое задание, результаты, доставленные в исходный объект задания в исходном сеансе, недоступны в только что подключенном сеансе. В сеансе повторного подключения доступны только результаты, которые не были доставлены в исходный объект задания.

Аналогичным образом, если вы запускаете скрипт в сеансе, а затем отключаете от сеанса, все результаты, которые скрипт доставляет в сеанс до отключения, недоступны другому клиенту, который подключается к сеансу.

Чтобы предотвратить потерю данных в сеансах, которые планируется отключить, используйте параметр InDisconnectedSession командлета Invoke-Command. Так как этот параметр предотвращает возврат результатов в текущий сеанс, все результаты будут доступны при повторном подключении сеанса.

Вы также можете предотвратить потерю данных с помощью командлета Invoke-Command для выполнения команды Start-Job в удаленном сеансе. В этом случае объект задания создается в удаленном сеансе. Для получения результатов задания нельзя использовать командлет Receive-PSSession. Вместо этого используйте командлет Connect-PSSession для подключения к сеансу, а затем используйте командлет Invoke-Command для выполнения команды Receive-Job в сеансе.

Если сеанс, содержащий запущенное задание, отключен и повторно подключен, исходный объект задания повторно используется только в том случае, если задание отсоединяется и повторно подключается к одному сеансу, а команда повторного подключения не указывает новое имя задания. Если сеанс повторно подключается к другому клиентскому сеансу или новому имени задания, PowerShell создает новый объект задания для нового сеанса.

При отключении PSSessionсостояние сеанса — Отключено, а доступность отсутствует.

• Значение свойства состояния является относительным для текущего сеанса. Значение "Отключено" означает, что PSSession не подключен к текущему сеансу. Однако это не означает, что PSSession отключен от всех сеансов. Он может быть подключен к другому сеансу. Чтобы определить, можно ли подключиться или повторно подключиться к сеансу, используйте свойство доступности.
• Значение доступности "None" указывает, что вы можете подключиться к сеансу. Значение "Занято" указывает, что вы не можете подключиться к PSSession, так как он подключен к другому сеансу.
• Дополнительные сведения о значениях свойства состояния сеансов см. в разделе RunspaceState.
• Дополнительные сведения о значениях свойства Availability сеансов смотрите в разделе RunspaceAvailability.