Setting Network Parameters Using WMI (Part 1)

Scripting configuration of network parameters, such as IP addresses of primary and secondary WINS or DNS servers and lists of DNS suffixes, was rather cumbersome in Windows NT 4.0.

Windows Management Instrumentation provides a number of ways to collect information about network configuration and manage its parameters, making scripting configuration in Windows 2000 and Windows XP much easier. In the first of a two-part article, Marcin Policht overviews the two main classes in WMI that deal with network adapters.

Without having access to APIs available to programmers, it was necessary to resort to workarounds, such as sequence of SendKey methods calls or direct registry manipulation. The first approach (using SendKey method) was at best time consuming to write and at worst vulnerable at runtime. Anyone changing focus windows during script execution could affect its results in a difficult to predict fashion. Direct registry manipulation was much more reliable and rather easy when dealing with DNS-related parameters, since they resided in specific area of registry. WINS settings, on the other hand, were configured on a per-network adapter basis, so their location varied, depending on number and type of network adapters installed on the computer.

Locating the WINS and DNS configuration information became even more challenging in Windows 2000 and XP. This is because each network interface is assigned a unique identifier in the form of GUID. This GUID is referenced in several places in the registry, and, as the name indicates, it is unique per interface on every single computer. Fortunately, cumbersome workarounds are no longer necessary. Windows Management Instrumentation provides a number of ways that can be used to both collect information about network configuration and manage its parameters.

WMI provides two main classes that deal with network adapters. The first one, called Win32_NetworkAdapter contains the list of the following properties. This, however, is not an exclusive list as it contains only the ones are relevant for our purposes:

• AdapterType reflects the network medium in use. A typical value for an Ethernet adapter would be Ethernet 802.3.
• AdapterTypeId contains the same information as the AdapterType but in numerical format. Ethernet 802.3 is represented by the number 0.
• AutoSense, True or False, depending on whether the network adapter is capable of network media autosensing. Unfortunately, this property is frequently not set.
• Availability represents the status of the device. Typically it will be equal to 3 (representing full power).
• Caption describes the interface (based on network adapter or port used) preceded by unique numerical value assigned to interface.
• Description is typically the same as Caption (but without the numerical value included only in the caption).
• MACAddress is the MAC address (string of 6 pairs of hex digits separated by semicolons) of the network adapter.
• Manufacturer names the manufacturer of physical or virtual network adapter.
• MaxSpeed is the maximum speed (in bits per second) supported by the network adapter (as with autosense, this value is frequently not set).
• Name is typically set to the same value as Description.
• NetConnectionID is the name for the network interface that appears in the “Network Connections” folder.
• NetConnectionStatus is a number indicating the status of the connection. Of all the values, two are of our interest (0 and 2, representing disconnected and connected, respectively).
• ProductName is typically the same as the Name.
• ServiceName is the service name of the network adapter. This is the name of the key that appears in the registry in the HKLMSYSTEMCurrentControlSetServices node.

Interestingly, the Win32_NetworkAdapter does not contain protocol-related network interface configuration. Information about this configuration, along with methods that allow modifying it, are part of Win32_NetworkAdapterConfiguration class. You might wonder why we bothered with the Win32_NetworkAdapter class at all if all methods required for modifying IP configuration are part of different class. The reason is that Win32_NetworkAdapterConfiguration class properties are typically not sufficient enough to properly identify network interface for which you want to modify network configuration. Instead, it is easier to accomplish this using Win32_NetworkAdapter class.

Fortunately, instances of both classes are linked to each other through so-called association. We will use this association to first identify the target network interface using properties of Win32_NetworkAdapter class and then to configure its IP protocol properties with methods applied to corresponding instances of the Win32_NetworkAdapterConfiguration class. To identify the target network interface, we will use one or more of the properties listed above.

We will start with a script that will query information on configuration of computer network adapters. This will allow you to review values of Win32_NetworkAdapter properties of network interfaces. The script enumerates all instances of Win32_NetworkAdapter class, and, for each, it lists all of the properties and their values (or if the property is empty, it displays the message that the property is not set). If the property is an array, all of its elements are listed. A list of the properties for each instance is separated by a double horizontal line. Before launching the script, set the value of sComputer variable to the name of the target computer for which you want to list the property values.

sComputer 	= "TargetComputer"

sNameSpace	= "root/CIMV2"
sClass		= "Win32_NetworkAdapter"

Set cInstances = GetObject("winmgmts:{impersonationLevel=impersonate}//" & _
		sComputer & "/" & sNameSpace & ":" & sClass).Instances_

For Each oInstance In cInstances
	WScript.Echo String(60,"=")
	For Each oProperty In oInstance.Properties_
		WScript.Echo oProperty.Name 
		If IsArray(oProperty) Then
			For iCount = 0 To UBound(oProperty)
				WScript.Echo vbTab & oProperty.Value(iCount)
			Next
		ElseIf IsNull(oProperty) Then
			Wscript.Echo vbTab & "Property not set"
		Else
			WScript.Echo vbTab & oProperty.Value
		End If
	Next
Next

You can use the same script to lists all instances of Win32_NetworkAdapterConfiguration class (or any class for that matter) by simply changing the value of sClass variable. Better understanding of actual values of proprieties for each class will help you use more efficiently the scripts modifying WINS and DNS configuration, which be presented and further explained in the next article in this series.

Discuss WMI and other Windows 2000 issues in the ServerWatch Discussion Forum.