Delen via


Invoke-Command

Voert opdrachten uit op lokale en externe computers.

Syntaxis

Invoke-Command
      [-StrictMode <Version>]
      [-ScriptBlock] <ScriptBlock>
      [-NoNewScope]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]
Invoke-Command
      [[-Session] <PSSession[]>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-FilePath] <String>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]
Invoke-Command
      [[-Session] <PSSession[]>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      [-RemoteDebug]
      [-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]
      [-RemoteDebug]
      [-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]
      [-RemoteDebug]
      [-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]
      [-RemoteDebug]
      [-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]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]
Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-ScriptBlock] <ScriptBlock>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-VMId] <Guid[]>
      [<CommonParameters>]
Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-ScriptBlock] <ScriptBlock>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -VMName <String[]>
      [<CommonParameters>]
Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-VMId] <Guid[]>
      [<CommonParameters>]
Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -VMName <String[]>
      [<CommonParameters>]
Invoke-Command
      [-Port <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      -HostName <String[]>
      [-UserName <String>]
      [-KeyFilePath <String>]
      [-Subsystem <String>]
      [-ConnectingTimeout <Int32>]
      [-SSHTransport]
      [-Options <Hashtable>]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]
Invoke-Command
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      [-RunAsAdministrator]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -ContainerId <String[]>
      [<CommonParameters>]
Invoke-Command
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-FilePath] <String>
      [-RunAsAdministrator]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -ContainerId <String[]>
      [<CommonParameters>]
Invoke-Command
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      -SSHConnection <Hashtable[]>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]
Invoke-Command
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      -HostName <String[]>
      [-UserName <String>]
      [-KeyFilePath <String>]
      [-Subsystem <String>]
      [-ConnectingTimeout <Int32>]
      [-SSHTransport]
      [-Options <Hashtable>]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]
Invoke-Command
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      -SSHConnection <Hashtable[]>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Description

De Invoke-Command cmdlet voert opdrachten uit op een lokale of externe computer en retourneert alle uitvoer van de opdrachten, inclusief fouten. Met één Invoke-Command opdracht kunt u opdrachten uitvoeren op meerdere computers.

Als u één opdracht wilt uitvoeren op een externe computer, gebruikt u de parameter ComputerName . Als u een reeks gerelateerde opdrachten wilt uitvoeren die gegevens delen, gebruikt u de New-PSSession cmdlet om een PSSession (een permanente verbinding) op de externe computer te maken en gebruikt u vervolgens de sessieparameter om Invoke-Command de opdracht uit te voeren in de PSSession. Als u een opdracht wilt uitvoeren in een niet-verbonden sessie, gebruikt u de parameter InDisconnectedSession . Als u een opdracht in een achtergrondtaak wilt uitvoeren, gebruikt u de parameter AsJob .

U kunt ook op een lokale computer gebruiken Invoke-Command om een scriptblok uit te voeren als opdracht. PowerShell voert het scriptblok direct uit in een onderliggend bereik van het huidige bereik.

Invoke-Command Lees about_Remote voordat u opdrachten uitvoert op een externe computer.

Vanaf PowerShell 6.0 kunt u Secure Shell (SSH) gebruiken om verbinding te maken met en opdrachten aan te roepen op externe computers. SSH moet worden geïnstalleerd op de lokale computer en de externe computer moet worden geconfigureerd met een PowerShell SSH-eindpunt. Het voordeel van een externe PowerShell-sessie op basis van SSH is dat deze werkt op meerdere platforms (Windows, Linux, macOS). Voor een SSH-sessie gebruikt u de parameters HostName of SSHConnection om de externe computer en relevante verbindingsgegevens op te geven. Zie externe communicatie van PowerShell via SSH voor meer informatie over het instellen van externe communicatie van PowerShell via SSH.

Sommige codevoorbeelden gebruiken splatting om de lijnlengte te verminderen. Zie about_Splatting voor meer informatie.

Voorbeelden

Voorbeeld 1: Een script uitvoeren op een server

In dit voorbeeld wordt het Test.ps1 script uitgevoerd op de Server01-computer.

Invoke-Command -FilePath c:\scripts\test.ps1 -ComputerName Server01

De Parameter FilePath geeft een script op dat zich op de lokale computer bevindt. Het script wordt uitgevoerd op de externe computer en de resultaten worden geretourneerd naar de lokale computer.

Voorbeeld 2: Een opdracht uitvoeren op een externe server

In dit voorbeeld wordt een Get-Culture opdracht uitgevoerd op de externe Server01-computer.

Invoke-Command -ComputerName Server01 -Credential Domain01\User01 -ScriptBlock {
    Get-Culture
}

De parameter ComputerName geeft de naam van de externe computer op. De referentieparameter wordt gebruikt om de opdracht uit te voeren in de beveiligingscontext van Domain01\User01, een gebruiker die gemachtigd is om opdrachten uit te voeren. De parameter ScriptBlock geeft de opdracht op die moet worden uitgevoerd op de externe computer.

Als reactie vraagt PowerShell het wachtwoord en een verificatiemethode voor het User01-account aan. Vervolgens wordt de opdracht uitgevoerd op de Server01-computer en wordt het resultaat geretourneerd.

Voorbeeld 3: Een opdracht uitvoeren in een permanente verbinding

In dit voorbeeld wordt dezelfde Get-Culture opdracht uitgevoerd in een sessie, met behulp van een permanente verbinding, op de externe computer met de naam Server02.

$s = New-PSSession -ComputerName Server02 -Credential Domain01\User01
Invoke-Command -Session $s -ScriptBlock { Get-Culture }

De New-PSSession cmdlet maakt een sessie op de externe Server02-computer en slaat deze op in de $s variabele. Normaal gesproken maakt u alleen een sessie wanneer u een reeks opdrachten uitvoert op de externe computer.

De Invoke-Command cmdlet voert de Get-Culture opdracht uit op Server02. De sessieparameter geeft de sessie op die is opgeslagen in de $s variabele.

Als reactie voert PowerShell de opdracht uit in de sessie op de Server02-computer.

Voorbeeld 4: Een sessie gebruiken om een reeks opdrachten uit te voeren waarmee gegevens worden gedeeld

In dit voorbeeld worden de effecten van het gebruik van computernaam en sessieparameters van Invoke-Command. Het laat zien hoe u een sessie gebruikt om een reeks opdrachten uit te voeren die dezelfde gegevens delen.

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

De eerste twee opdrachten gebruiken de parameter ComputerName om Invoke-Command opdrachten uit te voeren op de externe Server02-computer. De eerste opdracht gebruikt de Get-Process cmdlet om het PowerShell-proces op de externe computer op te halen en op te slaan in de $p variabele. Met de tweede opdracht wordt de waarde opgehaald van de eigenschap VirtualMemorySize van het PowerShell-proces.

Wanneer u de parameter ComputerName gebruikt, maakt PowerShell een nieuwe sessie om de opdracht uit te voeren. De sessie wordt gesloten wanneer de opdracht is voltooid. De $p variabele is in één verbinding gemaakt, maar deze bestaat niet in de verbinding die voor de tweede opdracht is gemaakt.

Het probleem wordt opgelost door een permanente sessie op de externe computer te maken en vervolgens beide opdrachten in dezelfde sessie uit te voeren.

De New-PSSession cmdlet maakt een permanente sessie op de computer Server02 en slaat de sessie op in de $s variabele. De Invoke-Command volgende regels gebruiken de sessieparameter om beide opdrachten in dezelfde sessie uit te voeren. Omdat beide opdrachten in dezelfde sessie worden uitgevoerd, blijft de $p waarde actief.

Voorbeeld 5: Een opdracht aanroepen met een scriptblok dat is opgeslagen in een variabele

