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>]

Deze cmdlet is alleen beschikbaar op het Windows-platform.

Met de Receive-PSSession-cmdlet worden de resultaten opgehaald van opdrachten die worden uitgevoerd in PowerShell-sessies (PSSession) die zijn verbroken. Als de sessie momenteel is verbonden, krijgt Receive-PSSession de resultaten van opdrachten die werden uitgevoerd toen de sessie werd verbroken. Indien de sessie nog steeds is verbroken, maakt Receive-PSSession verbinding met de sessie, hervat de onderbroken opdrachten en haalt de resultaten op van opdrachten die in de sessie worden uitgevoerd.

Deze cmdlet is geïntroduceerd in PowerShell 3.0.

U kunt een Receive-PSSession naast of in plaats van een Connect-PSSession opdracht gebruiken. Receive-PSSession kan verbinding maken met elke verbroken of opnieuw verbonden sessie die is gestart in andere sessies of op andere computers.

Receive-PSSession werkt op PSSessions die opzettelijk zijn verbroken met behulp van de Disconnect-PSSession cmdlet of de parameter Invoke-CommandInDisconnectedSession. Of onopzettelijk verbroken door een netwerkonderbreking.

Als u de Receive-PSSession-cmdlet gebruikt om verbinding te maken met een sessie waarin geen opdrachten worden uitgevoerd of onderbroken, maakt Receive-PSSession verbinding met de sessie, maar retourneert geen uitvoer of fouten.

Zie about_Remote_Disconnected_Sessionsvoor meer informatie over de functie Niet-verbonden sessies.

In sommige voorbeelden wordt splatting gebruikt om de lijnlengte te verminderen en de leesbaarheid te verbeteren. Zie about_Splattingvoor meer informatie.

In dit voorbeeld wordt verbinding gemaakt met een sessie op een externe computer en worden de resultaten opgehaald van opdrachten die in een sessie worden uitgevoerd.

Receive-PSSession -ComputerName Server01 -Name ITTask

De Receive-PSSession geeft de externe computer op met de parameter ComputerName. De parameter Name identificeert de ITTask-sessie op de Server01-computer. In het voorbeeld worden de resultaten opgehaald van opdrachten die werden uitgevoerd in de ITTask-sessie.

Omdat de opdracht de parameter OutTarget niet gebruikt, worden de resultaten weergegeven op de opdrachtregel.

In dit voorbeeld worden de resultaten opgehaald van alle opdrachten die worden uitgevoerd in alle niet-verbonden sessies op twee externe computers.

Als een sessie niet is verbroken of geen opdrachten uitvoert, maakt Receive-PSSession geen verbinding met de sessie en retourneert geen uitvoer of fouten.

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

Get-PSSession gebruikt de parameter ComputerName om de externe computers op te geven. De objecten worden via de pijpleiding naar Receive-PSSessionverzonden.

In dit voorbeeld wordt de Receive-PSSession-cmdlet gebruikt om de resultaten op te halen van een script dat werd uitgevoerd in de sessie van een externe computer.

$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

De opdracht maakt gebruik van de parameters ComputerName en Name om de niet-verbonden sessie te identificeren. Hierbij wordt de parameter OutTarget met de waarde Job gebruikt om Receive-PSSession de resultaten als een job te laten retourneren. De parameter JobName geeft een naam op voor de taak in de opnieuw verbonden sessie. De parameter Credential voert de opdracht Receive-PSSession uit met behulp van de machtigingen van een domeinbeheerder.

In de uitvoer ziet u dat Receive-PSSession de resultaten als een taak in de huidige sessie heeft geretourneerd. Gebruik een Receive-Job opdracht om de taakresultaten op te halen

In dit voorbeeld wordt de cmdlet Receive-PSSession gebruikt om de resultaten van een taak op te halen nadat een netwerkstoring een sessieverbinding heeft onderbroken. PowerShell probeert de sessie automatisch één keer per seconde opnieuw te verbinden voor de komende vier minuten en de inspanning wordt alleen afgebroken als alle pogingen in het interval van vier minuten mislukken.

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

