Monthly Archives: May 2008

When it comes to large file downloads one should use a download manager which at least is able to resume broken downloads. Windows has a built-in download manager service called Background Intelligent Transfer Service(BITS). Some of us at Login Consultants (including me) prefer to script large file downloads with the Microsoft’s BITS Admin Utility – Bitsadmin. This article explains how to use Bitsadmin to download a file.

The BITS service is built into Windows XP, Vista, Server 2003, and Server 2008. For example the Windows Automatic Update, WSUS 3.0, or Microsoft SCCM 2007 depend on BITS to transfer files like Windows Updates and software packages. For one thing BITS has been designed for robustness over slow or unstable network connections, and for another thing BITS is a background process that economizes on bandwidth usage. If a download does not complete due to a network problem or restart of your machine, BITS will automatically try to continue the download from where it left off, and repeat this until the whole file has been retrieved. BITS file transfers can be invoked and managed from the command line with the Bitsadmin utility which is part of the Windows Support Tools.

Please note that this article applies to Bitsadmin 3.0 and the version of BITS that is included in Windows Vista SP1.

In order to download a file with Bitsadmin, respectively BITS, you need to type a series of Bitsadmin commands to create a download job, to add the file the the job, eventually to set credentials and proxy settings, and finally to start the download job. Bitsadmin has many command line switches, for this see also Bitsadmin’s help by typing “bitsadmin” at the command prompt. For our purposes we need the switches CREATE, ADDFILE, SETNOTIFYCMDLINE, COMPLETE, SETCREDENTIALS (maybe), and RESUME.

First of all, we need to create a new download job with Bitsadmin /CREATE

MS DOS

1

2

setbits_job=%random%

bitsadmin/create%bits_job%

Bitsadmin will confirm job creation by echoing the job GUID like “Created job {58C6770A-AB4E-477C-8944-33246EC8791E}”. For now, the job is created and its state is suspended. (Therefore, we will need to resume the job later in order to start the download process.)

2. Add File

Now we can add the file to the job with Bitsadmin /ADDFILE. We need to specify the job name, the download URL, and the file’s local name.

MS DOS

1

bitsadmin.exe/addfile%bitsjob%...aikl_en.isoC:\Downloads\aik_en.iso

Again, Bitsadmin will confirm the action. (Hint: if you want to add multiple files to a job take a look at Bitsadmin’s switch /ADDFILESET which reads each file’s remote URL and local name from a text file.)

3. Optional Settings

The job is still in suspended state, and we are almost ready to start the download. But to start with we should pay attention to three important and useful Bitsadmin switches: COMPLETE, SETNOTIFYCMDLINE, and SETCREDENTIALS

By default, Bitsadmin doesn’t tell anything about a finished file transfer. Even worse, though BITS may have downloaded a file completely you won’t find it unless you have completed the job explicitly. To kill two birds with one stone we will use Bitsadmin /SETNOTIFYCMDLINE to launch Bitsadmin /COMPLETE as loon as the transfer is finished. (Virtually, SETNOTIFYCMDLINE enables you to set a command line to execute for notification when the file download is finished.)

Maybe the file is located on a password protected web server. In this case you can add credentials to a job using Bitsadmin /SETCREDENTIALS. This time you have to go without an example. Please refer to Bitsadmin’s syntax help by typing “bitsadmin” at the command line.

4. Start/Resume Download

Finally, we are ready to resume the download job with Bitsadmin /RESUME:

MS DOS

1

bitsadmin/resume%bitsjob%

Now, BITS is downloading the file in the background. Since we have defined the launch of an according job completion command on transfer completion we can just wait and see… or check out some Bitsadmin command lines:

5. Monitor or Cancel Job

How to display information about the BITS job?

PowerShell

1

bitsadmin/info%bitsjob%

How to retrieve the size of the BITS job?

PowerShell

1

bitsadmin/getbytestotal%bitsjob%

How to retrieve the number of bytes transferred?

MS DOS

1

bitsadmin/getbytestransferred%bitsjob%

How to monitor the BITS copy manager?

MS DOS

1

bitsadmin/monitor

How to cancel the BITS job?

MS DOS

1

bitsadmin/cancel%bitsjob%

How to delete all BITS jobs?

MS DOS

1

bitsadmin/reset

6. Write a Shell Script

The batch file below, Bits-Download.cmd, simplifies the usage of Bitsadmin:

Bits-Download.cmd

MS DOS

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

@ECHO OFF

:: NAME

:: Bits-Download.cmd

::

:: SYNOPSIS

:: Downloads a remote file with BITS.

::

:: SYNTAX

:: Bits-Download remote_url local_name

::

:: DETAILED DESCRIPTION

:: The Bits-Download.cmd batch file uses BITS to download

:: the given remote file. Bits-Download.cmd requires the

:: BITS Admin Utility Bitsadmin.exe.

::

:: NOTES

:: Bits-Download.cmd was developed and tested on Windows Vista.

::

:: AUTHOR

:: Frank-Peter Schultze

::

:: DATE

:: 00:18 21.07.2008

SETLOCAL

IF"%2"==""(

TYPE"%~f0"|findstr.exe/R"^::"

GOTO:END

)

SETbits_job=bits%RANDOM%

SETremote_url="%~1"

IFNOTDEFINEDremote_url(

ECHO %~n0 : Cannot bind argument to parameter 'remote_url' because it is empty.

GOTO:END

)

SETlocal_name="%~2"

IFNOTDEFINEDlocal_name(

ECHO %~n0 : Cannot bind argument to parameter 'local_name' because it is empty.