In dit voorbeeld ziet u hoe u een opdracht uitvoert die is opgeslagen als een scriptblok in een variabele. Wanneer het scriptblok wordt opgeslagen in een variabele, kunt u de variabele opgeven als de waarde van de parameter ScriptBlock .

$command = {
    Get-WinEvent -LogName PowerShellCore/Operational |
      Where-Object -FilterScript { $_.Message -like '*certificate*' }
}
Invoke-Command -ComputerName S1, S2 -ScriptBlock $command

De $command variabele slaat de Get-WinEvent opdracht op die is opgemaakt als een scriptblok. De Invoke-Command opdracht wordt uitgevoerd die is opgeslagen $command op de externe S1- en S2-computers.

Voorbeeld 6: Voer één opdracht uit op verschillende computers

In dit voorbeeld ziet u hoe Invoke-Command u één opdracht uitvoert op meerdere computers.

$parameters = @{
  ComputerName      = 'Server01', 'Server02', 'TST-0143', 'localhost'
  ConfigurationName = 'MySession.PowerShell'
  ScriptBlock       = { Get-WinEvent -LogName PowerShellCore/Operational }
}
Invoke-Command @parameters

De parameter ComputerName geeft een door komma's gescheiden lijst met computernamen op. De lijst met computers bevat de localhost-waarde, die de lokale computer vertegenwoordigt. De parameter ConfigurationName geeft een alternatieve sessieconfiguratie op. De parameter ScriptBlock wordt uitgevoerd Get-WinEvent om de PowerShellCore-/operationele gebeurtenislogboeken van elke computer op te halen.

Voorbeeld 7: de versie van het hostprogramma op meerdere computers ophalen

In dit voorbeeld wordt de versie van het PowerShell-hostprogramma op 200 externe computers uitgevoerd.

$version = Invoke-Command -ComputerName (Get-Content Machines.txt) -ScriptBlock {
    (Get-Host).Version
}

Omdat er slechts één opdracht wordt uitgevoerd, hoeft u geen permanente verbindingen met elk van de computers te maken. In plaats daarvan gebruikt de opdracht de parameter ComputerName om de computers aan te geven. Als u de computers wilt opgeven, wordt de Get-Content cmdlet gebruikt om de inhoud van het Machine.txt-bestand, een bestand met computernamen op te halen.

De Invoke-Command cmdlet voert een Get-Host opdracht uit op de externe computers. Er wordt gebruikgemaakt van punt notatie om de eigenschap Versie van de PowerShell-host op te halen.

Deze opdrachten worden één voor één uitgevoerd. Wanneer de opdrachten zijn voltooid, wordt de uitvoer van de opdrachten van alle computers opgeslagen in de $version variabele. De uitvoer bevat de naam van de computer waaruit de gegevens afkomstig zijn.

Voorbeeld 8: Een achtergrondtaak uitvoeren op verschillende externe computers

In dit voorbeeld wordt een opdracht uitgevoerd op twee externe computers. De Invoke-Command opdracht gebruikt de parameter AsJob , zodat de opdracht wordt uitgevoerd als achtergrondtaak. De opdrachten worden uitgevoerd op de externe computers, maar de taak bestaat op de lokale computer. De resultaten worden verzonden naar de lokale computer.

$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

De New-PSSession cmdlet maakt sessies op de externe computers server01 en Server02. De Invoke-Command cmdlet voert een achtergrondtaak uit in elk van de sessies. De opdracht gebruikt de parameter AsJob om de opdracht uit te voeren als achtergrondtaak. Met deze opdracht wordt een taakobject geretourneerd dat twee onderliggende taakobjecten bevat, één voor elk van de taken die worden uitgevoerd op de twee externe computers.

Met Get-Job de opdracht wordt het taakobject opgeslagen in de $j variabele. De $j variabele wordt vervolgens doorgesluisd naar de Format-List cmdlet om alle eigenschappen van het taakobject in een lijst weer te geven. Met de laatste opdracht worden de resultaten van de taken opgehaald. Het pijpt het taakobject in $j de Receive-Job cmdlet en slaat de resultaten op in de $results variabele.

Voorbeeld 9: Lokale variabelen opnemen in een opdracht die wordt uitgevoerd op een externe computer

In dit voorbeeld ziet u hoe u de waarden van lokale variabelen opneemt in een opdracht die wordt uitgevoerd op een externe computer. De opdracht gebruikt de Using bereikaanpassing om een lokale variabele in een externe opdracht te identificeren. Standaard wordt ervan uitgegaan dat alle variabelen worden gedefinieerd in de externe sessie. De Using bereikaanpassing is geïntroduceerd in PowerShell 3.0. Zie about_Remote_Variables en about_Scopes voor meer informatie over de Using bereikaanpassing.

$Log = 'PowerShellCore/Operational'
Invoke-Command -ComputerName Server01 -ScriptBlock {
    Get-WinEvent -LogName $Using:Log -MaxEvents 10
}

De $Log variabele slaat de naam op van het gebeurtenislogboek, PowerShellCore/Operational. De Invoke-Command cmdlet wordt uitgevoerd Get-WinEvent op Server01 om de tien nieuwste gebeurtenissen op te halen uit het gebeurtenislogboek. De waarde van de Parameter LogName is de $Log variabele die wordt voorafgegaan door de Using bereikaanpassing om aan te geven dat deze is gemaakt in de lokale sessie, niet in de externe sessie.

Voorbeeld 10: De computernaam verbergen

In dit voorbeeld ziet u het effect van het gebruik van de parameter HideComputerName van Invoke-Command. HideComputerName wijzigt het object dat door deze cmdlet wordt geretourneerd niet. Alleen de weergave wordt gewijzigd. U kunt nog steeds de format-cmdlets gebruiken om de eigenschap PsComputerName van een van de betrokken objecten weer te geven.

Invoke-Command -ComputerName S1, S2 -ScriptBlock { Get-Process PowerShell }

PSComputerName    Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id   ProcessName
--------------    -------  ------    -----      ----- -----   ------     --   -----------
S1                575      15        45100      40988   200     4.68     1392 PowerShell
S2                777      14        35100      30988   150     3.68     67   PowerShell

Invoke-Command -ComputerName S1, S2 -HideComputerName -ScriptBlock {
    Get-Process PowerShell
}

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id   ProcessName
-------  ------    -----      ----- -----   ------     --   -----------
575      15        45100      40988   200     4.68     1392 PowerShell
777      14        35100      30988   150     3.68     67   PowerShell

De eerste twee opdrachten gebruiken Invoke-Command om een Get-Process opdracht uit te voeren voor het PowerShell-proces. De uitvoer van de eerste opdracht bevat de eigenschap PsComputerName , die de naam bevat van de computer waarop de opdracht is uitgevoerd. De uitvoer van de tweede opdracht, die HideComputerName gebruikt, bevat niet de kolom PsComputerName.

Voorbeeld 11: het trefwoord Param gebruiken in een scriptblok

Het Param trefwoord en de parameter ArgumentList worden gebruikt om variabele waarden door te geven aan benoemde parameters in een scriptblok. In dit voorbeeld worden bestandsnamen weergegeven die beginnen met de letter a en de .pdf extensie hebben.

Zie about_Language_Keywords voor meer informatie over het Param trefwoord.

$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 maakt gebruik van de ScriptBlock-parameter die twee variabelen definieert, $param1 en $param2. Get-ChildItem gebruikt de benoemde parameters, Naam en Opnemen met de namen van de variabelen. De ArgumentList geeft de waarden door aan de variabelen.

Voorbeeld 12: gebruik de $args automatische variabele in een scriptblok

