Using Win32_NetworkAdapterConfiguration -- Managing Windows networks using scripts, part 4

This article originally appeared on WindowsNetworking.com.

In the first two articles of this series we examined the basics of using Windows scripting to manage TCP/IP networking settings. In particular, we developed the following simple script to change the IP address of a network adapter:

Option Explicit
On Error Resume Next

Read other 'Managing Windows networks using scripts' tips Part 1: The basics Part 2: Cleaning up Part 3: Understanding WMI Part 4: Using Win32_NetworkAdapterConfiguration Part 5: Getting over the hump Part 6: Remote scripting first steps Part 7: Troubleshooting the mystery error Part 8: Troubleshooting Remote Scripting using Network Monitor 3.0

This above script changes the IP address of a network adapter by using Win32_NetworkAdapterConfiguration, which is one of the most useful WMI classes for managing TCP/IP networking configuration of Windows-based systems. In our third article we took a brief detour into "WMI Land" to learn more about WMI namespaces, providers and classes so we could better understand the following cryptic line that lies at the heart of this script:

Set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")

If you recall, what this line does is to connect you to the root\cimv2 namespace on the local computer by defining an object named objWMIService and setting it equal to the handle returned by the GetObject method. And of course, once you're connected to this namespace, you can collect information from it.

In today's article, however, the line we want to focus on is the line that follows this one in our script and which makes use of the Win32_NetworkAdapterConfiguration class:

