Calling methods

The Invoke-CimMethod command may be used to call a method. The CIM class can be used to find details of the methods that a class supports:

PS> (Get-CimClass Win32_Process).CimClassMethods 

Name ReturnType Parameters Qualifiers
---- ---------- ---------- ----------
Create UInt32 {CommandLine...} {Constructor...}
Terminate UInt32 {Reason} {Destructor...}
GetOwner UInt32 {Domain...} {Implemented...}
GetOwnerSid UInt32 {Sid} {Implemented...}

The method with the Constructor qualifier can be used to create a new instance of Win32_Process.

The Parameters property of a specific method can be explored to find out how to use a method:

PS> (Get-CimClass Win32_Process).CimClassMethods['Create'].Parameters

Name CimType Qualifiers
---- ------- ----------
CommandLine String {ID, In, MappingStrings}
CurrentDirectory String {ID, In, MappingStrings}
ProcessStartupInformation Instance {EmbeddedInstance, ID, In, MappingStrings}
ProcessId UInt32 {ID, MappingStrings, Out}

If an argument has the In qualifier, it can be passed in when creating an object. If an argument has the Out qualifier, it will be returned after the instance has been created. Arguments are passed in using a hashtable.

When creating a process, the CommandLine argument is required; the rest can be ignored until later:

$params = @{
ClassName = 'Win32_Process'
MethodName = 'Create'
Arguments = @{
CommandLine = 'notepad.exe' }
} $return = Invoke-CimMethod @params

The return object holds three properties in the case of Win32_Process, as follows:

PS> $return

ProcessId ReturnValue PSComputerName
--------- ----------- --------------
15172 0

PSComputerName is blank when the request is local. The ProcessId is the Out property listed under the method parameters. ReturnValue indicates whether or not the operation succeeded, and 0 indicates that it was successful.

A nonzero value indicates that something went wrong, but the values are not translated in PowerShell. The return values are documented on MSDN at https://msdn.microsoft.com/en-us/library/aa389388(v=vs.85).aspx.

The Create method used here creates a new instance. The other methods for Win32_Process act against an existing instance (an existing process).

Extending the preceding example, a process can be created and then terminated:

$params = @{
ClassName = 'Win32_Process'
MethodName = 'Create'
Arguments = @{ CommandLine = 'notepad.exe' }
} $return = Invoke-CimMethod @params

pause
Get-CimInstance Win32_Process -Filter "ProcessID=$($return.ProcessId)" | Invoke-CimMethod -MethodName Terminate

The pause command will wait for return to be pressed before continuing; this gives us the opportunity to show that Notepad was opened before it is terminated.

The Terminate method has an optional argument that is used as the exit code for the terminate process. This argument may be added using hashtable; in this case, a (made up) value of 5 is set as the exit code:

$invokeParams = @{
ClassName = 'Win32_Process'
MethodName = 'Create'
Arguments = @{ CommandLine = 'notepad.exe'
} } $return = Invoke-CimMethod @invokeParams

$getParams = @{
ClassName = 'Win32_Process'
Filter = 'ProcessId={0}' -f $return.ProcessId
}
Get-CimInstance @getParams |
Invoke-CimMethod -MethodName Terminate -Arguments @{Reason = 5}

Invoke-CimMethod returns an object with a ReturnValue. A return value of 0 indicates that the command succeeded. A nonzero value indicates an error condition. The meaning of the value will depend on the WMI class.

The return values associated with the Terminate method of Win32_Process are documented on MSDN at https://msdn.microsoft.com/en-us/library/aa393907(v=vs.85).aspx.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.222.119.148