De New-PSSession cmdlet maakt een sessie op de Server01-computer en slaat de sessie op in de $s variabele. De variabele $s geeft aan dat de Status geopend is en dat de Beschikbaarheid beschikbaar is. Deze waarden geven aan dat u verbonden bent met de sessie en opdrachten in de sessie kunnen uitvoeren.

De cmdlet Invoke-Command voert een script uit in de sessie in de $s variabele. Het script begint met het uitvoeren en retourneren van gegevens, maar er treedt een netwerkstoring op die de sessie onderbreekt. De gebruiker moet de sessie afsluiten en de lokale computer opnieuw opstarten.

Wanneer de computer opnieuw wordt opgestart, start de gebruiker PowerShell en voert de gebruiker een Get-PSSession opdracht uit om sessies op de Server01-computer op te halen. De uitvoer laat zien dat de AD- sessie nog steeds bestaat op de Server01-computer. De toestand geeft aan dat de AD sessie is verbroken. De beschikbaarheid waarde Geen, geeft aan dat de sessie niet is verbonden met clientsessies.

De cmdlet Receive-PSSession maakt opnieuw verbinding met de AD--sessie en haalt de resultaten op van het script dat in de sessie is uitgevoerd. De opdracht gebruikt de parameter OutTarget om de resultaten aan te vragen in een taak met de naam ADJob. De opdracht retourneert een taakobject en de uitvoer geeft aan dat het script nog steeds wordt uitgevoerd.

De cmdlet Get-PSSession wordt gebruikt om de taakstatus te controleren. De uitvoer bevestigt dat de Receive-PSSession cmdlet opnieuw verbinding heeft gemaakt met de AD--sessie, die nu is geopend en beschikbaar is voor opdrachten. En daarna wordt de uitvoering van het script hervat en worden de scriptresultaten opgehaald.

In dit voorbeeld wordt de cmdlet Receive-PSSession gebruikt om opnieuw verbinding te maken met sessies die opzettelijk zijn verbroken en de resultaten te verkrijgen van taken die in de sessies werden uitgevoerd.

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

De cmdlet Invoke-Command voert een script uit op drie externe computers. Omdat het script gegevens uit meerdere databases verzamelt en samenvat, duurt het vaak een langere tijd om het script te voltooien. De opdracht maakt gebruik van de parameter InDisconnectedSession waarmee de scripts worden gestart en de sessies onmiddellijk worden verbroken. De parameter SessionOption breidt de IdleTimeout- waarde van de niet-verbonden sessie uit. Niet-verbonden sessies worden beschouwd als niet-actief vanaf het moment dat de verbinding wordt verbroken. Het is belangrijk om de time-out voor inactiviteit zo lang in te stellen dat de opdrachten kunnen worden voltooid en u opnieuw verbinding kunt maken met de sessie. U kunt de IdleTimeout alleen instellen wanneer u de PSSession maakt en deze alleen wijzigen wanneer u de verbinding verbreekt. U kunt de IdleTimeout--waarde niet wijzigen wanneer u verbinding maakt met een PSSession- of de resultaten ontvangt. Nadat de opdracht is uitgevoerd, sluit de gebruiker PowerShell af en sluit de computer.

De volgende dag hervat de gebruiker Windows, start PowerShell en gebruikt Get-PSSession om de sessies op te halen waarin de scripts werden uitgevoerd. De opdracht identificeert de sessies op basis van de computernaam, sessienaam en de naam van de sessieconfiguratie en slaat de sessies op in de $s variabele. De waarde van de variabele $s wordt weergegeven en geeft aan dat de sessies zijn verbroken, maar niet bezet zijn.

De Receive-PSSession cmdlet maakt verbinding met de sessies in de $s variabele en haalt de resultaten op. Met de opdracht worden de resultaten opgeslagen in de $Results variabele. De variabele $s wordt weergegeven en laat zien dat de sessies zijn verbonden en beschikbaar zijn voor opdrachten.

De resultaten van het script worden weergegeven voor de variabele $Results in de PowerShell-console. Als een van de resultaten onverwacht is, kan de gebruiker opdrachten uitvoeren in de sessies om de hoofdoorzaak te onderzoeken.

In dit voorbeeld ziet u wat er gebeurt met een taak die wordt uitgevoerd in een niet-verbonden sessie.

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

