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>
       [-ApplicationName <String>]
       [-ConfigurationName <String>]
       -Name <String>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-Port <Int32>]
       [-UseSSL]
       [-SessionOption <PSSessionOption>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

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

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

Receive-PSSession
       [-ConfigurationName <String>]
       [-ConnectionUri] <Uri>
       [-AllowRedirection]
       -InstanceId <Guid>
       [-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 で導入されました。

Connect-PSSession コマンドの代わりに、Receive-PSSessionを使用できます。 Receive-PSSession は、他のセッションまたは他のコンピューターで開始された切断または再接続されたセッションに接続できます。

Receive-PSSessionは、Disconnect-PSSession コマンドレットまたは Invoke-Command InDisconnectedSession パラメーターを使用して意図的に切断されたPSSessionsで動作します。 または、ネットワークの中断によって意図せず切断されました。

Receive-PSSession コマンドレットを使用して、コマンドが実行または中断されていないセッションに接続する場合、Receive-PSSessionはセッションに接続しますが、出力やエラーは返されません。

切断されたセッション機能の詳細については、「 about_Remote_Disconnected_Sessions」を参照してください。

一部の例では、スプラッティングを使用して行の長さを減らし、読みやすさを向上させます。 詳細については、「 about_Splatting」を参照してください。

例

例 1: PSSession に接続する

次の使用例は、リモート コンピューター上のセッションに接続し、セッションで実行されているコマンドの結果を取得します。

Receive-PSSession -ComputerName Server01 -Name ITTask

Receive-PSSessionは、ComputerName パラメーターを持つリモート コンピューターを指定します。 Name パラメーターは、Server01 コンピューター上の ITTask セッションを識別します。 この例では、ITTask セッションで実行されていたコマンドの結果を取得します。

コマンドは OutTarget パラメーターを使用しないため、結果はコマンド ラインに表示されます。

例 2: 切断されたセッションのすべてのコマンドの結果を取得する

この例では、2 台のリモート コンピューター上のすべての切断されたセッションで実行されているすべてのコマンドの結果を取得します。

セッションが切断されていない場合、またはコマンドを実行していない場合、 Receive-PSSession はセッションに接続せず、出力やエラーは返されません。

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

Get-PSSession は、 ComputerName パラメーターを使用してリモート コンピューターを指定します。 オブジェクトはパイプラインに送信され、 Receive-PSSessionされます。

例 3: セッションで実行されているスクリプトの結果を取得する

この例では、 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 パラメーターは、再接続されたセッション内のジョブの名前を指定します。 Credential パラメーターは、ドメイン管理者のアクセス許可を使用してReceive-PSSession コマンドを実行します。

出力は、 Receive-PSSession が現在のセッションでジョブとして結果を返したことを示しています。 ジョブの結果を取得するには、 Receive-Job コマンドを使用します。

例 4: ネットワークの停止後に結果を取得する

この例では、 Receive-PSSession コマンドレットを使用して、ネットワークの停止によってセッション接続が中断された後のジョブの結果を取得します。 PowerShell は、次の 4 分間に 1 秒に 1 回セッションの再接続を自動的に試行し、4 分間のすべての試行が失敗した場合にのみ、作業を中止します。

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変数には、State が Opened で、Availability が使用可能であることが表示されます。 これらの値は、セッションに接続していること、およびセッションでコマンドを実行できることを示します。

Invoke-Command コマンドレットは、$s変数内のセッションでスクリプトを実行します。 スクリプトの実行とデータの返しが開始されますが、セッションを中断するネットワーク障害が発生します。 ユーザーはセッションを終了し、ローカル コンピューターを再起動する必要があります。

コンピューターが再起動すると、ユーザーは PowerShell を起動し、 Get-PSSession コマンドを実行して Server01 コンピューター上のセッションを取得します。 出力は、 AD セッションがまだ Server01 コンピューターに存在することを示しています。 State は、AD セッションが切断されていることを示します。 Availability値 None は、セッションがクライアント セッションに接続されていないことを示します。

Receive-PSSession コマンドレットは、AD セッションに再接続し、セッションで実行されたスクリプトの結果を取得します。 コマンドは、 OutTarget パラメーターを使用して、 ADJob という名前のジョブで結果を要求します。 このコマンドはジョブ オブジェクトを返し、出力はスクリプトがまだ実行されていることを示します。

Get-PSSession コマンドレットは、ジョブの状態を確認するために使用されます。 出力は、 Receive-PSSession コマンドレットが AD セッションに再接続されたことを確認します。このセッションは、コマンドで開いて使用できるようになりました。 そして、スクリプトは実行を再開し、スクリプトの結果を取得しています。

例 5: 切断されたセッションに再接続する

この例では、 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 コマンドレットは、3 台のリモート コンピューターでスクリプトを実行します。 スクリプトは複数のデータベースからデータを収集して集計するため、多くの場合、スクリプトが完了するまでに時間がかかります。 このコマンドは、スクリプトを開始し、すぐにセッションを切断する InDisconnectedSession パラメーターを使用します。 SessionOption パラメーターは、切断されたセッションのIdleTimeout値を拡張します。 切断されたセッションは、切断された時点からアイドル状態と見なされます。 コマンドが完了し、セッションに再接続できるように、アイドルタイムアウトを十分な長さに設定することが重要です。 IdleTimeoutPSSession を作成した場合にのみ設定し接続を切断したときにのみ変更できます。 PSSession に接続したり結果を受け取ったりするときに、IdleTimeout 値を変更することはできません。 コマンドを実行すると、ユーザーは PowerShell を終了し、コンピューターを閉じます。

翌日、ユーザーは Windows を再開し、PowerShell を起動し、 Get-PSSession を使用してスクリプトが実行されていたセッションを取得します。 このコマンドは、コンピューター名、セッション名、およびセッション構成の名前によってセッションを識別し、セッションを $s 変数に保存します。 $s変数の値が表示され、セッションが切断されているがビジー状態でないことを示します。

Receive-PSSession コマンドレットは、$s変数内のセッションに接続し、その結果を取得します。 このコマンドは、結果を $Results 変数に保存します。 $s変数が表示され、セッションが接続され、コマンドで使用可能であることが示されます。

スクリプトの結果、 $Results 変数が PowerShell コンソールに表示されます。 いずれかの結果が予期しない場合、ユーザーはセッションでコマンドを実行して根本原因を調査できます。

例 6: 切断されたセッションでのジョブの実行

この例では、切断されたセッションで実行されているジョブの動作を示します。

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 コマンドレットは、同じクライアント セッションで実行されます。 このコマンドは、Server01 コンピューター上のテスト セッションに再接続し、セッションを $s2 変数に保存します。

Receive-PSSession コマンドレットは、セッションで実行されていたジョブの結果を取得します。 コマンドは同じセッションで実行されるため、 Receive-PSSession は既定で結果をジョブとして返し、同じジョブ オブジェクトを再利用します。 このコマンドは、ジョブを $j2 変数に保存します。 Receive-Job コマンドレットは、$j変数内のジョブの結果を取得します。

パラメーター

-AllowRedirection

-ApplicationName

-Authentication

-CertificateThumbprint

-ComputerName

-ConfigurationName

-Confirm

-ConnectionUri

-Credential

-Id

-InstanceId

-JobName

-Name

-OutTarget

-Port

-Session

-SessionOption

-UseSSL

-WhatIf

入力

PSSession

Get-PSSession コマンドレットによって返されるオブジェクトなど、セッション オブジェクトをこのコマンドレットにパイプできます。

Int32

このコマンドレットにセッション ID をパイプできます。

Guid

このコマンドレットでは、セッションのインスタンス ID をパイプ処理できます。

String

このコマンドレットにセッション名をパイプできます。

出力

Job

OutTarget パラメーターの値または既定値がJobの場合、Receive-PSSessionはジョブ オブジェクトを返します。

PSObject

このコマンドレットは、切断されたセッションで実行されたコマンド (ある場合) の結果を返します。

メモ

PowerShell には、 Receive-PSSessionの次のエイリアスが含まれています。

• すべてのプラットフォーム:
  • rcsn

このコマンドレットは、Windows プラットフォームでのみ使用できます。

Receive-PSSession は、切断されたセッションからのみ結果を取得します。 切断して再接続できるのは、PowerShell 3.0 以降のバージョンを実行するコンピューターに接続されている、または終了するセッションだけです。

切断されたセッションで実行されていたコマンドで結果が生成されなかった場合、または結果が既に別のセッションに返された場合、 Receive-PSSession は出力を生成しません。

セッションの出力バッファリング モードは、セッションが切断されたときにセッション内のコマンドが出力を管理する方法を決定します。 セッションの OutputBufferingMode オプションの値が Drop で、出力バッファーがいっぱいになると、コマンドは出力の削除を開始します。 Receive-PSSession は、この出力を回復できません。 出力バッファリング モード オプションの詳細については、 New-PSSessionOption および New-PSTransportOption コマンドレットのヘルプ記事を参照してください。

PSSession に接続するときPSSession のアイドル タイムアウト値を変更したり結果を受け取ったりすることはできません。 Receive-PSSession の SessionOption パラメーターは、IdleTimeout 値を持つ SessionOption オブジェクトを受け取ります。 ただし、SessionOption オブジェクトのIdleTimeout値と$PSSessionOption変数のIdleTimeout値は、PSSessionに接続したり、結果を受け取ったりするときに無視されます。

• PSSessionPSSession を作成する場合、New-PSSessionまたはInvoke-Commandコマンドレットを使用してPSSession から切断するときに、アイドルタイムアウトを設定および変更できます。
• PSSession の IdleTimeout プロパティは、切断されたセッションがリモート コンピューターで維持される期間を決定するため、切断されたセッションにとって重要です。 セッションが切断されると、その時点からアイドル状態であると判断されます。これは、そのセッションでコマンドを実行している場合であっても同じです。

Invoke-Command コマンドレットの AsJob パラメーターを使用してリモート セッションでジョブを開始すると、ジョブがリモート セッションで実行されている場合でも、ジョブ オブジェクトが現在のセッションに作成されます。 リモート セッションを切断すると、現在のセッションのジョブ オブジェクトがジョブから切断されます。 ジョブ オブジェクトには、返された結果が含まれていますが、切断されたセッションでジョブから新しい結果を受け取りません。

実行中のジョブを含むセッションに別のクライアントが接続した場合、元のセッションの元のジョブ オブジェクトに配信された結果は、新しく接続されたセッションでは使用できません。 再接続したセッションでは、元のジョブ オブジェクトに配信されなかった結果のみ利用できます。

同様に、セッションでスクリプトを開始してからセッションから切断した場合、切断前にスクリプトがセッションに配信した結果は、セッションに接続する別のクライアントでは使用できません。

切断するセッションでデータが失われるのを防ぐには、Invoke-Command コマンドレットの InDisconnectedSession パラメーターを使用します。 このパラメーターは現在のセッションに結果が返されないようにするものであるため、セッションに再接続した時点で結果がすべて利用できるようになります。

Invoke-Command コマンドレットを使用してリモート セッションでStart-Job コマンドを実行することで、データ損失を防ぐこともできます。 この場合には、リモート セッションでジョブ オブジェクトが作成されます。 Receive-PSSession コマンドレットを使用してジョブの結果を取得することはできません。 代わりに、 Connect-PSSession コマンドレットを使用してセッションに接続し、 Invoke-Command コマンドレットを使用してセッションで Receive-Job コマンドを実行します。

実行中のジョブを含むセッションが切断されてから再接続されると、元のジョブ オブジェクトは、ジョブが切断されて同じセッションに再接続され、再接続するコマンドで新しいジョブ名が指定されていない場合にのみ再利用されます。 セッションが別のクライアント セッションに再接続されるか、新しいジョブ名が指定されている場合、PowerShell は新しいセッションの新しいジョブ オブジェクトを作成します。

PSSessionを切断すると、セッションの状態は切断され、可用性は None になります。

• State プロパティの値は、現在のセッションに対する相対値です。 Disconnected の値は、 PSSession が現在のセッションに接続されていないことを意味します。 ただし、 PSSession がすべてのセッションから切断されているわけではありません。 別のセッションに接続されている可能性があるためです。 セッションに接続できるか再接続できるかを判断するには、 Availability プロパティを使用します。
• Availability値 None は、セッションに接続できることを示します。 [ビジー] の値は、別のセッションに接続されているためPSSession に接続できないことを示します。
• セッションの State プロパティの値の詳細については、「 RunspaceState」を参照してください。
• セッションの Availability プロパティの値の詳細については、「 RunspaceAvailability」を参照してください。

関連リンク

• about_PSSessions
• about_Remote に関するページ
• about_Remote_Disconnected_Sessions
• about_Session_Configurations
• Connect-PSSession
• Enter-PSSession
• Exit-PSSession
• Get-PSSession
• Invoke-Command
• New-PSSession
• New-PSSessionOption
• New-PSSessionOption
• Remove-PSSession