Invoke-WSManAction
Ruft eine Aktion für das Objekt auf, das durch den Ressourcen-URI und die Selektoren angegeben ist.
Syntax
Invoke-WSManAction
[-Action] <String>
[-ConnectionURI <Uri>]
[-FilePath <String>]
[-OptionSet <Hashtable>]
[[-SelectorSet] <Hashtable>]
[-SessionOption <SessionOption>]
[-ValueSet <Hashtable>]
[-ResourceURI] <Uri>
[-Credential <PSCredential>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[<CommonParameters>]
Invoke-WSManAction
[-Action] <String>
[-ApplicationName <String>]
[-ComputerName <String>]
[-FilePath <String>]
[-OptionSet <Hashtable>]
[-Port <Int32>]
[[-SelectorSet] <Hashtable>]
[-SessionOption <SessionOption>]
[-UseSSL]
[-ValueSet <Hashtable>]
[-ResourceURI] <Uri>
[-Credential <PSCredential>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[<CommonParameters>]
Beschreibung
Dieses Cmdlet ist nur auf der Windows-Plattform verfügbar.
Die Invoke-WSManAction
Ausführung einer Aktion für das Objekt, das durch RESOURCE_URI angegeben wird, wobei Parameter durch Schlüsselwertpaare angegeben werden.
Das Cmdlet verwendet die Verbindungs-/Transportschicht von WSMan zum Ausführen der Aktion.
Beispiele
Beispiel 1: Aufrufen einer Methode
Invoke-WSManAction -Action startservice -ResourceURI wmicimv2/win32_service -SelectorSet @{name="spooler"} -Authentication default
xsi : http://www.w3.org/2001/XMLSchema-instance
p : http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service
cim : http://schemas.dmtf.org/wbem/wscim/1/common
lang : en-US
ReturnValue : 0
Dieser Befehl ruft die StartService-Methode der WMI-Klasseninstanz Win32_Service auf, die dem Spoolerdienst entspricht.
Der Rückgabewert gibt an, ob die Aktion erfolgreich war. In diesem Fall deutet der Rückgabewert 0 auf eine erfolgreiche Aktion hin. Der Rückgabewert 5 gibt an, dass der Dienst bereits gestartet wurde.
Beispiel 2: Aufrufen einer Methode
Invoke-WSManAction -Action stopservice -ResourceURI wmicimv2/Win32_Service -SelectorSet @{Name="spooler"} -FilePath:input.xml -Authentication default
xsi : http://www.w3.org/2001/XMLSchema-instance
p : http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service
cim : http://schemas.dmtf.org/wbem/wscim/1/common
lang : en-US
ReturnValue : 0
Mit diesem Befehl wird die StopService-Methode für den Spooler-Dienst mithilfe von Eingaben aus einer Datei aufgerufen.
Die Datei enthält Input.xml
den folgenden Inhalt:
<p:StopService_INPUT xmlns:p="http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service" />
Beispiel 3: Aufrufen einer Methode mit angegebenen Parameterwerten
Invoke-WSManAction -Action create -ResourceURI wmicimv2/win32_process -ValueSet @{commandline="notepad.exe";currentdirectory="C:\"}
xsi : http://www.w3.org/2001/XMLSchema-instance
p : http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Process
cim : http://schemas.dmtf.org/wbem/wscim/1/common
lang : en-US
ProcessId : 6356
ReturnValue : 0
Mit diesem Befehl wird die Create-Methode der klasse Win32_Process aufgerufen. Es übergibt die Methode zwei Parameterwerte Notepad.exe
und C:\
. Daher wird ein neuer Prozess erstellt, um Editor auszuführen, und das aktuelle Verzeichnis des neuen Prozesses wird auf C:\
festgelegt.
Beispiel 4: Aufrufen einer Methode auf einem Remotecomputer
Invoke-WSManAction -Action startservice -ResourceURI wmicimv2/win32_service -SelectorSet @{name="spooler"} -ComputerName server01 -Authentication default
xsi : http://www.w3.org/2001/XMLSchema-instance
p : http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service
cim : http://schemas.dmtf.org/wbem/wscim/1/common
lang : en-US
ReturnValue : 0
Dieser Befehl ruft die StartService-Methode der WMI-Klasseninstanz Win32_Service auf, die dem Spoolerdienst entspricht. Da der ComputerName-Parameter angegeben ist, wird der Befehl für den Remotecomputer server01 ausgeführt.
Der Rückgabewert gibt an, ob die Aktion erfolgreich war. In diesem Fall deutet der Rückgabewert 0 auf eine erfolgreiche Aktion hin. Der Rückgabewert 5 gibt an, dass der Dienst bereits gestartet wurde.
Parameter
-Action
Gibt die Methode an, die für das verwaltungsobjekt ausgeführt werden soll, das durch den ResourceURI und selektoren angegeben wird.
Typ: | String |
Position: | 1 |
Standardwert: | None |
Erforderlich: | True |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-ApplicationName
Gibt den Anwendungsnamen in der Verbindung an. Der Standardwert des ApplicationName-Parameters lautet WSMAN. Der vollständige Bezeichner für den Remoteendpunkt hat das folgende Format:
<Transport>://<Server>:<Port>/<ApplicationName>
Zum Beispiel:
http://server01:8080/WSMAN
Die Sitzung wird von IIS (Internetinformationsdienste) gehostet. IIS leitet Anforderungen mit diesem Endpunkt an die angegebene Anwendung weiter. Die Standardeinstellung „WSMAN“ eignet sich für die meisten Verwendungszwecke. Dieser Parameter soll verwendet werden, wenn mehrere Computer Remoteverbindungen mit einem Computer herstellen, auf dem Windows PowerShell ausgeführt wird. In diesem Fall hostet IIS Webdienste für die Verwaltung (WS-Management) zur Effizienz.
Typ: | String |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-Authentication
Gibt den Authentifizierungsmechanismus an, der auf dem Server verwendet werden soll. Dabei sind folgende Werte möglich:
Basic
- Einfach ist ein Schema, bei dem der Benutzername und das Kennwort im Klartext an den Server oder Proxy gesendet werden.Default
- Verwenden Sie die vom WS-Management-Protokoll implementierte Authentifizierungsmethode. Dies ist die Standardeinstellung.Digest
– Digest ist ein Abfrageantwortschema, das eine serverspezifische Datenzeichenfolge für die Abfrage verwendet.Kerberos
– Der Clientcomputer und der Server authentifizieren sich gegenseitig mithilfe von Kerberos-Zertifikaten.Negotiate
- Negotiate ist ein Abfrageantwortschema, das mit dem Server oder Proxy aushandelt, um das schema zu bestimmen, das für die Authentifizierung verwendet werden soll. Dieser Parameterwert ermöglicht es z. B., die Verwendung des Kerberos-Protokolls oder von NTLM auszuhandeln.CredSSP
– Verwenden Der Credential Security Support Provider (CredSSP)-Authentifizierung, mit der der Benutzer Anmeldeinformationen delegieren kann. Diese Option ist für Befehle vorgesehen, die auf einem Remotecomputer ausgeführt werden, jedoch Daten von anderen Remotecomputern sammeln oder zusätzliche Befehle auf anderen Remotecomputern ausführen.
Achtung
CredSSP delegiert die Anmeldeinformationen des Benutzers vom lokalen Computer an einen Remotecomputer. Dieser Vorgang erhöht das Sicherheitsrisiko des Remotevorgangs. Wenn die Sicherheit des Remotecomputers gefährdet ist, während Anmeldeinformationen an ihn übergeben werden, können die Anmeldeinformationen zum Steuern der Netzwerksitzung verwendet werden.
Typ: | AuthenticationMechanism |
Aliase: | auth, am |
Zulässige Werte: | None, Default, Digest, Negotiate, Basic, Kerberos, ClientCertificate, Credssp |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-CertificateThumbprint
Gibt das digitale Zertifikat für öffentliche Schlüssel (X509) eines Benutzerkontos an, das über die Berechtigung zum Ausführen dieser Aktion verfügt. Geben Sie den Zertifikatfingerabdruck des Zertifikats ein.
Zertifikate werden bei der clientzertifikatbasierten Authentifizierung verwendet. Sie können nur lokalen Benutzerkonten zugeordnet werden und funktionieren nicht mit Domänenkonten.
Verwenden Sie zum Abrufen eines Zertifikatfingerabdrucks den Befehl oder Get-ChildItem
den Get-Item
Befehl im Windows PowerShell-Zertifikat: Laufwerk.
Typ: | String |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-ComputerName
Gibt den Computer an, für den der Verwaltungsvorgang ausgeführt werden soll. Bei dem Wert kann es sich um einen vollqualifizierten Domänennamen, einen NetBIOS-Namen oder eine IP-Adresse handeln. Verwenden Sie den lokalen Computernamen, verwenden Sie localhost, oder verwenden Sie einen Punkt (.
), um den lokalen Computer anzugeben. Der lokale Computer ist die Standardeinstellung. Wenn sich der Remotecomputer in einer anderen Domäne als der Benutzer befindet, müssen Sie einen vollqualifizierten Domänennamen verwenden. Sie können einen Wert für diesen Parameter an das Cmdlet weiterreichen.
Typ: | String |
Aliase: | cn |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-ConnectionURI
Gibt den Verbindungsendpunkt an. Das Format dieser Zeichenfolge lautet:
<Transport>://<Server>:<Port>/<ApplicationName>
Die folgende Zeichenfolge ist ein ordnungsgemäß formatierter Wert für diesen Parameter:
http://Server01:8080/WSMAN
Der URI muss vollqualifiziert sein.
Typ: | Uri |
Aliase: | CURI, CU |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-Credential
Gibt ein Benutzerkonto an, das über die Berechtigung zum Ausführen dieser Aktion verfügt. Der Standardwert ist der aktuelle Benutzer. Geben Sie einen Benutzernamen ein, z. B. "User01", "Domain01\User01" oder User@Domain.com. Oder geben Sie ein PSCredential-Objekt ein, z. B. ein objekt, das Get-Credential
vom Cmdlet zurückgegeben wird. Wenn Sie einen Benutzernamen eingeben, werden Sie zur Eingabe eines Kennworts aufgefordert.
Typ: | PSCredential |
Aliase: | cred, c |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | True |
Platzhalterzeichen akzeptieren: | False |
-FilePath
Gibt den Pfad einer Datei an, die zum Aktualisieren einer Verwaltungsressource verwendet wird. Sie geben die Verwaltungsressource mit dem ResourceURI-Parameter und SelectorSet-Parameter an. Der folgende Befehl verwendet z. B. den FilePath-Parameter:
Invoke-WSManAction -Action stopservice -ResourceUri wmicimv2/Win32_Service -SelectorSet @{Name="spooler"} -FilePath c:\input.xml -Authentication default
Mit diesem Befehl wird die StopService-Methode für den Spooler-Dienst mithilfe von Eingaben aus einer Datei aufgerufen. Die Datei enthält Input.xml
den folgenden Inhalt:
<p:StopService_INPUT xmlns:p="http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service" />
Typ: | String |
Aliase: | Path |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-OptionSet
Übergibt eine Reihe von Schaltern an einen Dienst, um die Art der Anforderung zu ändern oder zu verfeinern. Diese sind mit Schaltern in Befehlszeilenshells vergleichbar, da sie dienstspezifisch sind. Es kann eine beliebige Anzahl von Optionen angegeben werden.
Das folgende Beispiel veranschaulicht die Syntax, durch die die Werte 1, 2 und 3 für die Parameter „a“, „b“ und „c“ übergeben werden:
-OptionSet @{a=1;b=2;c=3}
Typ: | Hashtable |
Aliase: | os |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | True |
Platzhalterzeichen akzeptieren: | False |
-Port
Gibt den Port an, der verwendet wird, wenn der Client eine Verbindung mit dem WinRM-Dienst herstellt. Wenn der Transport auf HTTP festgelegt ist, lautet der Standardport 80. Wenn der Transport auf HTTPS festgelegt ist, lautet der Standardport 443. Wenn Sie HTTPS als Transport verwenden, muss der Wert des ComputerName-Parameters mit dem allgemeinen Namen des Serverzertifikats übereinstimmen. Wenn der SkipCNCheck-Parameter jedoch als Teil des SessionOption-Parameters angegeben wird, muss der allgemeine Servername im Zertifikat nicht mit dem Hostnamen des Servers übereinstimmen. Der SkipCNCheck-Parameter darf nur für vertrauenswürdige Computer verwendet werden.
Typ: | Int32 |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-ResourceURI
Enthält den URI (Uniform Resource Identifier) der Ressourcenklasse oder -instanz. Der URI wird verwendet, um einen bestimmten Ressourcentyp auf einem Computer zu identifizieren, z. B. Datenträger oder Prozesse.
Ein URI besteht aus einem Präfix und einem Pfad zu einer Ressource. Zum Beispiel:
http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk
http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor
Typ: | Uri |
Aliase: | ruri |
Position: | 0 |
Standardwert: | None |
Erforderlich: | True |
Pipelineeingabe akzeptieren: | True |
Platzhalterzeichen akzeptieren: | False |
-SelectorSet
Gibt eine Reihe von Wertpaaren an, mit denen bestimmte Instanzen von Verwaltungsressourcen ausgewählt werden. SelectorSet wird verwendet, wenn mehrere Instanzen der Ressource vorhanden sind. Der Wert von SelectorSet muss eine Hashtabelle sein.
Das folgende Beispiel zeigt, wie Sie einen Wert für diesen Parameter eingeben:
-SelectorSet @{Name="WinRM";ID="yyy"}
Typ: | Hashtable |
Position: | 2 |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | True |
Platzhalterzeichen akzeptieren: | False |
-SessionOption
Definiert eine Reihe von erweiterten Optionen für die WS-Management-Sitzung. Geben Sie ein SessionOption-Objekt ein, das Sie mithilfe des New-WSManSessionOption
Cmdlets erstellen. Weitere Informationen zu den verfügbaren Optionen finden Sie unter New-WSManSessionOption
.
Typ: | SessionOption |
Aliase: | so |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-UseSSL
Gibt an, dass das SSL-Protokoll (Secure Sockets Layer) verwendet wird, um eine Verbindung mit dem Remotecomputer herzustellen. Standardmäßig wird SSL nicht verwendet.
WS-Management verschlüsselt alle PowerShell-Inhalte, die über das Netzwerk übertragen werden. Mit dem UseSSL-Parameter können Sie anstelle von HTTP das sicherere HTTPS angeben. Wenn SSL an dem für die Verbindung verwendeten Port nicht verfügbar ist und Sie diesen Parameter angeben, verursacht der Befehl einen Fehler.
Typ: | SwitchParameter |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
-ValueSet
Gibt eine Hashtabelle an, mit deren Hilfe eine Verwaltungsressource geändert werden kann. Sie geben die Verwaltungsressource mithilfe der Parameter ResourceURI und SelectorSet an. Der Wert des ValueSet-Parameters muss eine Hashtabelle sein.
Typ: | Hashtable |
Position: | Named |
Standardwert: | None |
Erforderlich: | False |
Pipelineeingabe akzeptieren: | False |
Platzhalterzeichen akzeptieren: | False |
Eingaben
None
Sie können keine Objekte an dieses Cmdlet weiterleiten.
Ausgaben
Dieses Cmdlet gibt das Ergebnis des Vorgangs als XmlElement-Objekt zurück.