You want to work with data and functionality provided by the WMI facilities in Windows.

To retrieve all instances of a WMI class, use the Get-WmiObject cmdlet:

Get-WmiObject -ComputerName Computer -Class Win32_Bios

To retrieve specific instances of a WMI class using a WMI filter, supply an argument to the -Filter parameter of the Get-WmiObject cmdlet. This is the WHERE clause of a WQL statement, but without the WHERE keyword:

Get-WmiObject Win32_Service -Filter "StartMode = 'Auto'"

To retrieve instances of a WMI class using WMI’s WQL language, use the [WmiSearcher] type shortcut:

$query = [WmiSearcher] "SELECT * FROM Win32_Service WHERE StartMode = 'Auto'"
$query.Get()

To retrieve a specific instance of a WMI class using a WMI filter, use the [Wmi] type shortcut:

[Wmi] 'Win32_Service.Name="winmgmt"'

To retrieve a property of a WMI instance, access that property as you would access a .NET property:

$service = [Wmi] 'Win32_Service.Name="winmgmt"'
$service.StartMode

To invoke a method on a WMI instance, invoke that method as you would invoke a .NET method:

$service = [Wmi] 'Win32_Service.Name="winmgmt"'
$service.ChangeStartMode("Manual")
$service.ChangeStartMode("Automatic")

To invoke a method on a WMI class, use the Invoke-WmiMethod cmdlet. Alternatively, use the [WmiClass] type shortcut to access that WMI class. Then, invoke that method as you would invoke a .NET method:

Invoke-WmiMethod Win32_Process Create notepad

$class = [WmiClass] "Win32_Process"
$class.Create("Notepad")

To retrieve a WMI class from a specific namespace, use its fully qualified name along with the [WmiClass] type shortcut:

[WmiClass] "\COMPUTERRootCimv2:Win32_Process"

Working with WMI has long been a staple of managing Windows systems—especially systems that are part of corporate domains or enterprises. WMI supports a huge number of Windows management tasks, albeit not in a very user-friendly way.

Traditionally, administrators required either VBScript or the WMIC command-line tool to access and manage these systems through WMI. While powerful and useful, these techniques still provided plenty of opportunities for improvement. VBScript lacks support for an ad-hoc investigative approach, and WMIC fails to provide (or take advantage of) knowledge that applies to anything outside WMIC.

In comparison, PowerShell lets you work with WMI just like you work with the rest of the shell. WMI instances provide methods and properties, and you work with them the same way you work with methods and properties of other objects in PowerShell.

Not only does PowerShell make working with WMI instances and classes easy once you have them, but it also provides a clean way to access them in the first place. For most tasks, you need only to use the simple [Wmi], [WmiClass], or [WmiSearcher] syntax as shown in the solution.

Along with WMI’s huge scope, though, comes a related problem: finding the WMI class that accomplishes your task. To assist you in learning what WMI classes are available, Appendix G provides a helpful listing of the most common ones. For a script that helps you search for WMI classes by name, description, property name, or property description, see Program: Search for WMI Classes.

Some advanced WMI tasks require that you enable your security privileges or adjust the packet privacy settings used in your request. All of PowerShell’s WMI cmdlets support these options through built-in parameters.

When you want to access a specific WMI instance with the [Wmi] accelerator, you might at first struggle to determine what properties WMI lets you search on. These properties are called key properties on the class. For a script that lists these key properties, see Program: Determine Properties Available to WMI Filters.

For more information about the Get-WmiObject cmdlet, type Get-Help Get-WmiObject.

Program: Determine Properties Available to WMI Filters

Program: Search for WMI Classes

Appendix G

You want to modify the properties of a WMI instance.

Use the Set-WmiInstance cmdlet:

PS > $bootVolume = Get-WmiObject Win32_LogicalDisk |
    Where-Object { $_.DeviceID -eq 'C:' }

PS > $bootVolume

DeviceID     : C:
DriveType    : 3
ProviderName :
FreeSpace    : 10587656192
Size         : 34357637120
VolumeName   : Boot Volume

PS > $bootVolume | Set-WmiInstance -Arguments @{ VolumeName = 'Vista' }

DeviceID     : C:
DriveType    : 3
ProviderName :
FreeSpace    : 10587656192
Size         : 34357637120
VolumeName   : Vista

Although you can assign new property values to the objects output by Get-WmiObject, changes you make ultimately are not reflected in the permanent system state, as this example shows:

PS > $bootVolume = Get-WmiObject Win32_LogicalDisk |
    Where-Object { $_.DeviceID -eq 'C:' }

PS > $bootVolume

DeviceID     : C:
DriveType    : 3
ProviderName :
FreeSpace    : 10587656192
Size         : 34357637120
VolumeName   : Vista

PS > $bootVolume.VolumeName = "Boot Volume"