De New-PSSession cmdlet maakt de testsessie op de Server01-computer. Met de opdracht wordt de sessie opgeslagen in de variabele $s.

De cmdlet Invoke-Command voert een opdracht uit in de sessie in de $s variabele. De opdracht gebruikt de parameter AsJob om de opdracht uit te voeren als een taak en maakt het taakobject in de huidige sessie. De opdracht retourneert een taakobject dat is opgeslagen in de $j variabele. De $j-variabele geeft het taakobject weer.

Het sessieobject in de variabele $s wordt naar de pijplijn verzonden naar Disconnect-PSSession en de sessie wordt verbroken.

De $j variabele wordt weergegeven en toont het effect van het loskoppelen van het taakobject in de $j variabele. De taakstatus is nu verbroken.

De Receive-Job wordt uitgevoerd in de $j variabele tijdens de taakuitvoering. De uitvoer toont aan dat de taak uitvoer begon te retourneren voordat de sessie en de taak werden verbroken.

De Connect-PSSession cmdlet wordt uitgevoerd in dezelfde clientsessie. De opdracht maakt opnieuw verbinding met de testsessie op de Server01-computer en slaat de sessie op in de variabele $s2.

De Receive-PSSession cmdlet haalt de resultaten op van de taak die in de sessie is uitgevoerd. Omdat de opdracht in dezelfde sessie wordt uitgevoerd, retourneert Receive-PSSession standaard de resultaten als een taak en wordt hetzelfde taakobject opnieuw gebruikt. Met de opdracht wordt de taak opgeslagen in de variabele $j2. De cmdlet Receive-Job haalt de resultaten van de taak op in de variabele $j.

Deze cmdlet ondersteunt de algemene parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction en -WarningVariable. Zie about_CommonParametersvoor meer informatie.

U kunt sessieobjecten doorsturen naar deze cmdlet, zoals objecten die worden geretourneerd door de Get-PSSession cmdlet.

U kunt sessie-id's doorsluisen naar deze cmdlet.

U kunt de exemplaar-id's van sessies doorsturen met deze cmdlet.

U kunt sessienamen doorsluisen naar deze cmdlet.

Als de waarde of standaardwaarde van de parameter OutTarget is Job, retourneert Receive-PSSession een taakobject.

Deze cmdlet retourneert de resultaten van opdrachten die zijn uitgevoerd in de niet-verbonden sessie, indien van toepassing.

PowerShell bevat de volgende aliassen voor Receive-PSSession:

• Alle platforms:
  • rcsn

Deze cmdlet is alleen beschikbaar op Windows-platforms.

Receive-PSSession krijgt alleen resultaten van sessies die zijn losgekoppeld. Alleen sessies die zijn verbonden met of worden beëindigd op computers met PowerShell 3.0 of hoger, kunnen worden verbroken en opnieuw worden verbonden.

Als de opdrachten die worden uitgevoerd in de niet-verbonden sessie geen resultaten hebben gegenereerd of als de resultaten al zijn geretourneerd naar een andere sessie, genereert Receive-PSSession geen uitvoer.

De uitvoerbuffermodus van een sessie bepaalt hoe opdrachten in de sessie uitvoer beheren wanneer de verbinding met de sessie wordt verbroken. Wanneer de waarde van de OutputBufferingMode-optie van de sessie 'Drop' is en de uitvoerbuffer vol raakt, begint de opdracht met het verwijderen van de uitvoer. Receive-PSSession kan deze uitvoer niet herstellen. Voor meer informatie over de uitvoerbuffermodusoptie, zie de help-artikelen voor de New-PSSessionOption en de New-PSTransportOption cmdlets.

U kunt de time-outwaarde voor inactiviteit van een PSSession- niet wijzigen wanneer u verbinding maakt met de PSSession- of resultaten ontvangt. De SessionOption-parameter van Receive-PSSession accepteert een SessionOption--object dat een IdleTimeout--waarde heeft. De IdleTimeout- waarde van het object SessionOption en de IdleTimeout- waarde van de variabele $PSSessionOption worden echter genegeerd wanneer deze verbinding maakt met een PSSession- of resultaten ontvangt.

