The Network Object

The WScript.Network object provides access to drive and printer mapping functions, as well as access to network information, such as the current user and domain names. You must explicitly create an instance of the Network object in order to use it.


'Create reference

Dim oNetwork

Set oNetwork = CreateObject("WScript.Network")

When created, you can use the object in your scripts.

Overview

The Network object is designed primarily for use in logon scripts, where you'll need to map both drives and printers. Obviously, it has uses elsewhere, but logon scripts demonstrate its usefulness. The Network object provides three functions.

Working with network drives, including mapping and unmapping them, as well as enumerating them.
Working with network printers, including mapping and unmapping them, as well as enumerating them.
Providing access to the network environment's information, such as the current user and domain names.

NOTE

All of the examples in this section assume that you've created a variable named oNetwork and set it to be a reference to the WScript.Network object.

By the way, if you're in a rush to get to WMI, you should know that it's not the be-all and end-all of scripting. In fact, most of the functionality offered by the Network object, particularly mapping network drives, isn't possible through WMI.

Methods and Properties

The MapNetworkDrive object has several different methods for working with drives and printers, and three properties for obtaining network environment information.

MapNetworkDrive

You'll most often see drives mapped using a simplified version of the MapNetworkDrive method.


'map a drive

oNetwork.MapNetworkDrive "Z:", "\\Server1\public"

However, the method offers other parameters that give you more flexibility and functionality.

Local name. This is a required parameter (such as "Z:") and allows you to specify the local drive name for the new mapping.
Remote name. This is a required parameter (such as "\\server1\public") and allows you to specify the UNC of the shared folder you want to map to.
Update profile. This is an optional parameter and can be either True or False. If True, the user's profile is updated with the new drive mapping. The default is False.
User name. This is an optional parameter and allows you to specify an alternate user name for authenticating to the remote server.
Password. Another optional parameter, allowing you to specify an alternate password for authenticating to the remote server.

An example of the full method might look like this.


oNetwork.MapNetworkDrive "Z:", "\\Server1\public", _

 False, "DonJ", "Pa55word!"

NOTE

It's a very poor security practice to include passwords in a script, because the passwords can be easily read by almost anyone. Only use the parameters for alternate credentials if you plan to use the script for only your own purposes, and if the script is secured so that only you have access to it.

RemoveNetworkDrive

As its name implies, the RemoveNetworkDrive method disconnects a network drive. You must pass one parameter, which is the drive letter to disconnect. Two optional parameters allow you to specify if the drive should be disconnected even if files are in use, and whether the user's profile should be updated to indicate that the drive is no longer mapped. If you set that last parameter to False (which is the default if you omit the parameter), and the user's profile contains the drive mapping, the drive mapping will be restored the next time the user logs on.

Here's what the method looks like in action.


oNetwork.RemoveNetworkDrive "Z:", _

 False, True

This method can generate errors if the drive you try to remove isn't a network drive (if, for example, you try to unmap the C: drive), or if there are files on the network drive opened by the client and you don't specify True for the second parameter.

EnumNetworkDrives

This method allows your script to list information about connected network drives. Here's an example.


Set oDrives = oNetwork.EnumNetworkDrives

For x = 0 to oDrives.Count - 1 Step 2

 WScript.Echo oDrives.Item(x) & ": " & oDrives.Item(x+1)

Next

The EnumNetworkDrives method returns a collection, and the items in the collection are paired. The first item (displayed with WScript.Echo- oDrives.Item(x) in the example) is the drive's name, such as "Z:". The second item (oDrives.Item(x+1)) is the drive's UNC, which is the network location that the drive is connected to.

AddWindowsPrinterConnection

Windows-based printers do not require the use of a printer port; the printers simply show up as icons in the Printers (or Printers & Faxes) folder, and Windows applications can then print to them. Adding a connection to a network printer is as easy as using the AddWindowsPrinterConnection method.


oNetwork.AddWindowsPrinterConnection _

 "\\Server1\LaserJet"