De $args automatische variabele en de parameter ArgumentList worden gebruikt om matrixwaarden door te geven aan parameterposities in een scriptblok. In dit voorbeeld wordt de mapinhoud van een server van .txt bestanden weergegeven. De Get-ChildItem parameter Path is positie 0 en de filterparameter is positie 1.

Zie about_Automatic_Variables voor meer informatie over de $args variabele

$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 maakt gebruik van een ScriptBlock-parameter en Get-ChildItem geeft de $args[0] en $args[1] matrixwaarden op. De ArgumentList geeft de $args matrixwaarden door aan de Get-ChildItem parameterposities voor Path en Filter.

Voorbeeld 13: Een script uitvoeren op alle computers die worden vermeld in een tekstbestand

In dit voorbeeld wordt de Invoke-Command cmdlet gebruikt om het Sample.ps1 script uit te voeren op alle computers die in het Servers.txt bestand worden vermeld. De opdracht gebruikt de Parameter FilePath om het scriptbestand op te geven. Met deze opdracht kunt u het script uitvoeren op de externe computers, zelfs als het scriptbestand niet toegankelijk is voor de externe computers.

$parameters = @{
    ComputerName = (Get-Content Servers.txt)
    FilePath     = 'C:\Scripts\Sample.ps1'
    ArgumentList = 'Process', 'Service'
}
Invoke-Command @parameters

Wanneer u de opdracht verzendt, wordt de inhoud van het Sample.ps1 bestand gekopieerd naar een scriptblok en wordt het scriptblok uitgevoerd op elk van de externe computers. Deze procedure is gelijk aan het gebruik van de parameter ScriptBlock om de inhoud van het script in te dienen.

Voorbeeld 14: Een opdracht uitvoeren op een externe computer met behulp van een URI

In dit voorbeeld ziet u hoe u een opdracht uitvoert op een externe computer die wordt geïdentificeerd door een URI (Uniform Resource Identifier). In dit specifieke voorbeeld wordt een Set-Mailbox opdracht uitgevoerd op een externe 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

De eerste regel gebruikt de Get-Credential cmdlet om Windows Live ID-referenties op te slaan in de $LiveCred variabele. PowerShell vraagt de gebruiker om Windows Live ID-referenties in te voeren.

De $parameters variabele is een hash-tabel met de parameters die moeten worden doorgegeven aan de Invoke-Command cmdlet. De Invoke-Command cmdlet voert een Set-Mailbox opdracht uit met behulp van de microsoft.Exchange-sessieconfiguratie . De parameter ConnectionURI geeft de URL van het Exchange-servereindpunt op. De referentieparameter geeft de referenties op die zijn opgeslagen in de $LiveCred variabele. De parameter AuthenticationMechanism specificeert het gebruik van basisverificatie. De parameter ScriptBlock geeft een scriptblok op dat de opdracht bevat.

Voorbeeld 15: Een sessieoptie gebruiken

In dit voorbeeld ziet u hoe u een SessionOption-parameter maakt en gebruikt.

$so = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
$parameters = @{
    ComputerName  = 'server01'
    UseSSL        = $true
    ScriptBlock   = { Get-HotFix }
    SessionOption = $so
    Credential    = 'server01\user01'
}
Invoke-Command @parameters

De New-PSSessionOption cmdlet maakt een sessieoptieobject dat ervoor zorgt dat het externe einde de certificeringsinstantie, canonieke naam en intrekkingslijsten niet controleert tijdens het evalueren van de binnenkomende HTTPS-verbinding. Het SessionOption-object wordt opgeslagen in de $so variabele.

Notitie

Het uitschakelen van deze controles is handig voor probleemoplossing, maar is uiteraard niet veilig.

Met de Invoke-Command cmdlet wordt een Get-HotFix opdracht op afstand uitgevoerd. De parameter SessionOption krijgt de $so variabele.

Voorbeeld 16: URI-omleiding beheren in een externe opdracht

In dit voorbeeld ziet u hoe u de parameters AllowRedirection en SessionOption gebruikt voor het beheren van URI-omleiding in een externe opdracht.

$max = New-PSSessionOption -MaximumRedirection 1
$parameters = @{
  ConnectionUri    = 'https://ps.exchangelabs.com/PowerShell'
  ScriptBlock      = { Get-Mailbox dan }
  AllowRedirection = $true
  SessionOption    = $max
}
Invoke-Command @parameters

De New-PSSessionOption cmdlet maakt een PSSessionOption-object dat is opgeslagen in de $max variabele. De opdracht gebruikt de parameter MaximumRedirection om de eigenschap MaximumConnectionRedirectionCount van het PSSessionOption-object in te stellen op 1.

De Invoke-Command cmdlet voert een Get-Mailbox opdracht uit op een externe Microsoft Exchange Server. De parameter AllowRedirection biedt expliciete machtigingen om de verbinding om te leiden naar een alternatief eindpunt. De parameter SessionOption maakt gebruik van het sessieobject dat is opgeslagen in de $max variabele.

Als de externe computer die is opgegeven door ConnectionURI een omleidingsbericht retourneert, wordt de verbinding door PowerShell omgeleid, maar als de nieuwe bestemming een ander omleidingsbericht retourneert, wordt de waarde voor het aantal omleidingen van 1 overschreden en Invoke-Command wordt een niet-afsluitfout geretourneerd.

Voorbeeld 17: Toegang krijgen tot een netwerkshare in een externe sessie

In dit voorbeeld ziet u hoe u toegang hebt tot een netwerkshare vanuit een externe sessie. Er worden drie computers gebruikt om het voorbeeld te demonstreren. Server01 is de lokale computer, Server02 is de externe computer en Net03 bevat de netwerkshare. Server01 maakt verbinding met Server02 en vervolgens voert Server02 een tweede hop naar Net03 uit om toegang te krijgen tot de netwerkshare. Zie Voor meer informatie over hoe Externe communicatie van PowerShell hops tussen computers ondersteunt, de tweede hop maken in Externe communicatie in PowerShell.

De vereiste Delegatie van referentiebeveiligingsondersteuningsprovider (CredSSP) is ingeschakeld in de clientinstellingen op de lokale computer en in de service-instellingen op de externe computer. Als u de opdrachten in dit voorbeeld wilt uitvoeren, moet u lid zijn van de groep Administrators op de lokale computer en de externe computer.

Enable-WSManCredSSP -Role Client -DelegateComputer Server02
$s = New-PSSession Server02
Invoke-Command -Session $s -ScriptBlock { Enable-WSManCredSSP -Role Server -Force }
$parameters = @{
  ComputerName   = 'Server02'
  ScriptBlock    = { Get-Item \\Net03\Scripts\LogFiles.ps1 }
  Authentication = 'CredSSP'
  Credential     = 'Domain01\Admin01'
}
Invoke-Command @parameters

Met Enable-WSManCredSSP de cmdlet wordt CredSSP-delegering vanaf de lokale Server01-computer naar de externe Server02-computer ingeschakeld. De parameter Role specificeert de client voor het configureren van de CredSSP-clientinstelling op de lokale computer.

New-PSSession maakt een PSSession-object voor Server02 en slaat het object op in de $s variabele.

De Invoke-Command cmdlet gebruikt de $s variabele om verbinding te maken met de externe computer, Server02. De parameter ScriptBlock wordt uitgevoerd Enable-WSManCredSSP op de externe computer. Met de parameter Functie geeft u Server op voor het configureren van de CredSSP-serverinstelling op de externe computer.

De $parameters variabele bevat de parameterwaarden om verbinding te maken met de netwerkshare. De Invoke-Command cmdlet voert een Get-Item opdracht uit in de sessie in $s. Met deze opdracht wordt een script opgehaald uit de \\Net03\Scripts netwerkshare. De opdracht gebruikt de verificatieparameter met een waarde van CredSSP en de referentieparameter met de waarde Domain01\Admin01.

