Enterprise Software

Build Your Skills: NETSH scripts add network functionality to batch files

Use NETSH scripts to manage a Windows information network

Though some may argue the point, there are times when the easiest or most efficient way to get a task done is to create a batch file. Today's batch files are capable of much more than was possible in the days of DOS. One of Windows’ most powerful batch file utilities is a command called NETSH. NETSH lets you integrate network functionality into your batch files. In this Daily Drill Down, I’ll explain NETSH and show you how to incorporate NETSH scripts into your batch files.

What's NETSH?
NETSH is a command line scripting utility designed to give you access to many high-level network functions via a batch file. You can use NETSH to either display or modify a range of network configuration information. Furthermore, you can display or modify information locally or on a remote computer.

The NETSH command exists in Windows 2000, Windows XP, and Windows .NET. On the surface, the command syntax and the various NETSH features appear to be identical in all three versions of Windows, but there are minor inconsistencies between the different operating systems. For the purposes of this Daily Drill Down, I’ll be using the version of NETSH that comes with Windows .NET.

NETSH is actually a scripting shell. Commands can be sent to the NETSH interpreter either from inside of the NETSH shell or from outside of the shell. Sending NETSH commands from outside of the shell is appropriate in situations in which only a single command is being entered, or in situations in which multiple commands are being entered, but each command is completely independent of the other commands being entered and requires no knowledge of the other commands or their results.

Issuing commands from outside the NETSH shell is known as command mode. Batch mode involves issuing commands from inside the NETSH shell. Batch mode is appropriate in situations in which multiple commands need to be issued, especially when a command depends on the results of a prior command.

Command mode vs. batch mode
Command mode is intended for single commands or for multiple commands that don’t require any knowledge of each other. For example, if you need a script or batch file to simply display a piece of information by issuing a command to a context, there’s no reason that you couldn’t use command mode. However, if you need the script to act on the information that was displayed, you must use batch mode. Commands to reconfigure a network component can be issued through command mode, but the commands have no way of knowing what the rest of the script has already done unless they are issued through batch mode.

Entering a command in command mode is as simple as entering the NETSH command, followed by the context name (or context names if nested contexts are being used) and the actual command. For example, if you wanted to display the DHCP server configuration information in command mode, you’d use the command NETSH DHCP SHOW SERVER. In this command, NETSH loads the NETSH shell and the DHCP portion of the command loads the DHCP context. The SHOW SERVER portion is the actual command that’s being sent to the context. Once the command has completed, the system promptly unloads the context and the NETSH shell. Because the NETSH shell is no longer in memory, other commands can’t reference the command that has just executed.

Working with the NETSH command in batch mode is a little more complicated. In batch mode, all commands are executed from within a NETSH shell. You can interact with NETSH in batch mode either manually or with a script. Interacting with NETSH manually simply involves entering the NETSH command at the command prompt to load the NETSH shell. Once the shell has been loaded, you’re essentially in batch mode and may load contexts and issue commands at will. To close the NETSH shell, simply enter the EXIT command.

Suppose for a moment that you wanted to create a script that displayed the DHCP configuration information. Earlier I showed you that you could do so in command mode by simply entering the NETSH DHCP SHOW SERVER command. In command mode, you could enter this command manually or as a line in a batch file. The system doesn’t care which you use. However, if you wanted to enter the same command in batch mode, there’s a little more work to go through.

At first, it might seem like you could create a batch file that contains the NETSH command, followed by the DHCP command and the SHOW SERVER command, all on separate lines of the file. Unfortunately, NETSH doesn’t work this way. When you execute the batch file, the first line of the file would load the NETSH shell. However, the NETSH shell has no way of knowing that it was called from a batch file (remember command mode?) and, therefore, none of the remaining commands are processed.

The right way to get the job done actually involves creating two different scripts. The first script would be the script containing all of the NETSH commands. In this case, the script would contain the commands DHCP and SHOW SERVER. The other script would be a batch file that calls NETSH in command mode. However, the way that the NETSH command is entered forces NETSH to switch from command mode to batch mode.

In this particular case, the batch file would call the NETSH shell but use the EXEC command and the name of the batch-mode script as parameters. For example, if you saved the batch-mode script as TEST.TXT, then the line in the batch file that runs the script would be NETSH EXEC TEST.TXT. When you execute the batch file, the command interpreter would read the line, load the NETSH shell, switch to batch mode, load the script TEST.TXT, execute the script, and then return to the command prompt (or to the next line in the batch file) when the script completed.

