Invoke-WmiMethod

Applies To: Windows PowerShell 2.0

Calls Windows Management Instrumentation (WMI) methods.

Syntax

Invoke-WmiMethod [-Class] <string> [-Name] <string> [[-ArgumentList] <Object[]>] [-AsJob] [-Authentication {<Default> | <None> | <Connect> | <Call> | <Packet> | <PacketIntegrity> | <PacketPrivacy> | <Unchanged>}] [-Authority <string>] [-ComputerName <string[]>] [-Credential <PSCredential>] [-EnableAllPrivileges] [-Impersonation {<Default> | <Anonymous> | <Identify> | <Impersonate> | <Delegate>}] [-Locale <string>] [-Namespace <string>] [-ThrottleLimit <int>] [-Confirm] [-WhatIf] [<CommonParameters>]

Invoke-WmiMethod [-Name] <string> [-AsJob] [-Authentication {<Default> | <None> | <Connect> | <Call> | <Packet> | <PacketIntegrity> | <PacketPrivacy> | <Unchanged>}] [-Authority <string>] [-ComputerName <string[]>] [-Credential <PSCredential>] [-EnableAllPrivileges] [-Impersonation {<Default> | <Anonymous> | <Identify> | <Impersonate> | <Delegate>}] [-Locale <string>] [-Namespace <string>] [-ThrottleLimit <int>] [-Confirm] [-WhatIf] [<CommonParameters>]

Invoke-WmiMethod [-Name] <string> -InputObject <ManagementObject> [-ArgumentList <Object[]>] [-AsJob] [-ThrottleLimit <int>] [-Confirm] [-WhatIf] [<CommonParameters>]

Invoke-WmiMethod [-Name] <string> -Path <string> [-ArgumentList <Object[]>] [-AsJob] [-Authentication {<Default> | <None> | <Connect> | <Call> | <Packet> | <PacketIntegrity> | <PacketPrivacy> | <Unchanged>}] [-Authority <string>] [-ComputerName <string[]>] [-Credential <PSCredential>] [-EnableAllPrivileges] [-Impersonation {<Default> | <Anonymous> | <Identify> | <Impersonate> | <Delegate>}] [-Locale <string>] [-Namespace <string>] [-ThrottleLimit <int>] [-Confirm] [-WhatIf] [<CommonParameters>]

Invoke-WmiMethod [-Name] <string> [-AsJob] [-Authentication {<Default> | <None> | <Connect> | <Call> | <Packet> | <PacketIntegrity> | <PacketPrivacy> | <Unchanged>}] [-Authority <string>] [-ComputerName <string[]>] [-Credential <PSCredential>] [-EnableAllPrivileges] [-Impersonation {<Default> | <Anonymous> | <Identify> | <Impersonate> | <Delegate>}] [-Locale <string>] [-Namespace <string>] [-ThrottleLimit <int>] [-Confirm] [-WhatIf] [<CommonParameters>]

Invoke-WmiMethod [-Name] <string> [-AsJob] [-Authentication {<Default> | <None> | <Connect> | <Call> | <Packet> | <PacketIntegrity> | <PacketPrivacy> | <Unchanged>}] [-Authority <string>] [-ComputerName <string[]>] [-Credential <PSCredential>] [-EnableAllPrivileges] [-Impersonation {<Default> | <Anonymous> | <Identify> | <Impersonate> | <Delegate>}] [-Locale <string>] [-Namespace <string>] [-ThrottleLimit <int>] [-Confirm] [-WhatIf] [<CommonParameters>]

Description

The Invoke-WmiMethod cmdlet calls WMI methods.

Parameters

-ArgumentList <Object[]>

Specifies the parameters to pass to the called method. The value of this parameter must be an array of objects and they must appear in the order required by the called method.

Important: If the first value is an array containing more than one element, then a second value of $null is required, otherwise the command will generate an error, such as "Unable to cast object of type 'System.Byte' to type 'System.Array'.".

An example using an array of objects ($binSD) followed by a null value ($null) follows:

PS C:\> $acl = Get-Acl test.txt

PS C:\> $binSD = $acl.GetSecurityDescriptorBinaryForm()

PS C:\> invoke-wmimethod -class Win32_SecurityDescriptorHelper -Name BinarySDToSDDL -argumentlist $binSD, $null

-AsJob

Runs the command as a background job. Use this parameter to run commands that take a long time to finish.

When you use the AsJob parameter, the command returns an object that represents the background job and then displays the command prompt. You can continue to work in the session while the job finishes. If Invoke-WmiMethod is used against a remote computer, the job is created on the local computer, and the results from remote computers are automatically returned to the local computer. To manage the job, use the cmdlets that contain the Job noun (the Job cmdlets). To get the job results, use the Receive-Job cmdlet.

Note: To use this parameter with remote computers, the local and remote computers must be configured for remoting. Additionally, you must start Windows PowerShell by using the "Run as administrator" option in Windows Vista and later versions of Windows. For more information, see about_Remote_Requirements.