Voorbeeld 18: Scripts starten op veel externe computers

In dit voorbeeld wordt een script uitgevoerd op meer dan honderd computers. Als u de impact op de lokale computer wilt minimaliseren, maakt deze verbinding met elke computer, start u het script en verbreekt u vervolgens de verbinding met elke computer. Het script wordt nog steeds uitgevoerd in de niet-verbonden sessies.

$parameters = @{
  ComputerName          = (Get-Content -Path C:\Test\Servers.txt)
  InDisconnectedSession = $true
  FilePath              = '\\Scripts\Public\ConfigInventory.ps1'
  SessionOption         = @{
      OutputBufferingMode = 'Drop'
      IdleTimeout         = [timespan]::FromHours(12)
  }
}
Invoke-Command @parameters

De opdracht gebruikt Invoke-Command om het script uit te voeren. De waarde van de parameter ComputerName is een Get-Content opdracht waarmee de namen van de externe computers uit een tekstbestand worden opgehaald. Met de parameter InDisconnectedSession worden de sessies verbroken zodra de opdracht wordt gestart. De waarde van de FilePath-parameter is het script dat Invoke-Command op elke computer wordt uitgevoerd.

De waarde van SessionOption is een hash-tabel. De waarde OutputBufferingMode is ingesteld op Drop en de waarde IdleTimeout is ingesteld op 12 uur.

Gebruik de Receive-PSSession cmdlet om de resultaten op te halen van opdrachten en scripts die worden uitgevoerd in niet-verbonden sessies.

Voorbeeld 19: Een opdracht uitvoeren op een externe computer met behulp van SSH

In dit voorbeeld ziet u hoe u een opdracht uitvoert op een externe computer met behulp van Secure Shell (SSH). Als SSH is geconfigureerd op de externe computer om te vragen om wachtwoorden, krijgt u een wachtwoordprompt. Anders moet u gebruikersverificatie op basis van SSH-sleutels gebruiken.

Invoke-Command -HostName UserA@LinuxServer01 -ScriptBlock { Get-MailBox * }

Voorbeeld 20: Een opdracht uitvoeren op een externe computer met behulp van SSH en een gebruikersverificatiesleutel opgeven

In dit voorbeeld ziet u hoe u een opdracht uitvoert op een externe computer met behulp van SSH en een sleutelbestand opgeeft voor gebruikersverificatie. U wordt niet om een wachtwoord gevraagd, tenzij de sleutelverificatie mislukt en de externe computer is geconfigureerd om basiswachtwoordverificatie toe te staan.

$parameters = @{
    HostName    = 'UserA@LinuxServer01'
    ScriptBlock = { Get-MailBox * }
    KeyFilePath = '/UserA/UserAKey_rsa'
}
Invoke-Command

Voorbeeld 21: Een scriptbestand uitvoeren op meerdere externe computers met behulp van SSH als taak

In dit voorbeeld ziet u hoe u een scriptbestand uitvoert op meerdere externe computers met behulp van SSH en de parameterset SSHConnection . De parameter SSHConnection gebruikt een matrix van hash-tabellen die verbindingsgegevens voor elke computer bevatten. In dit voorbeeld is vereist dat de externe doelcomputers SSH hebben geconfigureerd ter ondersteuning van op sleutels gebaseerde gebruikersverificatie.

$sshConnections = @(
    @{
        HostName    = "WinServer1"
        UserName    = "Domain\UserA"
        KeyFilePath = "C:\Users\UserA\id_rsa"
    }
    @{
        HostName    = "UserB@LinuxServer5"
        KeyFilePath = "/Users/UserB/id_rsa"
    }
)
$results = Invoke-Command -FilePath c:\Scripts\GetInfo.ps1 -SSHConnection $sshConnections

Voorbeeld 22: Verbinding maken met een externe SSH-sessie met behulp van SSH-opties

In dit voorbeeld ziet u hoe u een scriptbestand uitvoert op een externe Linux-computer met behulp van SSH-opties. De parameter Opties gebruikt een hashtabel met waarden die als opties worden doorgegeven aan de onderliggende ssh opdracht waarmee de verbinding met het externe systeem tot stand is gebracht.

$options = @{
    Port=22
    User = 'UserB'
    Host = 'LinuxServer5'
}
$results = Invoke-Command -FilePath c:\Scripts\CollectEvents.ps1 -KeyFilePath '/Users/UserB/id_rsa' -Options $options

Parameters

-AllowRedirection

Hiermee wordt omleiding van deze verbinding naar een alternatieve URI (Uniform Resource Identifier) toegestaan.

Wanneer u de parameter ConnectionURI gebruikt, kan de externe bestemming een instructie retourneren om om te leiden naar een andere URI. PowerShell leidt standaard geen verbindingen om, maar u kunt deze parameter gebruiken om de verbinding om te leiden.

U kunt ook het aantal keren beperken dat de verbinding wordt omgeleid door de waarde van de sessieoptie MaximumConnectionRedirectionCount te wijzigen. Gebruik de parameter MaximumRedirection van de New-PSSessionOption cmdlet of stel de eigenschap MaximumConnectionRedirectionCount van de $PSSessionOption voorkeursvariabele in. De standaardwaarde is 5.

Type:SwitchParameter
Position:Named
Default value:False
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-ApplicationName

Hiermee geeft u het naamsegment van de toepassing van de verbindings-URI. Gebruik deze parameter om de naam van de toepassing op te geven wanneer u de connectionURI-parameter niet gebruikt in de opdracht.

De standaardwaarde is de waarde van de $PSSessionApplicationName voorkeursvariabele op de lokale computer. Als deze voorkeursvariabele niet is gedefinieerd, is de standaardwaarde WSMAN. Deze waarde is geschikt voor de meeste toepassingen. Zie about_Preference_Variables voor meer informatie.

De WinRM-service gebruikt de naam van de toepassing om een listener te selecteren voor de service van de verbindingsaanvraag. De waarde van deze parameter moet overeenkomen met de waarde van de eigenschap URLPrefix van een listener op de externe computer.

Type:String
Position:Named
Default value:$PSSessionApplicationName if set on the local computer, otherwise WSMAN
Vereist:False
Pijplijninvoer accepteren:True
Jokertekens accepteren:False

-ArgumentList

Levert de waarden van parameters voor de scriptblock. De parameters in het scriptblok worden doorgegeven door de positie van de matrixwaarde die is opgegeven in ArgumentList. Dit staat bekend als matrixsplatting. Zie about_Splatting voor meer informatie over het gedrag van ArgumentList.

Type:Object[]
Aliassen:Args
Position:Named
Default value:None
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-AsJob

Geeft aan dat met deze cmdlet de opdracht wordt uitgevoerd als achtergrondtaak op een externe computer. Gebruik deze parameter om opdrachten uit te voeren die veel tijd in beslag nemen om te voltooien.

Wanneer u de parameter AsJob gebruikt, retourneert de opdracht een object dat de taak vertegenwoordigt en wordt vervolgens de opdrachtprompt weergegeven. U kunt in de sessie blijven werken terwijl de taak is voltooid. Gebruik de *-Job cmdlets om de taak te beheren. Gebruik de Receive-Job cmdlet om de taakresultaten op te halen.

De parameter AsJob lijkt op het gebruik van de Invoke-Command cmdlet om een Start-Job cmdlet op afstand uit te voeren. Met AsJob wordt de taak echter gemaakt op de lokale computer, ook al wordt de taak uitgevoerd op een externe computer. De resultaten van de externe taak worden automatisch geretourneerd naar de lokale computer.