PS > Get-WmiObject Win32_LogicalDisk |
    Where-Object { $_.DeviceID -eq 'C:' }


DeviceID     : C:
DriveType    : 3
ProviderName :
FreeSpace    : 10587652096
Size         : 34357637120
VolumeName   : Vista

Instead, the Set-WmiInstance cmdlet lets you permanently modify values of WMI instances. While the Set-WmiInstance cmdlet supports WMI instances as pipeline input, you can also pass the fully qualified path to the -Path parameter:

Set-WmiInstance -Path "Win32_LogicalDisk.DeviceID='C:'" `
    -Argument @{ VolumeName="Vista" }

To determine which properties can be modified on an instance, you need to investigate the WMI class that defines it. Each WMI class has a Properties collection, and each property has a Qualifiers collection. If Write is one of the qualifiers, then that property is writeable:

PS > [WmiClass] "Win32_LogicalDisk" | Select -Expand Properties

(...)
Name       : VolumeName
Value      :
Type       : String
IsLocal    : True
IsArray    : False
Origin     : Win32_LogicalDisk
Qualifiers : {CIMTYPE, MappingStrings, read, write}

Name       : VolumeSerialNumber
Value      :
Type       : String
IsLocal    : True
IsArray    : False
Origin     : Win32_LogicalDisk
Qualifiers : {CIMTYPE, MappingStrings, read}
(...)

To automatically see all writeable classes in the ROOTCIMV2 namespace, simply run this snippet of PowerShell script:

$writeableProperties = Get-WmiObject -List -Recurse |
    Select -Expand Properties |
    Where-Object { $_ | Select -Expand Qualifiers |
        Where-Object { $_.Name -eq "Write" } } | Select Origin,Name

Like all other WMI-related cmdlets, the Set-WmiInstance cmdlet lets you configure impersonation, authentication, and privilege restrictions. For more information about working with WMI classes, see Access Windows Management Instrumentation Data.

Access Windows Management Instrumentation Data

Appendix G

You want to invoke a method supported by a WMI class.

Use the Invoke-WmiMethod cmdlet:

PS > Invoke-WmiMethod -Class Win32_Process -Name Create -Args notepad.exe
(notepad starts)

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

As with .NET types, WMI classes describe the functionality and features of a related set of items. For example, the Win32_Process class describes the features and behavior of an entity called an operating system process. When WMI returns information about a specific operating system process, that is called an instance.

As with static methods on .NET types, many WMI classes offer methods that relate broadly to the entity they try to represent. For example, the Win32_Process class defines methods to start processes, stop them, and more. To invoke any of these methods, call the Invoke-WmiMethod cmdlet.

While you may already know the method you want to call, PowerShell also offers a way to see the methods exposed by WMI classes on your system. Each WMI class has a Methods collection, and reviewing that collection lists all methods supported by that class. The following snippet lists all methods supported by all classes in the ROOTCIMV2 namespace:

Get-WmiObject -List -Recurse | Select -Expand Methods | Select Origin,Name

Like all other WMI-related cmdlets, the Invoke-WmiMethod cmdlet lets you configure impersonation, authentication, and privilege restrictions.

In addition to the Invoke-WmiMethod cmdlet, the [WmiClass] type shortcut also lets you refer to a WMI class and invoke its methods:

$processClass = [WmiClass] "Win32_Process"
$processClass.Create("notepad.exe")

This method, however, does not easily support customization of impersonation, authentication, or privilege restrictions.

For more information about working with WMI classes, see Access Windows Management Instrumentation Data.

Access Windows Management Instrumentation Data

Appendix G

Run Programs, Scripts, and Existing Tools

Run Programs, Scripts, and Existing Tools

Appendix G

You want to work with advanced features of WMI, but PowerShell’s access (through the [Wmi], [WmiClass], and [WmiSearcher] accelerators) does not directly support them.

To interact with advanced features of WMI objects, access their methods and properties.

$instance = [Wmi] 'Win32_Service.Name="winmgmt"'
$instance.GetRelated()

$system = Get-WmiObject Win32_OperatingSystem
$system.Scope.Options.EnablePrivileges = $true
$system.SetDateTime($class.ConvertFromDateTime("01/01/2007"))

$class = [WmiClass] "Win32_Service"
$class.Properties

$credential = Get-Credential
$query = [WmiSearcher] "SELECT * FROM IISWebServerSetting"
$query.Scope.Path = "\REMOTE_COMPUTERRootMicrosoftIISV2"
$query.Scope.Options.Username = $credential.Username
$query.Scope.Options.Password = $credential.GetNetworkCredential().Password
$query.Scope.Options.Authentication = "PacketPrivacy"
$query.get() | Select-Object AnonymousUserName

The [Wmi], [WmiClass], and [WmiSearcher] type shortcuts return instances of .NET System.Management.ManagementObject, System.Management.ManagementClass, and System.Management.ManagementObjectSearcher classes, respectively.

As might be expected, the .NET Framework provides comprehensive support for WMI queries, with PowerShell providing an easier-to-use interface to that support. If you need to step outside the support offered directly by PowerShell, these classes in the .NET Framework provide an advanced outlet.

For more information about working with classes from the .NET Framework, see Work with .NET Objects.

Work with .NET Objects

You want to perform a large-scale WMI operation across many computers, and you want to control how many computers should be managed at a time.

Use the -ThrottleLimit parameter on the cmdlet, and invoke that cmdlet as a job:

$computers = Get-Content computers.txt
Get-WmiObject Win32_OperatingSystem -Computer $computers -ThrottleLimit 10 -AsJob

One problem with large-scale WMI operations against many computers is that most scripts invoke them sequentially. If your script acts against 10,000 servers, it will usually process the first computer, and then retrieve the results. Next, it will process the second computer, and then retrieve its results. Since WMI operations are traditionally network-bound, your script spends the vast majority of its time simply waiting for results from remote computers.

The solution to this quandary comes from invoking the commands in parallel. Not entirely in parallel, however, as most machines would buckle under the load of 10,000 active WMI queries. While it is possible to recognize the solution and pitfalls, actually implementing it is something different altogether. Even with the proper skill set, a job manager that supports automatic throttling is usually not high on an administrator’s list of priorities when compared to the collection of fires the administrator needs to put out.

Instead, PowerShell’s WMI cmdlets handle all of this complexity for you. For more information about PowerShell’s job support, see Invoke a Long-Running or Background Command.

Invoke a Long-Running or Background Command

You want to perform a WMI task in PowerShell, but you can find only VBScript examples that demonstrate the solution to the problem.

To accomplish the task of a script that retrieves data from a computer, use the Get-WmiObject cmdlet:

foreach($printer in Get-WmiObject -Computer COMPUTER Win32_Printer)
{
    ## Work with the properties
    $printer.Name
}

To accomplish the task of a script that calls methods on an instance, use the [Wmi] or [WmiSearcher] accelerators to retrieve the instances, and then call methods on the instances like you would call any other PowerShell method.

$service = [Wmi] 'Win32_Service.Name="winmgmt"'
$service | Invoke-WmiMethod -Name ChangeStartMode -ArgumentList "Manual"
$service | Invoke-WmiMethod -Name ChangeStartMode -ArgumentList "Automatic"

To accomplish the task of a script that calls methods on a class, use the Invoke-WmiMethod cmdlet, or use the [WmiClass] accelerator to retrieve the class, and then call methods on the class like you would call any other PowerShell method:

Invoke-WmiMethod Win32_Process Create notepad

$class = [WmiClass] "Win32_Process"
$class.Create("Notepad")

For many years, VBScript has been the preferred language that administrators use to access WMI data. Because of that, the vast majority of scripts available in books and on the Internet come written in VBScript.

These scripts usually take one of three forms: retrieving data and accessing properties, calling methods of an instance, and calling methods of a class.

strComputer = "."
Set objWMIService = GetObject("winmgmts:" _
    & "{impersonationLevel=impersonate}!\" & strComputer & "
ootcimv2")

Set colInstalledPrinters = objWMIService.ExecQuery _
    ("Select * from Win32_Printer")

For Each objPrinter in colInstalledPrinters
    Wscript.Echo "Name: " & objPrinter.Name
    Wscript.Echo "Location: " & objPrinter.Location
    Wscript.Echo "Default: " & objPrinter.Default
Next

$installedPrinters = Get-WmiObject Win32_Printer -ComputerName computer

foreach($printer in $installedPrinters)
{
    $printer.Name
    $printer.Location
    $printer.Default
}

Get-WmiObject Win32_Printer -ComputerName computer | Format-List Name,Location,Default

strComputer = "."
Set objWMIService = GetObject("winmgmts:" _
    & "{impersonationLevel=impersonate}!\" & strComputer & "
ootcimv2")

Set colServiceList = objWMIService.ExecQuery _
    ("Select * from Win32_Service where StartMode = 'Manual'")

For Each objService in colServiceList
    errReturnCode = objService.ChangeStartMode("Disabled")
Next

$services = Get-WmiObject Win32_Service -Filter "StartMode = 'Manual'"

foreach($service in $services)
{
    $service.ChangeStartMode("Disabled")
}

strComputer = "COMPUTER"
Set objWMIService = GetObject _
    ("winmgmts:\" & strComputer & "
ootcimv2:Win32_Process")

objWMIService.Create("notepad.exe")

Invoke-WmiMethod "\COMPUTERRootCimv2:Win32_Process" Create notepad.exe

Access Windows Management Instrumentation Data

Invoke a Method on a WMI Class