Invoke-WSManAction

Modul:

Microsoft.WSMan.Management

Ruft eine Aktion für das Objekt auf, das vom Ressourcen-URI und von den Selektoren angegeben wird.

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

Die Invoke-WSManAction führt eine Aktion für das Objekt aus, das durch RESOURCE_URI angegeben wird, wobei Parameter durch Schlüsselwertpaare angegeben werden.

Dieses Cmdlet verwendet die WSMan-Verbindungs-/Transportebene, um die Aktion auszuführen.

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 Win32_Service WMI-Klasseninstanz auf, die dem Spooler-Dienst entspricht.

Der Rückgabewert gibt an, ob die Aktion erfolgreich war. In diesem Fall gibt ein Rückgabewert von 0 den Erfolg an. Ein Rückgabewert von 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

Dieser Befehl ruft die StopService-Methode für den Spooler-Dienst mithilfe von Eingaben aus einer Datei auf. Die Datei, Input.xml, enthält den folgenden Inhalt:

<p:StopService_INPUT xmlns:p="http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service" />

Der Rückgabewert gibt an, ob die Aktion erfolgreich war. In diesem Fall gibt ein Rückgabewert von 0 den Erfolg an. Ein Rückgabewert von 5 gibt an, dass der Dienst bereits gestartet wurde.

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. Sie übergibt die beiden Parameterwerte der Methode, 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 Win32_Service WMI-Klasseninstanz auf, die dem Spooler-Dienst entspricht. Da der Parameter ComputerName angegeben ist, wird der Befehl auf dem Remoteserver01-Computer ausgeführt.

Der Rückgabewert gibt an, ob die Aktion erfolgreich war. In diesem Fall gibt ein Rückgabewert von 0 den Erfolg an. Ein Rückgabewert von 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 ist WSMAN. Der vollständige Bezeichner für den Remoteendpunkt weist das folgende Format auf:

<Transport>://<Server>:<Port>/<ApplicationName>

Zum Beispiel:

http://server01:8080/WSMAN

Internetinformationsdienste (Internet Information Services, IIS), die die Sitzung hostet, leitet Anforderungen mit diesem Endpunkt an die angegebene Anwendung weiter. Diese Standardeinstellung von "WSMAN" ist für die meisten Verwendungen geeignet. Dieser Parameter ist so konzipiert, dass er verwendet wird, wenn zahlreiche Computer Remoteverbindungen mit einem Computer herstellen, auf dem Windows PowerShell ausgeführt wird. In diesem Fall hosten IIS Webdienste für die Verwaltung (WS-Management) zur Effizienz.

Typ:	String
Position:	Named
Standardwert:	Wsman
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-Authentication

Gibt den Authentifizierungsmechanismus an, der auf dem Server verwendet werden soll. Mögliche Werte sind:

• Basic – Einfach ist ein Schema, bei dem der Benutzername und das Kennwort 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. Mit diesem Parameterwert kann beispielsweise ermittelt werden, ob das Kerberos-Protokoll oder NTLM verwendet wird.
• CredSSP – Verwenden Sie die Authentifizierung für die Unterstützung von Anmeldeinformationen (Credential Security Support Provider, CredSSP), mit der der Benutzer Anmeldeinformationen delegieren kann. Diese Option wurde für Befehle entwickelt, die auf einem Remotecomputer ausgeführt werden, aber Daten von anderen Remotecomputern sammeln oder zusätzliche Befehle ausführen.

Vorsicht

CredSSP delegiert die Anmeldeinformationen des Benutzers vom lokalen Computer an einen Remotecomputer. Diese Vorgehensweise erhöht das Sicherheitsrisiko des Remotevorgangs. Wenn der Remotecomputer kompromittiert wird, können die Anmeldeinformationen verwendet werden, um die Netzwerksitzung zu steuern.

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 Zertifikat für den digitalen öffentlichen 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 in der zertifikatbasierten Clientauthentifizierung verwendet. Sie können nur lokalen Benutzerkonten zugeordnet werden; sie funktionieren nicht mit Domänenkonten.