Zie about_Jobs en about_Remote_Jobs voor meer informatie over PowerShell-achtergrondtaken.

Type:SwitchParameter
Position:Named
Default value:False
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-Authentication

Hiermee geeft u het mechanisme op dat wordt gebruikt om de referenties van de gebruiker te verifiëren. CredSSP-verificatie is alleen beschikbaar in Windows Vista, Windows Server 2008 en latere versies van het Windows-besturingssysteem.

De acceptabele waarden voor deze parameter zijn als volgt:

  • Standaardinstelling
  • Basis
  • Credssp
  • Verteren
  • Kerberos
  • Onderhandelen
  • NegotiateWithImplicitCredential

De standaardwaarde is Standaard.

Zie AuthenticationMechanism Enumeration voor meer informatie over de waarden van deze parameter.

Let op

CredSSP-verificatie (Credential Security Support Provider), waarbij de referenties van de gebruiker worden doorgegeven aan een externe computer die moet worden geverifieerd, is ontworpen voor opdrachten waarvoor verificatie is vereist voor meer dan één resource, zoals toegang tot een externe netwerkshare. Dit mechanisme verhoogt het beveiligingsrisico van de externe bewerking. Als de externe computer is aangetast, kunnen de referenties die aan de computer worden doorgegeven, worden gebruikt om de netwerksessie te beheren. Zie Referentiebeveiligingsondersteuningsprovider voor meer informatie.

Type:AuthenticationMechanism
Geaccepteerde waarden:Basic, Default, Credssp, Digest, Kerberos, Negotiate, NegotiateWithImplicitCredential
Position:Named
Default value:Default
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-CertificateThumbprint

Hiermee geeft u het certificaat van de digitale openbare sleutel (X509) van een gebruikersaccount dat gemachtigd is om verbinding te maken met de niet-verbonden sessie. Voer de vingerafdruk van het certificaat in.

Certificaten worden gebruikt in verificatie op basis van clientcertificaten. Ze kunnen alleen worden toegewezen aan lokale gebruikersaccounts en ze werken niet met domeinaccounts.

Als u een vingerafdruk van een certificaat wilt ophalen, gebruikt u een Get-Item of Get-ChildItem opdracht in het PowerShell-certificaat: station.

Type:String
Position:Named
Default value:None
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-ComputerName

Hiermee geeft u de computers waarop de opdracht wordt uitgevoerd. Standaard is dit de lokale computer.

Wanneer u de parameter ComputerName gebruikt, maakt PowerShell een tijdelijke verbinding die alleen wordt gebruikt om de opgegeven opdracht uit te voeren en vervolgens wordt gesloten. Als u een permanente verbinding nodig hebt, gebruikt u de sessieparameter .

Typ de NETBIOS-naam, het IP-adres of de volledig gekwalificeerde domeinnaam van een of meer computers in een door komma's gescheiden lijst. Als u de lokale computer wilt opgeven, typt u de computernaam, localhost of een punt (.).

Als u een IP-adres in de waarde van ComputerName wilt gebruiken, moet de opdracht de referentieparameter bevatten. De computer moet worden geconfigureerd voor het HTTPS-transport of het IP-adres van de externe computer moet worden opgenomen in de WinRM TrustedHosts-lijst van de lokale computer. Zie How to Add a Computer to the Trusted Host List (Een computer toevoegen aan de lijst met vertrouwde hosts) voor instructies voor het toevoegen van een computernaam aan de lijst met vertrouwde hosts.

Op Windows Vista en latere versies van het Windows-besturingssysteem, om de lokale computer op te nemen in de waarde van ComputerName, moet u PowerShell uitvoeren met de optie Als administrator uitvoeren.

Type:String[]
Aliassen:Cn
Position:0
Default value:Local computer
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-ConfigurationName

Hiermee geeft u de sessieconfiguratie op die wordt gebruikt voor de nieuwe PSSession.

Voer een configuratienaam of de volledig gekwalificeerde resource-URI in voor een sessieconfiguratie. Als u alleen de configuratienaam opgeeft, wordt de volgende schema-URI voorafgegaan: http://schemas.microsoft.com/PowerShell

Wanneer deze parameter wordt gebruikt met SSH, geeft deze parameter het subsysteem op dat moet worden gebruikt voor het doel zoals gedefinieerd in sshd_config. De standaardwaarde voor SSH is het powershell subsysteem.

De sessieconfiguratie voor een sessie bevindt zich op de externe computer. Als de opgegeven sessieconfiguratie niet bestaat op de externe computer, mislukt de opdracht.

De standaardwaarde is de waarde van de $PSSessionConfigurationName voorkeursvariabele op de lokale computer. Als deze voorkeursvariabele niet is ingesteld, is microsoft.PowerShell de standaardinstelling. Zie about_Preference_Variables voor meer informatie.

Type:String
Position:Named
Default value:$PSSessionConfigurationName if set on the local computer, otherwise Microsoft.PowerShell
Vereist:False
Pijplijninvoer accepteren:True
Jokertekens accepteren:False

-ConnectingTimeout

Hiermee geeft u de hoeveelheid tijd in milliseconden op die is toegestaan voor de eerste SSH-verbinding. Als de verbinding niet binnen de opgegeven tijd is voltooid, wordt er een fout geretourneerd.

Deze parameter is geïntroduceerd in PowerShell 7.2

Type:Int32
Position:Named
Default value:Unlimited
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-ConnectionUri

Hiermee geeft u een URI (Uniform Resource Identifier) op die het verbindingseindpunt van de sessie definieert. De URI moet volledig gekwalificeerd zijn.

De notatie van deze tekenreeks is als volgt:

<Transport>://<ComputerName>:<Port>/<ApplicationName>

De standaardwaarde is als volgt:

http://localhost:5985/WSMAN

Als u geen verbindings-URI opgeeft, kunt u de parameters UseSSL en Poort gebruiken om de verbindings-URI-waarden op te geven.

Geldige waarden voor het transportsegment van de URI zijn HTTP en HTTPS. Als u een verbindings-URI met een transportsegment opgeeft, maar geen poort opgeeft, wordt de sessie gemaakt met de standaardenpoorten: 80 voor HTTP en 443 voor HTTPS. Als u de standaardpoorten voor externe communicatie met PowerShell wilt gebruiken, geeft u poort 5985 op voor HTTP of 5986 voor HTTPS.

Als de doelcomputer de verbinding omleidt naar een andere URI, voorkomt PowerShell de omleiding, tenzij u de parameter AllowRedirection in de opdracht gebruikt.

Type:Uri[]
Aliassen:URI, CU
Position:0
Default value:http://localhost:5985/WSMAN
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-ContainerId

Hiermee geeft u een matrix van container-id's.

Type:String[]
Position:Named
Default value:None
Vereist:True
Pijplijninvoer accepteren:True
Jokertekens accepteren:False

-Credential

Hiermee geeft u een gebruikersaccount op dat gemachtigd is om deze actie uit te voeren. Standaard is dit de huidige gebruiker.

Typ een gebruikersnaam, zoals User01 of Domain01\User01, of voer een PSCredential-object in dat is gegenereerd door de Get-Credential cmdlet. Als u een gebruikersnaam typt, wordt u gevraagd het wachtwoord in te voeren.

Referenties worden opgeslagen in een PSCredential-object en het wachtwoord wordt opgeslagen als SecureString.

Notitie

Zie Hoe veilig is SecureString SecureString?voor meer informatie over SecureString-gegevensbeveiliging.

Type:PSCredential
Position:Named
Default value:Current user
Vereist:False
Pijplijninvoer accepteren:True
Jokertekens accepteren:False

-EnableNetworkAccess

