Utility SpotlightScripting Trouble-Free Downloads with BITS

Michael Murgolo

Download the code for this article: UtilitySpotlight2006_08.exe (158KB)

Many of us in Microsoft Consulting Services spend lots of time downloading large ISO files and virtual machine images from our primary file servers in Redmond, and it’s so frustrating to have those downloads fail when a wireless or remote access connection is dropped. And though tools like Robocopy and Xcopy can be used in restartable mode, they require manual restart after a machine restart. Fortunately, the Background Intelligent Transfer Service (BITS), which is built into Windows® XP, Windows Server™ 2003, and Windows Vista™ can help you easily manage file downloads. Software and update distribution products like Systems Management Server (SMS) 2003, Windows Server Update Services, and Windows Automatic Updates use BITS to transfer updates and software to computers with limited end-user disruption.

BITS is designed to have minimal impact on resources; it transfers files using leftover network bandwidth. So if you’re using 60 percent of your bandwidth for other tasks, BITS will only use up to the remaining 40 percent and no more. Even better, if you get disconnected or need to restart your machine, the file transfer does not have to be restarted; when the network connection is re-established, BITS continues where it left off.

You can download files with BITS using a command-line tool called the BITS Administration Utility (Bitsadmin), which is found in the Windows Support Tools. With Bitsadmin you can achieve "set-and-forget" downloading. In this column I’ll describe how you can use Bitsadmin with a sample VBScript to automate BITS jobs.

BITS and Bitsadmin Versions

How you use Bitsadmin depends on which version of BITS you have installed on your operating system. Figure 1 lists BITS versions and features as well as the location of the downloads.

Figure 1 BITS Features

Bitsadmin is versioned based on the BITS version. Figure 2 shows the version of BITS and the source for the corresponding version of Bitsadmin.

Figure 2 Bitsadmin Versions

If you’re going to use BITS and scripting for your downloading tasks, it’s a good idea to have at least BITS 2.0 installed. BITS 1.5 and later allow an action to be executed after the transfer is complete. BITS 2.0 allows transfers from SMB server shares as well as HTTP transfers, so the source file(s) for a BITS job can be on a file server. BITS 2.0 also includes a new BITS policy setting called Maximum Network Bandwidth, which you access in the Computer Configuration\Administrative Templates\Network\Background Intelligent Transfer Service node of the Group Policy Object Editor. If you have Windows XP Service Pack 2 (SP2), Windows Server 2003 SP1, or later, you have at least BITS 2.0. It is also available as a download for older service packs.

Bitsadmin Commands

Now let’s look at a series of Bitsadmin commands used to create a BITS job, as shown in Figure 3. The example assumes that the client computer is running Windows XP or Windows Server 2003 with BITS 1.5 or higher, and that bitsadmin.exe is located in the %SystemRoot%\system32 folder (generally C:\Windows\system32 by default on a new Windows XP installation).

Figure 3 Bitsadmin Commands

bitsadmin /create myDownloadJob
bitsadmin /addfile myDownloadJob https://www.contoso.com/downloads/test.exe 
    C:\Downloads\Test.exe
bitsadmin /SetNotifyCmdLine myDownloadJob "%SystemRoot%\system32\bitsadmin.exe" 
    "%SystemRoot%\system32\bitsadmin.exe /complete myDownloadJob "
bitsadmin /resume myDownloadJob
 

The Create command creates the BITS job in a suspended state. You add files to the job with the AddFile command. The SetNotifyCmdLine switch lets you define a command to launch when the transfer is finished. In this case it runs the Bitsadmin command to Complete the BITS jobs. (A job must be completed after the transfer is finished.) The Resume command starts the download.

For complete Bitsadmin command syntax, at a command prompt you should type: bitsadmin /?

Sample VBScript

I created a sample VBScript—BITSJob.vbs—to avoid having to create command shell scripts manually with Bitsadmin commands. You can use the script with Bitsadmin.exe to create BITS jobs that will download a URL file, a single UNC shared file, or an entire Universal Naming Convention (UNC) shared folder. (There is no scriptable COM interface to BITS for use in VBScript or other languages, so Bitsadmin is currently the only tool for scripting BITS.)

To use BITSJob.vbs, first make sure your computer has BITS 2.0 or higher. Next, you need bitsadmin.exe. If you are using Windows XP or Windows Server 2003, use the version from the Windows Server 2003 SP1 Support Tools. (The Windows XP SP2 Support Tools version has a known issue that does not allow it to be used correctly with the Windows Script Host WshShell.Exec method to capture StdOut.) Windows Vista already has bitsadmin.exe in the OS. Due to the quirky syntax of the Bitsadmin SetNotifyCmdLine command syntax, the location of bitsadmin.exe must not have any spaces in its path. So for this version of the script, the bitsadmin.exe location is hardcoded to %SystemRoot%\system32. You must copy it there on Windows XP or Windows Server 2003. (It’s already in this location on Windows Vista.)

BITSJob.vbs works in two stages. You use it first to create a CMD file, then the CMD file is used to actually execute the bitsadmin commands. The remote file or folder needs to be available when you run the script or CMD file. The advantage of this is that you can look at the total file count in a remote folder (shown in the CMD file) to see if there are too many files for BITS to handle in one job. Due to limitations of BITS, it is not recommended for jobs with more than 100 files. You can comment out any files you decide not to add to the job. (An optional switch for BITSJobs.vbs lets you execute the CMD file immediately after it is created.) Use bitsadmin’s /list or /info switches to check on the status of your BITS jobs.

BITSJobs.vbs is available at Code Downloads. I’ve included a small CMD file along with the download that shows examples of the BITSJobs.vbs switches. You can also get help by executing

cscript BITSJobs.vbs /?

at a command prompt.

For more on BITS, see Background Intelligent Transfer Service in Windows Server 2003. Also check out technet.microsoft.com and msdn.microsoft.com.

Michael Murgolo is a Senior Infrastructure Consultant for Microsoft Consulting Services. He is focused in the areas of operating systems, deployment, network services, active directory, systems management, automation, and patch management. He is a subject-matter expert in the area of desktop deployment and migration.

© 2008 Microsoft Corporation and CMP Media, LLC. All rights reserved; reproduction in part or in whole without permission is prohibited.