Set colNetAdapters = objWMIService.ExecQuery("Select * from
Win32_NetworkAdapterConfiguration where IPEnabled=TRUE")

If you recall again, what this second line does is call the ExecQuery method for the objWMIService object which we instantiated in the first line. A SELECT statement is passed to this method as an argument, and the collection of all network adapter configurations on the system that have TCP/IP bound and enabled on the adapter is returned and is assigned to the variable colNetAdapters. Once we have this collection, we can loop through it using a For Each…Next loop. Remember that you always have to loop through collections even if they have only one object in them.

The question we want to pose today is this: What else can we do with the Win32_NetworkAdapterConfiguration class?

Using properties and methods of Win32_NetworkAdapterConfiguration

Recall that properties represent information you can retrieve from a system using WMI. The more properties a WMI class has, the more information you can get out of it. It turns out that the Win32_NetworkAdapterConfiguration class actually has 61 different properties, some of them unique and others inherited from other classes. You can find a complete list of properties for the Win32_NetworkAdapterConfiguration class on MSDN. When you're trying to learn how to do WMI scripting so you can manage Windows networks using scripts, it's important to become familiar with WMI information like this on MSDN, and Figure 1 below shows some of the properties of this class as listed on this page:

In the figure above I've clicked on the link for the boolean property IPEnabled, which we used in our script to identify all network adapters on our system that have TCP/IP bound and enabled on them. We did this by passing the following SQL query as an argument to the objWMIService.ExecQuery method:

Select * from Win32_NetworkAdapterConfiguration where IPEnabled=TRUE

Right away we can see how we can extend the functionality of our script by querying for other properties of this class. For example, if we wanted to select all network adapters on our system that have DHCP enabled on them, we simply need to change our SELECT statement to this:

Select * from Win32_NetworkAdapterConfiguration where DHCPEnabled=TRUE

How do we know this? Because this information can be found on the same MSDN page as shown in Figure 2:

What about the methods for this class? Recall that methods are things you call so you can perform different actions using WMI. It turns out that Win32_NetworkAdapterConfiguraiton has lots of methods too, in fact 41 methods in all. You can find the methods for this class listed on the same page below the properties, as shown in Figure 3:

Let's go back for a moment to the following key section of our script:

Set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")
Set colNetAdapters = objWMIService.ExecQuery("Select * from
Win32_NetworkAdapterConfiguration where IPEnabled=TRUE")
For Each objNetAdapter in colNetAdapters
    errEnableStatic = objNetAdapter.EnableStatic(arrIPAddress, arrSubnetMask)
Next

First we used the IPEnabled property of the Win32_NetworkAdapterConfiguration class to return the collection network adapters that have TCP/IP bound and enabled on them. Then we called the EnableStatic method of this same class to change the IP address and subnet mask of these network adapters using the array variables arrIPAddress and arrSubnetMask, which were defined previously in our script. How did we know we had to pass two variables as arguments for this method? Well, by clicking on the EnableStatic link in Figure 3 above, the MSDN page shown in Figure 4 is displayed, which gives us information on how to use this class:

Note that not only does this MSDN page give us the syntax of how to call this class, it also gives us the return value and how to interpret different error conditions that could arise. That's why we used the error variable in the following line of our script:

errEnableStatic = objNetAdapter.EnableStatic(arrIPAddress, arrSubnetMask)

And it's also why we included the following lines in our script to report the error code should an error condition arise when our script is run:

If errEnableStatic=0 Then
    Wscript.Echo "Adapter's IP address has been successfully changed to " & strAddress
Else
    Wscript.Echo "Changing the adapter's address was not successful. Error code " & errEnableStatic
End If

Once again, we can see how we can extend the functionality of our script, this time by calling other methods of this class. For example, let's say we wanted to disable NetBIOS over TCP/IP (NetBT) on all our network adapters that have TCP/IP bound and enabled on them. After skimming through the MSDN page for the Win32_NetworkAdapterClass page, we find a method called SetTcpNetbios that seems to fit the bill for this (see Figure 5):

Clicking on the link for this method opens a page with information on how to use it (Figure 6):

We can see that if we want to disable NetBT on our adapters, all we need to do is change the following line in our script:

   errEnableStatic = objNetAdapter.EnableStatic(arrIPAddress, arrSubnetMask)

to this:

    errEnableStatic = objNetAdapter.SetTcpipNetbios(2)

After making this change and cleaning up our script by removing variables that are no longer needed and renaming others, we now have the following script that can be used to disable NetBT on all network adapters that have TCP/IP bound and enabled on them:

'=========================
' NAME: DisableNetbios.vbs
'
'AUTHOR: Mitch Tulloch
'DATE: December 2006
'
'ARGUMENTS:
'1. None
'=========================-

Let's see if it works. Figure 7 shows the WINS tab of the Advanced TCP/IP Properties for Local Area Connection on a Windows Server 2003 machine:

Note that the current NetBT setting for this machine is "Default," which corresponds to a value of 0 for the SetTcpipNetbios method (see Figure 6 previously). Let's copy our new script to Notepad (make sure Word Wrap is turned off) and save it as DisableNetbios.vbs. Then we'll run it on our server in a command prompt window using cscript (Figure 8):

Now let's see if it worked. We need to close our TCP/IP properties pages and re-open them to refresh the NetBT setting in the GUI, which now looks like this (Figure 9):

Conclusion

The best way to learn Windows scripting is by actually trying it out, so here are a couple of exercises you can try on your own to reinforce what you've learned in this article:

1. Modify the script so it can take arguments i.e. type DisableNetbios.vbs 1 to enable NetBT, DisableNetbios.vbs 2 to disable it, and DisableNetbios.vbs 0 to return it to its default setting of using DHCP to determine whether NetBT is enabled or disabled for the adapter.
2. Modify the SELECT statement in the script to select network adapters based on some other property of the Win32_NetworkAdapterConfiguration class, and modify it further to call some different method of this class to perform some other action on the TCP/IP configuration of the network adapters.
3. Browse MSDN to learn about other WMI classes that look like they might be useful to you for scripting different Windows administration tasks.

About the author:
Mitch Tulloch is a writer, trainer and consultant specializing in Windows server operating systems, IIS administration, network troubleshooting, and security. He is the author of 15 books including the Microsoft Encyclopedia of Networking (Microsoft Press), the Microsoft Encyclopedia of Security (Microsoft Press), Windows Server Hacks (O'Reilly), Windows Server 2003 in a Nutshell (O'Reilly), Windows 2000 Administration in a Nutshell (O'Reilly), and IIS 6 Administration (Osborne/McGraw-Hill). Mitch is based in Winnipeg, Canada, and you can find more information about his books at his Web site: www.mtit.com.

WindowsNetworking.com contains a wealth of networking information for administrators: Featuring information on how to setup and troubleshoot various networks of any size. Also includes a comprehensive archive of hundreds of reviewed networking software and hardware solutions. Frequently updated with articles and tips by a team of leading authors, it remains a favorite within the networking community.