Geeft aan dat deze cmdlet een interactief beveiligingstoken toevoegt aan loopbacksessies. Met het interactieve token kunt u opdrachten uitvoeren in de loopbacksessie waarmee gegevens van andere computers worden opgehaald. U kunt bijvoorbeeld een opdracht uitvoeren in de sessie waarmee XML-bestanden van een externe computer naar de lokale computer worden gekopieerd.

Een loopbacksessie is een PSSession die afkomstig is en eindigt op dezelfde computer. Als u een loopbacksessie wilt maken, laat u de parameter ComputerName weg of stelt u de waarde ervan in op dot (.), localhost of de naam van de lokale computer.

Standaard worden loopbacksessies gemaakt met behulp van een netwerktoken, wat mogelijk niet voldoende machtigingen biedt voor verificatie bij externe computers.

De parameter EnableNetworkAccess is alleen van kracht in loopbacksessies. Als u EnableNetworkAccess gebruikt wanneer u een sessie op een externe computer maakt, slaagt de opdracht, maar wordt de parameter genegeerd.

U kunt externe toegang in een loopbacksessie toestaan met behulp van de CredSSP-waarde van de verificatieparameter , waarmee de sessiereferenties worden gedelegeerd aan andere computers.

Als u de computer wilt beschermen tegen schadelijke toegang, kunnen verbroken loopbacksessies met interactieve tokens, die zijn gemaakt met EnableNetworkAccess, alleen opnieuw worden verbonden vanaf de computer waarop de sessie is gemaakt. Verbroken sessies waarvoor CredSSP-verificatie wordt gebruikt, kunnen opnieuw worden verbonden vanaf andere computers. Zie Disconnect-PSSession voor meer informatie.

Deze parameter is geïntroduceerd in PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:False
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-FilePath

Hiermee geeft u een lokaal script op dat door deze cmdlet wordt uitgevoerd op een of meer externe computers. Voer het pad en de bestandsnaam van het script in of geef een scriptpad door naar Invoke-Command. Het script moet bestaan op de lokale computer of in een map waartoe de lokale computer toegang heeft. Gebruik ArgumentList om de waarden van parameters in het script op te geven.

Wanneer u deze parameter gebruikt, converteert PowerShell de inhoud van het opgegeven scriptbestand naar een scriptblok, verzendt het scriptblok naar de externe computer en voert deze uit op de externe computer.

Type:String
Aliassen:PSPath
Position:1
Default value:None
Vereist:True
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-HideComputerName

Geeft aan dat deze cmdlet de computernaam van elk object weglaat uit de uitvoerweergave. Standaard wordt de naam van de computer die het object heeft gegenereerd, weergegeven in de weergave.

Deze parameter is alleen van invloed op de uitvoerweergave. Het object wordt niet gewijzigd.

Type:SwitchParameter
Aliassen:HCN
Position:Named
Default value:False
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-HostName

Hiermee geeft u een matrix van computernamen voor een SSH-verbinding (Secure Shell). Dit is vergelijkbaar met de parameter ComputerName , behalve dat de verbinding met de externe computer wordt gemaakt met behulp van SSH in plaats van Windows WinRM.

Deze parameter is geïntroduceerd in PowerShell 6.0.

Type:String[]
Position:Named
Default value:None
Vereist:True
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-InDisconnectedSession

Geeft aan dat met deze cmdlet een opdracht of script wordt uitgevoerd in een niet-verbonden sessie.

Wanneer u de parameter InDisconnectedSession gebruikt, Invoke-Command maakt u een permanente sessie op elke externe computer, start u de opdracht die is opgegeven door de parameter ScriptBlock of FilePath en verbreekt u de verbinding met de sessie. De opdrachten blijven worden uitgevoerd in de niet-verbonden sessies. Met InDisconnectedSession kunt u opdrachten uitvoeren zonder een verbinding met de externe sessies te onderhouden. En omdat de verbinding met de sessie wordt verbroken voordat resultaten worden geretourneerd, zorgt InDisconnectedSession ervoor dat alle opdrachtresultaten worden geretourneerd naar de opnieuw verbonden sessie, in plaats van te worden gesplitst tussen sessies.

U kunt InDisconnectedSession niet gebruiken met de sessieparameter of de astaakparameter.

Opdrachten die Gebruikmaken van InDisconnectedSession retourneren een PSSession-object dat de niet-verbonden sessie vertegenwoordigt. Ze retourneren de uitvoer van de opdracht niet. Gebruik de Connect-PSSession of Receive-PSSession cmdlets om verbinding te maken met de niet-verbonden sessie. Gebruik de Receive-PSSession cmdlet om de resultaten op te halen van opdrachten die in de sessie zijn uitgevoerd. Als u opdrachten wilt uitvoeren die uitvoer genereren in een niet-verbonden sessie, stelt u de waarde van de sessieoptie OutputBufferingMode in op Neerzetten. Als u verbinding wilt maken met de niet-verbonden sessie, stelt u de time-out voor inactiviteit in de sessie in, zodat u voldoende tijd hebt om verbinding te maken voordat u de sessie verwijdert.

U kunt de uitvoerbuffermodus en inactiviteittime-out instellen in de parameter SessionOption of in de $PSSessionOption voorkeursvariabele. Zie en about_Preference_Variables voor meer informatie over sessieoptiesNew-PSSessionOption.

Zie about_Remote_Disconnected_Sessions voor meer informatie over de functie Niet-verbonden sessies.

Deze parameter is geïntroduceerd in PowerShell 3.0.

Type:SwitchParameter
Aliassen:Disconnected
Position:Named
Default value:False
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-InputObject

Hiermee geeft u invoer voor de opdracht. Voer een variabele in die de objecten bevat of typ een opdracht of expressie waarmee de objecten worden opgehaald.

Wanneer u de parameter InputObject gebruikt, gebruikt u de $Input automatische variabele in de waarde van de parameter ScriptBlock om de invoerobjecten weer te geven.

Type:PSObject
Position:Named
Default value:None
Vereist:False
Pijplijninvoer accepteren:True
Jokertekens accepteren:False

-JobName

Hiermee geeft u een beschrijvende naam voor de achtergrondtaak. Taken worden standaard benoemd Job<n>, waarbij <n> een rangnummer is.

Als u de parameter JobName in een opdracht gebruikt, wordt de opdracht uitgevoerd als een taak en Invoke-Command wordt een taakobject geretourneerd, zelfs als u AsJob niet in de opdracht opneemt.

Zie about_Jobs voor meer informatie over PowerShell-achtergrondtaken.

Type:String
Position:Named
Default value:Job<n>
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-KeyFilePath

Hiermee geeft u een sleutelbestandspad op dat wordt gebruikt door Secure Shell (SSH) om een gebruiker op een externe computer te verifiëren.

Met SSH kan gebruikersverificatie worden uitgevoerd via persoonlijke en openbare sleutels als alternatief voor basiswachtwoordverificatie. Als de externe computer is geconfigureerd voor sleutelverificatie, kan deze parameter worden gebruikt om de sleutel op te geven die de gebruiker identificeert.

Deze parameter is geïntroduceerd in PowerShell 6.0.

Type:String
Aliassen:IdentityFilePath
Position:Named
Default value:None
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-NoNewScope

Geeft aan dat met deze cmdlet de opgegeven opdracht in het huidige bereik wordt uitgevoerd. Invoke-Command Standaard worden opdrachten in hun eigen bereik uitgevoerd.

Deze parameter is alleen geldig in opdrachten die worden uitgevoerd in de huidige sessie, dus opdrachten die zowel de computernaam als de sessieparameters weglaten.

Deze parameter is geïntroduceerd in PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:False
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-Options

