Invoke-WSManAction

Invoke an action on a specified object via WSMan (Web Services-Management). The objects is specified with -ResourceURI

Syntax
      Invoke-WSManAction [-ApplicationName string] [-ComputerName string]
         [-Credential PSCredential] [-Port int] [-UseSSL] [-ResourceURI] Uri
            [-Action] string [-Authentication AuthMechanism]
               [-FilePath File] [-OptionSet hashtable] [-SelectorSet hashtable]
                  [-SessionOption hashtable] [-ValueSet hashtable] [CommonParameters]
Invoke-WSManAction [-ConnectionURI Uri] [-ResourceURI] Uri [-Action] string [-Authentication AuthenticationMechanism] [-FilePath File] [-OptionSet hashtable] [-SelectorSet hashtable] [-SessionOption hashtable] [-ValueSet hashtable] [CommonParameters] Key -Action string The method to run on the management object specified by -ResourceURI and selectors. -ApplicationName string The application name in the connection. The default Application Name is "WSMAN" The complete identifier for the remote endpoint is in the following format: transport://server:port/ApplicationName For example: http://server64:8080/WSMAN IIS will forward requests with this endpoint to the specified application. This default setting of "WSMAN" is appropriate for most uses. This parameter is designed to be used when numerous computers establish remote connections to one computer that is running PowerShell. In this case, IIS hosts Web Services for Management (WS-Management) for efficiency. -Authentication AuthMechanism The authentication mechanism to be used at the server. Possible values are: - Basic Send username and password in clear text. - Default Use the authentication method implemented by WS-Management protocol. This is the default. - Digest Challenge-response scheme using a server-specified data string for the challenge. - Kerberos Authenticate by using Kerberos certificates. - Negotiate Challenge-response that negotiates an authentication scheme. e.g. Kerberos protocol or NTLM. - CredSSP Use Credential Security Service Provider (CredSSP) authentication, delegate credentials to a remote computer. This increases the security risk, if the remote computer is compromised, the credentials could be used to control the network session. -ComputerName string The computer against which you want to run the management operation. A fully qualified domain name, NetBIOS name, or an IP address. Use the local computer name, localhost, or a dot (.) to specify the local computer. The local computer is the default. When the remote computer is in a different domain, use a fully qualified domain name. You can pipe a value for ComputerName. -ConnectionURI Uri The connection endpoint. The format of this string is: Transport://Server:Port/ApplicationName. The following string is a properly formatted value for this parameter: http://Server01:8080/WSMAN. The URI must be fully qualified. -Credential PSCredential A user account that has permission to perform this action. default=current user. e.g. "User01", "Domain01\User01", or "User@Domain.com". Or a PSCredential object, such as returned by the Get-Credential cmdlet. When you type a user name, you will be prompted for a password. -FilePath File The path of a file that is used to update a management resource. Specify the management resource by using the -ResourceURI parameter and the -SelectorSet parameter. For example, the following command uses the -FilePath parameter: invoke-wsmanaction -action stopservice -resourceuri wmicimv2/Win32_Service -SelectorSet @{Name="spooler"} -FilePath:c:\input.xml -authentication default This command calls the StopService method on the Spooler service by using input from a file. The file, Input.xml, contains the following: <p:StopService_INPUT xmlns:p="http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service"/> -OptionSet hashtable Pass a set of switches to the service to modify or refine the nature of the request. These are similar to switches used in command-line shells in that they are service specific. Any number of options can be specified. The following example demonstrates the syntax that passes the values 1, 2, and 3 for the a, b, and c parameters: -OptionSet @{a=1;b=2;c=3} -Port int The port to use when the client connects to the WinRM service. When the transport is HTTP, the default port is 80. When the transport is HTTPS, the default port is 443. When you use HTTPS as the transport, the value of the -ComputerName parameter must match the server's certificate common name (CN). However, if the SkipCNCheck parameter is specified as part of the SessionOption parameter, then the certificate common name of the server does not have to match the host name of the server. The SkipCNCheck parameter should be used only for trusted computers. -ResourceURI Uri Contains the Uniform Resource Identifier (URI) of the resource class or instance. The URI is used to identify aspecific type of resource, such as disks or processes, on a computer. A URI consists of a prefix and a path to a resource. For example: http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor -SelectorSet hashtable
A set of value pairs that are used to select particular management resource instances. The SelectorSet parameter is used when more than one instance of the resource exists.
The following example shows how to enter a value for this parameter:

-SelectorSet @{Name="WinRM";ID="yyy"} -SessionOption hashtable Define a set of extended options for the WS-Management session. Enter a SessionOption object that you create by using New-WSManSessionOption. -UseSSL Use the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used. WS-Management encrypts all PowerShell content that is transmitted over the network. The UseSSL parameter lets you specify the additional protection of HTTPS instead of HTTP. This will fail if SSL is not available on the port that is used for the connection. -ValueSet hashtable
A hash table that helps modify a management resource. Specify the management resource by using -ResourceURI and -SelectorSet. CommonParameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable, -OutBuffer -OutVariable.

Invoke-WSManAction uses the WSMan connection/transport layer to run the action.

Examples

Call the StartService method of the Win32_Service WMI class instance that corresponds to the Spooler service:

PS C:\> invoke-wsmanaction -action startservice -resourceuri wmicimv2/win32_service -selectorset @{name="spooler"} -authentication default

Call the StartService method of the Win32_Service WMI class instance that corresponds to the Spooler service. Because the ComputerName parameter is specified, the command runs against the remote server64 computer:

PS C:\> invoke-wsmanaction -action startservice -resourceuri wmicimv2/win32_service -selectorset @{name="spooler"} -computername server64 -authentication default

The return value indicates whether the action was successful. In this case, a return value of 0 indicates success. A return value of 5 indicates that the service is already started.

“Action conquers fear” ~ Peter Nivio Zarlenga

Related:

Connect-WSMan - Connect to the WinRM service on a remote computer
psExec - Execute process remotely


© Copyright SS64.com 1999-2013
Some rights reserved