For more information about Windows PowerShell background jobs, see about_Jobs and about_Remote_Jobs.

-Authentication <AuthenticationLevel>

Specifies the authentication level to be used with the WMI connection. Valid values are:

-1: Unchanged

0: Default

1: None (No authentication in performed.)

2: Connect (Authentication is performed only when the client establishes a relationship with the application.)

3: Call (Authentication is performed only at the beginning of each call when the application receives the request.)

4: Packet (Authentication is performed on all the data that is received from the client.)

5: PacketIntegrity (All the data that is transferred between the client and the application is authenticated and verified.)

6: PacketPrivacy (The properties of the other authentication levels are used, and all the data is encrypted.)

-Authority <string>

Specifies the authority to use to authenticate the WMI connection. You can specify standard NTLM or Kerberos authentication. To use NTLM, set the authority setting to ntlmdomain:<DomainName>, where <DomainName> identifies a valid NTLM domain name. To use Kerberos, specify kerberos:<DomainName\ServerName>. You cannot include the authority setting when you connect to the local computer.

-Class <string>

Specifies the WMI class that contains a static method to call.

-ComputerName <string[]>

Specifies the computer against which you want to run the management operation. The value can be a fully qualified domain name, a NetBIOS name, or an Internet Protocol (IP) address. Use the local computer name, use localhost, or use a dot (.) to specify the local computer. The local computer is the default. When the remote computer is in a different domain from the user, a fully qualified domain name is required. You can also set the value of this parameter by piping the value to the parameter.

-Credential <PSCredential>

Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01", "Domain01\User01", or User@Contoso.com. Or, enter a PSCredential object, such as an object that is returned by the Get-Credential cmdlet. When you type a user name, you will be prompted for a password.

-EnableAllPrivileges

Enables all the privileges of the current user before the command makes the WMI call.

-Impersonation <ImpersonationLevel>

Specifies the impersonation level to use. Valid values are:

0: Default (Reads the local registry for the default impersonation level, which is usually set to "3: Impersonate".)

1: Anonymous (Hides the credentials of the caller.)

2: Identify (Allows objects to query the credentials of the caller.)

3: Impersonate (Allows objects to use the credentials of the caller.)

4: Delegate (Allows objects to permit other objects to use the credentials of the caller.)

-InputObject <ManagementObject>

Specifies a ManagementObject object to use as input. When this parameter is used, all other parameters except the Flag and Argument parameters are ignored.

-Locale <string>

Specifies the preferred locale for WMI objects. Specify the value of the Locale parameter as an array in the MS_<LCID> format in the preferred order.

-Name <string>

Specifies the name of the method to be invoked. This parameter is mandatory and cannot be null or empty.

-Namespace <string>

When used with the Class parameter, this parameter specifies the WMI repository namespace where the referenced WMI class or object is located.

-Path <string>

Specifies the WMI object path of a WMI class, or specifies the WMI object path of an instance of a WMI class. The class or the instance that you specify must contain the method that is specified in the Name parameter.

-ThrottleLimit <int>

Allows the user to specify a throttling value for the number of WMI operations that can be executed simultaneously. This parameter is used together with the AsJob parameter. The throttle limit applies only to the current command, not to the session or to the computer.

-Confirm

Prompts you for confirmation before executing the command.

-WhatIf

Describes what would happen if you executed the command without actually executing the command.

<CommonParameters>

This command supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, and WarningVariable. For more information, see about_CommonParameters.

Inputs and Outputs

The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.

Example 1

C:\PS>invoke-wmimethod -path win32_process -name create -argumentlist notepad.exe

__GENUS          : 2
__CLASS          : __PARAMETERS
__SUPERCLASS     :
__DYNASTY        : __PARAMETERS
__RELPATH        :
__PROPERTY_COUNT : 2
__DERIVATION     : {}
__SERVER         :
__NAMESPACE      :
__PATH           :
ProcessId        : 4844
ReturnValue      : 0

Description
-----------
This command starts an instance of Notepad by calling the Create method of the Win32_Process class.

Note: The ReturnValue property is populated with a 0, and the ProcessId property is populated with an integer (the next process ID number) if the command is completed.

Example 2

C:\PS>invoke-wmimethod -path "CIM_DataFile.Name='C:\scripts\test.txt'" -Name Rename -ArgumentList "C:\scripts\test_bu.txt"

__GENUS          : 2
__CLASS          : __PARAMETERS
__SUPERCLASS     :
__DYNASTY        : __PARAMETERS
__RELPATH        :
__PROPERTY_COUNT : 1
__DERIVATION     : {}
__SERVER         :
__NAMESPACE      :
__PATH           :
ReturnValue      : 0

Description
-----------
This command renames a file. It uses the Path parameter to reference an instance of the CIM_DataFile class. Then, it applies the Rename method to that particular instance.

Note: The ReturnValue property is populated with a 0 if the command is completed.

See Also

Concepts

Get-WmiObject
Remove-WmiObject
Set-WmiInstance
Get-WSManInstance
Invoke-WSManAction
New-WSManInstance
Remove-WSManInstance