Hiermee geeft u een hashtabel op van SSH-opties die worden gebruikt bij het maken van verbinding met een externe SSH-sessie. De mogelijke opties zijn waarden die worden ondersteund door de Unix-versie van de ssh-opdracht .

Alle waarden die expliciet door parameters worden doorgegeven, hebben voorrang op waarden die zijn doorgegeven in de hashtabel Opties . Als u bijvoorbeeld de poortparameter gebruikt, worden alle Port sleutel-waardeparen overschreven die zijn doorgegeven in de hashtabel Opties .

Deze parameter is toegevoegd in PowerShell 7.3.

Type:Hashtable
Position:Named
Default value:None
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-Port

Hiermee geeft u de netwerkpoort op de externe computer die wordt gebruikt voor deze opdracht. Als u verbinding wilt maken met een externe computer, moet de externe computer luisteren op de poort die door de verbinding wordt gebruikt. De standaardpoorten zijn 5985 (WinRM-poort voor HTTP) en 5986 (WinRM-poort voor HTTPS).

Voordat u een alternatieve poort gebruikt, configureert u de WinRM-listener op de externe computer om naar die poort te luisteren. Als u de listener wilt configureren, typt u de volgende twee opdrachten bij de PowerShell-prompt:

Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse

New-Item -Path WSMan:\Localhost\listener -Transport http -Address * -Port \<port-number\>

Gebruik de poortparameter alleen als u dit moet doen. De poort die in de opdracht is ingesteld, is van toepassing op alle computers of sessies waarop de opdracht wordt uitgevoerd. Een alternatieve poortinstelling kan verhinderen dat de opdracht wordt uitgevoerd op alle computers.

Type:Int32
Position:Named
Default value:None
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-RemoteDebug

Wordt gebruikt om de aangeroepen opdracht uit te voeren in de foutopsporingsmodus in de externe PowerShell-sessie.

Type:SwitchParameter
Position:Named
Default value:False
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-RunAsAdministrator

Geeft aan dat deze cmdlet een opdracht aanroept als beheerder.

Type:SwitchParameter
Position:Named
Default value:False
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-ScriptBlock

Hiermee geeft u de opdrachten die moeten worden uitgevoerd. Plaats de opdrachten tussen accolades ({ }) om een scriptblok te maken. Wanneer u Invoke-Command een opdracht op afstand gebruikt, worden alle variabelen in de opdracht geëvalueerd op de externe computer.

Notitie

Parameters voor de scriptblock kunnen alleen worden doorgegeven vanuit ArgumentList op positie. Schakelparameters kunnen niet worden doorgegeven door positie. Als u een parameter nodig hebt die zich gedraagt als een SwitchParameter-type , gebruikt u in plaats daarvan een Booleaanse waarde.

Type:ScriptBlock
Aliassen:Command
Position:0
Default value:None
Vereist:True
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-Session

Hiermee geeft u een matrix van sessies waarin deze cmdlet de opdracht uitvoert. Voer een variabele in die PSSession-objecten of een opdracht bevat waarmee de PSSession-objecten, zoals een New-PSSession of opdracht, worden gemaakt of Get-PSSession opgehaald.

Wanneer u een PSSession maakt, maakt PowerShell een permanente verbinding met de externe computer. Gebruik een PSSession om een reeks gerelateerde opdrachten uit te voeren die gegevens delen. Als u één opdracht of een reeks niet-gerelateerde opdrachten wilt uitvoeren, gebruikt u de parameter ComputerName . Zie about_PSSessions voor meer informatie.

Type:PSSession[]
Position:0
Default value:None
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-SessionName

Hiermee geeft u een beschrijvende naam op voor een niet-verbonden sessie. U kunt de naam gebruiken om te verwijzen naar de sessie in volgende opdrachten, zoals een Get-PSSession opdracht. Deze parameter is alleen geldig met de parameter InDisconnectedSession .

Deze parameter is geïntroduceerd in PowerShell 3.0.

Type:String[]
Position:Named
Default value:None
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-SessionOption

Hiermee geeft u geavanceerde opties voor de sessie. Voer een SessionOption-object in, zoals een object dat u maakt met behulp van de New-PSSessionOption cmdlet of een hash-tabel waarin de sleutels sessieoptienamen zijn en de waarden sessieoptiewaarden zijn.

Notitie

Als u een hashtabel voor SessionOption opgeeft, converteert PowerShell de hashtabel naar een System.Management.Autiomation.Remoting.PSSessionOption-object . De waarden voor sleutels die in de hashtabel zijn opgegeven, worden omgezet in de overeenkomende eigenschap van het object. Dit gedraagt zich anders dan bellen New-PSSessionOption. De system.TimeSpan-waarden voor de time-outeigenschappen, zoals IdleTimeout, converteren bijvoorbeeld een geheel getal naar maatstreepjes in plaats van milliseconden. Zie PSSessionOption voor meer informatie over het PSSessionOption-object en de eigenschappen ervan

De standaardwaarden voor de opties worden bepaald door de waarde van de $PSSessionOption voorkeursvariabele, als deze is ingesteld. Anders worden de standaardwaarden ingesteld op basis van opties die zijn ingesteld in de sessieconfiguratie.

De waarden voor sessieopties hebben voorrang op standaardwaarden voor sessies die zijn ingesteld in de $PSSessionOption voorkeursvariabele en in de sessieconfiguratie. Ze hebben echter geen voorrang op maximumwaarden, quota of limieten die zijn ingesteld in de sessieconfiguratie.

Zie voor een beschrijving van de sessieopties die de standaardwaarden New-PSSessionOptionbevatten. Zie about_Preference_Variables voor meer informatie over de $PSSessionOption voorkeursvariabele. Zie about_Session_Configurations (Engelstalig) voor meer informatie over sessieconfiguraties.

Type:PSSessionOption
Position:Named
Default value:None
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-SSHConnection

Deze parameter gebruikt een matrix van hash-tabellen waarbij elke hash-tabel een of meer verbindingsparameters bevat die nodig zijn om een SSH-verbinding (Secure Shell) tot stand te brengen. De parameter SSHConnection is handig voor het maken van meerdere sessies waarbij elke sessie verschillende verbindingsgegevens vereist.

De hashtabel heeft de volgende leden:

  • Computernaam (of HostName)
  • Poort
  • UserName
  • KeyFilePath (of IdentityFilePath)

ComputerNaam (of HostName) is het enige sleutel-waardepaar dat vereist is.

Deze parameter is geïntroduceerd in PowerShell 6.0.

Type:Hashtable[]
Position:Named
Default value:None
Vereist:True
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-SSHTransport

Geeft aan dat de externe verbinding tot stand is gebracht met behulp van Secure Shell (SSH).

PowerShell maakt standaard gebruik van Windows WinRM om verbinding te maken met een externe computer. Deze schakeloptie dwingt PowerShell om de parameter HostName te gebruiken voor het tot stand brengen van een externe verbinding op basis van SSH.

Deze parameter is geïntroduceerd in PowerShell 6.0.

Type:SwitchParameter
Geaccepteerde waarden:true
Position:Named
Default value:False
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-Subsystem

Hiermee geeft u het SSH-subsysteem dat wordt gebruikt voor de nieuwe PSSession.

Hiermee geeft u het subsysteem op dat moet worden gebruikt voor het doel zoals gedefinieerd in sshd_config. Het subsysteem start een specifieke versie van PowerShell met vooraf gedefinieerde parameters. Als het opgegeven subsysteem niet bestaat op de externe computer, mislukt de opdracht.

Als deze parameter niet wordt gebruikt, is de standaardwaarde het powershell subsysteem.

Type:String
Position:Named
Default value:powershell
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-ThrottleLimit