The parameter you provide specifies the UNC for the network printer. For NT-based operating systems, including Windows 2000 and Windows XP, that's all you need to provide. In Windows 9x operating systems, however, you also need to specify the name of the printer driver that supports the printer, and that printer driver must already be installed on the client.


oNetwork.AddWindowsPrinterConnection _

 "\\Server1\LaserJet", "HP LaserJet 5n"

Printer connections made using this method cannot be used by older MS-DOS applications (if you still have any), because MS-DOS applications are designed to print to a local printer port.

AddPrinterConnection

This method is similar to AddWindowsPrinterConnection, except that it captures a local printer port (generally LPT1 or LPT2) and makes the printer available to MS-DOS applications. The syntax is also similar.


oNetwork.AddPrinterConnection _

 "LPT1:", "\\Server1\LaserJet"

It's rare to see this method in use, because so few companies have any old MS-DOS applications that they're using to print. Still, if you need it, it's available.

EnumPrinterConnections

This method works very similarly to the EnumNetworkDrives method described earlier. Here's an example of it in use.


Set oPrinters = oNetwork.EnumPrinterConnections

For x = 0 to oPrinters.Count - 1

 WScript.Echo oPrinters.Item(x) & ": " & oPrinters.Item(x+1)

Next

For MS-DOS printer connections, you'll see the printer's captured port (oPrinters.Item(x)) and the printer's name (oPrinters.Item(x+1)). However, for Windows printer connections, you'll see the printer's local name, which might look like "HP083828288867," instead of a port name. You'll see the printer's UNC for the second item.

SetDefaultPrinter

You can force any connected printer to be the default by using the SetDefaultPrinter method. Simply specify the printer's UNC to make it the default.


oNetwork.SetDefaultPrinter( _

 "\\Server1\LaserJet")

There's no way, however, to discern the current default printer. Therefore, if you change the user's default printer, you won't easily be able to set it back to whatever the user had previously selected as the default.

RemovePrinterConnection

Like removing a network drive, you can remove printer connections. You must specify the printer name to disconnect, and you can specify options to force the disconnect and to update the user's profile. If you don't force a disconnect and the printer is being used by the client, you'll receive an error. Here's how to use the RemovePrinterConnection method.


oNetwork.RemovePrinterConnection _

 "\\server1\LaserJet", True, True

ComputerName, UserDomain, and UserName

These properties expose information about the current network environment.


Dim sComputer, sDomain, sUser

sComputer = oNetwork.ComputerName

sDomain = oNetwork.UserDomain

sUser = oNetwork.UserName

There are some caveats. First, as I'll discuss in more detail in Chapter 29, the UserName and UserDomain properties aren't populated on Windows 9x machines until after the logon process is complete, and scripts can begin executing before that occurs. Also, there's no way to retrieve the domain name of the computer, and if your environment contains multiple domains with trusts, you cannot assume that the user's logon domain is the same as the computer's.

Practical Application

Obviously, the most practical application for the Network object is in logon scripts. Listing 11.1 shows a short logon script example that uses the Network object.

Listing 11.1. Logon.vbs. Using the Network object in a logon script.


dim objNetwork

set objNetwork = WScript.CreateObject("WScript.Network")



' let's display a welcome message

dim strDomain, strUser

strDomain = objNetwork.UserDomain

strUser = objNetwork.UserName

msgbox "Welcome to the " & strDomain & ", " & strUser & "!"



'we'll map the Z: drive to a network location

objNetwork.MapNetworkDrive "Z:", "\\Server\Share"



'let's connect to a network printer - we'll capture LPT2:

objNetwork.AddPrinterConnection "LPT2", "\\Server\Print1"



'connect a second printer without capturing a printer port

objNetwork.AddWindowsPrinterConnection "\\server\print2", _

 "Lexmark Optra S 1650"



'let's make that the default printer

objNetwork.SetDefaultPrinter "\\Server\Print2"

You should be able to easily follow what the script is doing by referring to the method and property descriptions I've provided. This script simply displays a personalized welcome message, maps a network drive, captures a printer port to a network printer, and adds a Windows printer connection as the default printer.

Table of Contents