Loading a context
A context refers to a module loaded by the NETSH shell. Earlier, I explained that the NETSH scripting tool is a shell with a built-in command interpreter. However, the NETSH shell itself contains only a very general set of commands. The only way that NETSH can interact with a network on a higher level is to load external modules. These external modules are called contexts.

A context is actually nothing more than a DLL file. The DLL file (sometimes referred to as a helper DLL) bridges the gap between the NETSH shell and the operating system’s network functionality by supplying the NETSH shell with a set of commands that are specific to a particular aspect of networking.

For example, suppose that you needed to interact with a DHCP server. By itself, NETSH knows very little about DHCP servers. However, if you load the DHCP context, all kinds of DHCP-related commands are suddenly available to you. Contexts are independent NETSH modules, and it’s possible to have nested contexts. A nested context is a context inside of another context.

The operating system has only a few built-in contexts, but some of the contexts contain other contexts. The built-in root level contexts include DHCP, DIAG, INTERFACE, IPSEC, RAS, ROUTING, RPC, and WINS. You can select a context merely by entering its name. Of course the actual syntax would depend on whether you were running in command mode or batch mode. For example, suppose that you wanted to load the RAS context. If you were in command mode, you’d enter NETSH RAS. If you were in batch mode, you’d simply enter RAS.

Each context is designed to provide support for a very specific area. Therefore, it’s quite common to run into situations where it’s necessary to use multiple contexts to get the job done. However, there's no switch context command. Switching contexts tends to be a little more involved. The method that you’ll use also depends on whether you’re working with nested contexts or not.

Nested contexts
Let’s take a closer look at nested contexts, or contexts within a context. A good example of this is the RAS context, which contains an IP context, an IPX context, and an AppleTalk context, among others.

Working with nested contexts is fairly simple. For example, suppose you've just loaded the RAS context via the RAS command at the NETSH prompt. If you wanted to load the IPX context, you could simply enter the IPX command.

Remember, the IPX context is a part of the RAS context, and therefore, the RAS context is aware of the IPX command. You couldn’t just enter the IPX command directly at the NETSH prompt and expect the NETSH shell to load the RAS IPX context, because the NETSH shell has no idea what the IPX context is. You could enter RAS IPX at the NETSH prompt though, and the NETSH shell would load the IPX context.

Switching contexts
Now, suppose that you were in the IPX context and needed to switch to a different context. How would you get the job done? Well, it depends. If you needed to switch to another RAS subcontext, you could just enter the context name. For example, if you needed to switch to the IP context, you could just enter the IP command. Remember that even though you’re in the IPX context, you’re still in the RAS context as well, and the RAS context knows about the IP command. Suppose, however, that you needed to switch to something completely unrelated, such as the DHCP context. What then?

Unfortunately, there’s no direct way to switch to a completely foreign context once you’ve entered another context. This is where the NETSH shell program comes in. The NETSH shell does more than just load contexts. It also provides a small set of commands that you can use to interact with the contexts from outside of a context.

To switch root-level contexts, you need to build a stack. You can add items to the stack by using the PUSHD command, and you can remove items from the stack by using the POPD command. The stack loads commands in a last-in-first-out manner, much like piling up magazines to read. To see how these commands work together, let’s return to the previous example, switching from the RAS context to the DHCP context.

Normally, when you switch to a context, you simply enter the name of the context. However, if you were building a stack along the way, you would precede the name of the context with the PUSHD command. For example, if you were at the NETSH prompt and wanted to go to the RAS context, you’d enter the PUSHD RAS command rather than just entering the RAS command. This command would switch you to the RAS context, but, more importantly, it would also add the RAS context to a stack. Now, suppose that you wanted to switch from the RAS context to the DHCP context.

To do so, you’d enter the POPD command. This would remove the RAS command from the stack, thus returning you to the NETSH root. You’d then be free to enter either the DHCP command or the PUSHD DHCP command, depending on whether or not you were going to need to change contexts again.

As you use PUSHD and POPD, it’s important to remember that POPD doesn’t automatically move you to the NETSH root. It moves you to the most recent location on the stack. Therefore, if you entered the PUSHD RAS, PUSHD IP, POPD commands, you’d end up not at the NETSH root but at the RAS context, because POPD removed the most recent addition to the stack, which was IP.

NETSH in a nutshell
The NETSH shell is a valuable interface for building network functionality into your batch files. As with most command line utilities, NETSH can be a little cumbersome and confusing at first, but once you get the hang of it, you’ll find it to be a much more efficient way to analyze your network.


Editor's Picks

Free Newsletters, In your Inbox