• U kunt de time-out voor inactiviteit van een PSSession- instellen en wijzigen wanneer u de PSSession-maakt, met behulp van de New-PSSession- of Invoke-Command-cmdlets en wanneer u de verbinding met de PSSession-verbreekt.
• De eigenschap IdleTimeout van een PSSession- is essentieel voor verbroken sessies, omdat hiermee wordt bepaald hoe lang een niet-verbonden sessie op de externe computer wordt onderhouden. Niet-verbonden sessies worden beschouwd als niet-actief vanaf het moment dat de verbinding is verbroken, zelfs als opdrachten worden uitgevoerd in de niet-verbonden sessie.

Als u een taak in een externe sessie start met behulp van de AsJob parameter van de Invoke-Command cmdlet, wordt het taakobject gemaakt in de huidige sessie, ook al wordt de taak uitgevoerd in de externe sessie. Als u de verbinding met de externe sessie verbreekt, wordt het taakobject in de huidige sessie losgekoppeld van de taak. Het taakobject bevat resultaten die eraan zijn geretourneerd, maar ontvangt geen nieuwe resultaten van de taak in de niet-verbonden sessie.

Als een andere client verbinding maakt met de sessie die de actieve taak bevat, zijn de resultaten die zijn geleverd aan het oorspronkelijke taakobject in de oorspronkelijke sessie niet beschikbaar in de zojuist verbonden sessie. Alleen resultaten die niet aan het oorspronkelijke taakobject zijn geleverd, zijn beschikbaar in de opnieuw verbonden sessie.

Als u een script in een sessie start en vervolgens de verbinding met de sessie verbreekt, zijn eventuele resultaten die het script aan de sessie levert voordat de verbinding wordt verbroken niet beschikbaar voor een andere client die verbinding maakt met de sessie.

Gebruik de parameter InDisconnectedSession parameter van de Invoke-Command cmdlet om gegevensverlies in sessies die u wilt verbreken te voorkomen. Omdat deze parameter voorkomt dat resultaten worden geretourneerd naar de huidige sessie, zijn alle resultaten beschikbaar wanneer de sessie opnieuw verbinding maakt.

U kunt ook gegevensverlies voorkomen met behulp van de cmdlet Invoke-Command om een Start-Job opdracht uit te voeren in de externe sessie. In dit geval wordt het taakobject gemaakt in de externe sessie. U kunt de Receive-PSSession cmdlet niet gebruiken om de taakresultaten op te halen. Gebruik in plaats daarvan de cmdlet Connect-PSSession om verbinding te maken met de sessie en gebruik vervolgens de Invoke-Command cmdlet om een Receive-Job opdracht uit te voeren in de sessie.

Wanneer een sessie met een actieve taak wordt verbroken en vervolgens opnieuw verbinding maakt, wordt het oorspronkelijke taakobject alleen opnieuw gebruikt als de taak is verbroken en opnieuw is verbonden met dezelfde sessie. De opdracht om opnieuw verbinding te maken geeft geen nieuwe taaknaam op. Als de sessie opnieuw verbinding maakt met een andere clientsessie of als er een nieuwe taaknaam is opgegeven, maakt PowerShell een nieuw taakobject voor de nieuwe sessie.

Wanneer u de verbinding met een PSSessionverbreekt, wordt de sessiestatus verbroken en is de beschikbaarheid Geen.

• De waarde van de eigenschap State is relatief ten opzichte van de huidige sessie. De waarde Verbinding verbroken betekent dat de PSSession- niet is verbonden met de huidige sessie. Het betekent echter niet dat de PSSession- is losgekoppeld van alle sessies. Het kan zijn dat deze is verbonden met een andere sessie. Gebruik de eigenschap Availability om te bepalen of u verbinding kunt maken met de sessie of opnieuw verbinding kunt maken met de sessie.
• Een beschikbaarheidswaarde van Geen geeft aan dat u verbinding kunt maken met de sessie. Een waarde van Bezet geeft aan dat u geen verbinding kunt maken met de PSSession- omdat deze is verbonden met een andere sessie.
• Zie RunspaceStatevoor meer informatie over de waarden van de eigenschap State van sessies.
• Zie RunspaceAvailabilityvoor meer informatie over de waarden van de eigenschap Availability van sessies.