Verwenden Sie zum Abrufen eines Zertifikatfingerabdrucks den Befehl Get-Item oder Get-ChildItem 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 Sie den Verwaltungsvorgang ausführen möchten. Der Wert kann ein vollqualifizierter Domänenname, ein NetBIOS-Name oder eine IP-Adresse sein. Verwenden Sie den lokalen Computernamen, verwenden Sie "localhost", oder verwenden Sie einen Punkt (.), um den lokalen Computer anzugeben. Der lokale Computer ist der Standardwert. Wenn sich der Remotecomputer in einer anderen Domäne des Benutzers befindet, müssen Sie einen vollqualifizierten Domänennamen verwenden. Sie können einen Wert für diesen Parameter an das Cmdlet weiterleiten.

Typ:	String
Aliase:	cn
Position:	Named
Standardwert:	Localhost
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 richtig formatierter Wert für diesen Parameter:

http://Server01:8080/WSMAN

Der URI muss vollqualifizierter 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. Die Standardeinstellung 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 vom Cmdlet Get-Credential 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 mithilfe des ResourceURI-Parameters und des SelectorSet-Parameters an. Der folgende Befehl verwendet beispielsweise den FilePath-Parameter:

Invoke-WSManAction -Action stopservice -ResourceUri wmicimv2/Win32_Service -SelectorSet @{Name="spooler"} -FilePath c:\input.xml -Authentication default

Dieser Befehl ruft die StopService-Methode für den Spooler-Dienst mithilfe von Eingaben aus einer Datei auf. Die Datei, Input.xml, enthält den folgenden Inhalt:

<p:StopService_INPUT xmlns:p="http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service" />

Typ:	String
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. Dies ist vergleichbar mit Optionen, die in Befehlszeilenshells verwendet werden, da sie dienstspezifisch sind. Es können beliebig viele Optionen angegeben werden.

Im folgenden Beispiel wird die Syntax veranschaulicht, die die Werte 1, 2 und 3 für die Parameter a, b und c übergibt:

-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 werden soll, wenn der Client eine Verbindung mit dem WinRM-Dienst herstellt. Wenn der Transport HTTP ist, lautet der Standardport 80. Wenn der Transport HTTPS ist, lautet der Standardport 443. Wenn Sie HTTPS als Transport verwenden, muss der Wert des ComputersName-Parameters mit dem gemeinsamen Zertifikatnamen (CN) des Servers übereinstimmen. Wenn der Parameter SkipCNCheck jedoch als Teil des SessionOption-Parameters angegeben wird, muss der gemeinsame Zertifikatname des Servers nicht mit dem Hostnamen des Servers übereinstimmen. Der Parameter SkipCNCheck sollte 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 zu identifizieren, z. B. Datenträger oder Prozesse, auf einem Computer.

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 Gruppe von Wertpaaren an, die zum Auswählen bestimmter Verwaltungsressourceninstanzen verwendet werden. SelectorSet- wird verwendet, wenn mehrere Instanzen der Ressource vorhanden sind. Der Wert 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 erweiterter Optionen für die WS-Management Sitzung. Geben Sie ein SessionOption-Objekt ein, das Sie mithilfe des Cmdlets New-WSManSessionOption 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 den zusätzlichen Schutz von HTTPS anstelle von HTTP angeben. Wenn SSL für den Für die Verbindung verwendeten Port nicht verfügbar ist und Sie diesen Parameter angeben, schlägt der Befehl fehl.

Typ:	SwitchParameter
Position:	Named
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-ValueSet

Gibt eine Hashtabelle an, mit der eine Verwaltungsressource geändert werden kann. Sie geben die Verwaltungsressource mit den Parametern 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

XmlElement

Dieses Cmdlet gibt das Ergebnis des Vorgangs als XmlElement--Objekt zurück.

Ähnliche Themen

• Invoke-WmiMethod
• Connect-WSMan
• Disable-WSManCredSSP
• Disconnect-WSMan
• Enable-WSManCredSSP
• Get-WSManCredSSP
• Get-WSManInstance
• New-WSManInstance
• New-WSManSessionOption
• Remove-WSManInstance
• Set-WSManInstance
• Set-WSManQuickConfig
• Test-WSMan