Hiermee geeft u het maximum aantal gelijktijdige verbindingen op dat tot stand kan worden gebracht om deze opdracht uit te voeren. Als u deze parameter weglaat of een waarde van 0 invoert, wordt de standaardwaarde 32 gebruikt.

De beperkingslimiet is alleen van toepassing op de huidige opdracht, niet op de sessie of op de computer.

Type:Int32
Position:Named
Default value:32
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-UserName

Hiermee geeft u de gebruikersnaam voor het account dat wordt gebruikt om een opdracht uit te voeren op de externe computer. De verificatiemethode voor gebruikers is afhankelijk van hoe Secure Shell (SSH) is geconfigureerd op de externe computer.

Als SSH is geconfigureerd voor basiswachtwoordverificatie, wordt u gevraagd om het gebruikerswachtwoord.

Als SSH is geconfigureerd voor gebruikersverificatie op basis van sleutels, kan er een sleutelbestandspad worden opgegeven via de parameter KeyFilePath en wordt er geen wachtwoordprompt weergegeven. Als het clientgebruikerssleutelbestand zich op een bekende SSH-locatie bevindt, is de parameter KeyFilePath niet nodig voor verificatie op basis van sleutels en vindt gebruikersverificatie automatisch plaats op basis van de gebruikersnaam. Zie de SSH-documentatie van uw platform over gebruikersverificatie op basis van sleutels voor meer informatie.

Dit is geen vereiste parameter. Als de parameter UserName niet is opgegeven, wordt de huidige aangemelde gebruikersnaam gebruikt voor de verbinding.

Deze parameter is geïntroduceerd in PowerShell 6.0.

Type:String
Position:Named
Default value:None
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-UseSSL

Geeft aan dat deze cmdlet gebruikmaakt van het SSL-protocol (Secure Sockets Layer) om een verbinding met de externe computer tot stand te brengen. SSL wordt standaard niet gebruikt.

WS-Management versleutelt alle PowerShell-inhoud die via het netwerk wordt verzonden. De UseSSL-parameter is een extra beveiliging waarmee de gegevens via een HTTPS worden verzonden in plaats van HTTP.

Als u deze parameter gebruikt, maar SSL niet beschikbaar is op de poort die voor de opdracht wordt gebruikt, mislukt de opdracht.

Type:SwitchParameter
Position:Named
Default value:False
Vereist:False
Pijplijninvoer accepteren:False
Jokertekens accepteren:False

-VMId

Hiermee geeft u een matrix van id's van virtuele machines.

Type:Guid[]
Aliassen:VMGuid
Position:0
Default value:None
Vereist:True
Pijplijninvoer accepteren:True
Jokertekens accepteren:False

-VMName

Hiermee geeft u een matrix van namen van virtuele machines.

Type:String[]
Position:Named
Default value:None
Vereist:True
Pijplijninvoer accepteren:True
Jokertekens accepteren:False

Invoerwaarden

ScriptBlock

U kunt een opdracht in een scriptblok doorsluisen naar Invoke-Command. Gebruik de $Input automatische variabele om de invoerobjecten in de opdracht weer te geven.

Uitvoerwaarden

System.Management.Automation.PSRemotingJob

Als u de parameter AsJob gebruikt, retourneert deze cmdlet een taakobject.

PSSession

Als u de parameter InDisconnectedSession gebruikt, retourneert deze cmdlet een PSSession-object .

Object

Deze cmdlet retourneert standaard de uitvoer van de aangeroepen opdracht. Dit is de waarde van de parameter ScriptBlock .

Notities

PowerShell bevat de volgende aliassen voor Invoke-Command:

  • Alle platforms:
    • icm

Als u op Windows Vista en latere versies van het Windows-besturingssysteem de parameter ComputerName wilt gebruiken om Invoke-Command een opdracht uit te voeren op de lokale computer, moet u PowerShell uitvoeren met de optie Als administrator uitvoeren.

Wanneer u opdrachten uitvoert op meerdere computers, maakt PowerShell verbinding met de computers in de volgorde waarin ze worden weergegeven in de lijst. De uitvoer van de opdracht wordt echter weergegeven in de volgorde waarin deze wordt ontvangen van de externe computers, wat mogelijk anders is.

Fouten die het gevolg zijn van de opdracht die Invoke-Command wordt uitgevoerd, worden opgenomen in de opdrachtresultaten. Fouten die fouten bij het beëindigen van een lokale opdracht zouden zijn, worden behandeld als niet-afsluitfouten in een externe opdracht. Deze strategie zorgt ervoor dat afsluitfouten op één computer de opdracht niet sluiten op alle computers waarop deze wordt uitgevoerd. Deze procedure wordt zelfs gebruikt wanneer een externe opdracht wordt uitgevoerd op één computer.

Als de externe computer zich niet in een domein bevindt dat de lokale computer vertrouwt, kan de computer mogelijk de referenties van de gebruiker niet verifiëren. Als u de externe computer wilt toevoegen aan de lijst met vertrouwde hosts in WS-Management, gebruikt u de volgende opdracht in de WSMAN provider, waarbij <Remote-Computer-Name> de naam van de externe computer is:

Set-Item -Path WSMan:\Localhost\Client\TrustedHosts -Value \<Remote-Computer-Name\>

Wanneer u een PSSession loskoppelt met behulp van de parameter InDisconnectedSession , wordt de sessiestatus verbroken en is de beschikbaarheid Geen. De waarde van de eigenschap State is relatief ten opzichte van de huidige sessie. Een waarde van 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 Beschikbaarheid om te bepalen of u verbinding kunt maken met de sessie of opnieuw verbinding kunt maken.

Een beschikbaarheidswaarde van None 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 RunspaceState voor meer informatie over de waarden van de eigenschap State van sessies. Zie RunspaceAvailability voor meer informatie over de waarden van de eigenschap Beschikbaarheid van sessies.

De parameters HostName en SSHConnection zijn opgenomen vanaf PowerShell 6.0. Ze zijn toegevoegd om externe communicatie van PowerShell te bieden op basis van Secure Shell (SSH). PowerShell en SSH worden ondersteund op meerdere platforms (Windows, Linux, macOS) en externe communicatie van PowerShell via deze platforms waarop PowerShell en SSH zijn geïnstalleerd en geconfigureerd. Dit is gescheiden van de vorige windows alleen externe communicatie die is gebaseerd op WinRM en veel van de Specifieke WinRM-functies en -beperkingen zijn niet van toepassing. Op WinRM gebaseerde quota, sessieopties, aangepaste eindpuntconfiguratie en functies voor verbinding verbreken/opnieuw verbinden worden momenteel niet ondersteund. Zie externe communicatie van PowerShell via SSH voor meer informatie over het instellen van externe communicatie van PowerShell via SSH.

Het ssh uitvoerbare bestand haalt configuratiegegevens op uit de volgende bronnen in de volgende volgorde:

  1. opdrachtregelopties
  2. configuratiebestand van gebruiker (~/.ssh/config)
  3. configuratiebestand voor het hele systeem (/etc/ssh/ssh_config)

De volgende cmdlet-parameters worden toegewezen aan ssh parameters en opties:

Cmdlet-parameter ssh-parameter equivalente ssh -o-optie
-KeyFilePath -i <KeyFilePath> -o IdentityFile=<KeyFilePath>
-UserName -l <UserName> -o User=<UserName>
-Port -p <Port> -o Port=<Port>
-ComputerName -Subsystem -s <ComputerName> <Subsystem> -o Host=<ComputerName>

Alle waarden die expliciet door parameters worden doorgegeven, hebben voorrang op waarden die zijn doorgegeven in de hashtabel Opties . Zie ssh_config(5) voor meer informatie over ssh_config bestanden.