Calling methods

Calling a method on an existing instance of an object found using Get-WmiObject is similar to any .NET method call.

The following example gets and restarts the DNS Client service. The following operation requires administrative access:

$service = Get-WmiObject Win32_Service -Filter "DisplayName='DNS Client'" 
$service.StopService()     # Call the StopService method 
$service.StartService()    # Call the StartService method  

The WMI class can be used to find the details of a method; for example, the Create method of Win32_Share, as follows:

PS> (Get-WmiObject Win32_Share -List).Methods['Create']

Name : Create
InParameters : System.Management.ManagementBaseObject
OutParameters : System.Management.ManagementBaseObject
Origin : Win32_Share
Qualifiers : {Constructor, Implemented, MappingStrings, Static}

Where the Invoke-CimMethod command accepts a hashtable, the Invoke-WmiMethod command expects arguments to be passed as an array, in a specific order. The order can be retrieved by using the GetMethodParameters method of the WMI class:

PS> (Get-WmiObject Win32_Share -List).GetMethodParameters('Create')


__GENUS : 2
__CLASS : __PARAMETERS
__SUPERCLASS :
__DYNASTY : __PARAMETERS
__RELPATH :
__PROPERTY_COUNT : 7
__DERIVATION : {}
__SERVER :
__NAMESPACE :
__PATH :
Access :
Description :
MaximumAllowed :
Name :
Password :
Path :
Type :
PSComputerName :

To create a share, the argument list must therefore contain an argument for Access, then Description, then MaximumAllowed, and so on. If the argument is optional, it can be set to null; however, PowerShell is unable to say which are mandatory, so a trip to MSDN is required: https://msdn.microsoft.com/en-us/library/aa389393(v=vs.85).aspx.

Having established that Path, Name, and Type are mandatory; an array of arguments can be created in the order described by GetMethodParameters:

$argumentList = $null,            # Access 
                $null,            # Description 
                $null,            # MaximumAllowed 
                'Share1',         # Name 
                $null,            # Password 
                'C:TempShare1', # Path 
                0                 # Type (Disk Drive) 
Invoke-WmiMethod Win32_Share -Name Create -ArgumentList $argumentList 

The return value describes the result of the operation; a ReturnValue of 0 indicates success. As this operation requires administrator privileges (run as administrator), a return value of 2 is used to indicate that it was run without sufficient rights.

If the folder used in the previous example does not exist, the ReturnValue will be set to 24.

Adding the ComputerName parameter to Invoke-WmiMethod will create a share on a remote machine.

Arrays of null values are messy

This method of supplying arguments to execute a method is difficult to work with for all but the simplest of methods. An alternative is to use the .NET method InvokeMethod on the class object:

$class = Get-WmiObject Win32_Share -List
$inParams = $class.GetMethodParameters('Create')
$inParams.Name = 'Share1'
$inParams.Path = 'C:TempShare1'
$inParams.Type = 0
$return = $class.InvokeMethod('Create', $inParams, $null)

The last argument, set to null here, is InvokeMethodOptions, which is most often used to define a timeout for the operation. Doing so is beyond the scope of this chapter.

To create a share on a remote computer, use the ComputerName parameter with Get-WmiObject.
..................Content has been hidden....................

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