Utility Spotlight
Scripting Trouble-Free Downloads with BITS
Michael Murgolo
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
| Version |
Description of Features |
| Version 2.5 |
- Added support for certificate-based client authentication for secure HTTP transports and custom HTTP headers.
- Included in the Windows Vista and Windows Server “Longhorn” operating system. A redistributable will be available for the Windows Server 2003, Windows XP, and Windows 2000 SP3 operating systems from the Microsoft Download Center.
- The version of %windir%\System32\QMgr.dll is 6.7.xxxx.xxxx.
|
| Version 2.0 |
- Added support for performing concurrent foreground downloads, using server message block (SMB) paths for remote names, downloading ranges of a file, changing the prefix or complete name of a remote name, and limiting client bandwidth usage.
- Included in Windows XP SP2 and Windows Server 2003 SP1. You can also download BITS 2.0 for Windows Server 2003, Windows XP SP1, Windows XP, Windows 2000 SP4, and Windows 2000 SP3. To download BITS 2.0, go to the Microsoft Download Center and install KB 842773.
- The version of %windir%\System32\QMgr.dll is 6.6.xxxx.xxxx.
|
| Version 1.5 |
- Added upload and upload-reply capability, command-line execution for events, explicit credentials, and support for Windows 2000.
- Included in Windows Server 2003. A redistributable is available for Windows XP and Windows 2000 SP3 from the Microsoft Download Center.
- The version of %windir%\System32\QMgr.dll is 6.5.xxxx.xxxx.
|
| Version 1.2 |
- Same functionality as version 1.0. Contains internal upgrades and improvements.
- Included in Windows XP SP1 and Windows 2000 SP3.
- The version of %windir%\System32\QMgr.dll is 6.2.xxxx.xxxx.
|
| Version 1.0 |
- Initial release. Provides prioritized, throttled, and asynchronous downloads in the background or foreground. The downloads automatically resume after computer restarts and network disconnects.
- Included in Windows XP.
- The version of %windir%\System32\QMgr.dll is 6.0.xxxx.xxxx.
|
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
| Version |
Bitsadmin Source |
| Version 2.0 |
Windows Server 2003 Service Pack 1 32-bit Support Tools
Windows XP Service Pack 2 Support Tools go.microsoft.com/fwlink/?LinkId=68007 |
| Version 1.5 |
Windows Server 2003 Support Tools
Windows Server 2003 CD, Support\Tools folder
|
| Version 1.2 |
Windows XP Service Pack 1 Support Tools
Windows XP Service Pack 1 CD, Support\Tools folder |
|
|
| Version 1.0 |
Windows XP RTM Support Tools
Windows XP RTM CD, Support\Tools folder |
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 http://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
at a command prompt.
.