Saturday, January 22, 2005 7:57 PM bart

Use BITS for your own downloads

BITS stands for Background Intelligent Transfer Service and is designed to perform downloads of large files in the background and to support download resuming. It's intelligent because it can suspend automatically when the network connection is needed for other (foreground) tasks and will automatically resume when the needed resources become available. And, it also can maintain file transfers through network disconnections and computer restarts. In fact everyone knows BITS indirectly, since it's being used by the Windows Update service (you probably know the balloon in the system tray that tells you when an update becomes available and when it has been downloaded). Now, the great news is that you can actually use BITS yourself to perform large downloads (or if you want to take it even further, you can employ BITS in your own applications to perform download jobs). I'll focus in this post on the manual process of getting BITS to work for your own tasks.

  1. To kick off you need to grab the bitsadmin.exe tool from the support tools available on the cd-rom (in my case Windows Server 2003, I assume it's available on the Windows XP cd-rom too). In fact, you just install the Support Tools MSI (suptools.msi) which will add a program group to the start menu. Over there, open up a Support Tools Command Prompt.
  2. The second thing to do is to create a job:

    C:\Program Files\Support Tools>bitsadmin /create myjob
    BITSADMIN version 1.5 [ 5.2.3790.0 ]
    BITS administration utility.
    (C) Copyright 2000-2002 Microsoft Corp.
    Created job {26082B7C-FAC5-4489-BE6C-298E2E1078CD}.
  3. Okay, we have a job right now. Check this by executing bitsadmin /list:

    C:\Program Files\Support Tools>bitsadmin /list
    BITSADMIN version 1.5 [ 5.2.3790.0 ]
    BITS administration utility.
    (C) Copyright 2000-2002 Microsoft Corp.
    {26082B7C-FAC5-4489-BE6C-298E2E1078CD} myjob SUSPENDED 0 / 0 0 / 0
    Listed 1 job(s).


    This indicated that the job is actually empty and does not contain a file to download.
  4. Now it's time to add a file to the job, as follows:

    C:\Program Files\Support Tools>bitsadmin /addfile myjob http://someserver/vdir/file.dat c:\temp\file.dat
    BITSADMIN version 1.5 [ 5.2.3790.0 ]
    BITS administration utility.
    (C) Copyright 2000-2002 Microsoft Corp.
    Added http://someserver/vdir/file.dat -> c:\temp\file.dat to job.
  5. Let's add a notification first that will warn us when the download has completed:

    C:\Program Files\Support Tools>bitsadmin /setnotifycmdline myjob c:\windows\system32\net.exe "send %COMPUTERNAME% Download completed"
    BITSADMIN version 1.5 [ 5.2.3790.0 ]
    BITS administration utility.
    (C) Copyright 2000-2002 Microsoft Corp.
    notification command line set to 'c:\windows\system32\net.exe' 'send PAPAGENO Download completed'.

    Note that you'll need the Messenger service on your pc to execute this demo; it would be better to use another mechanism to show the message since the Messenger service is disabled by default (for security reasons) and it's not recommended to turn it on. However, for the purpose of this demo, I'll assume that the Messenger service on your system is enabled.
  6. When you query the job again, you'll see it's suspended:

    C:\Program Files\Support Tools>bitsadmin /list
    BITSADMIN version 1.5 [ 5.2.3790.0 ]
    BITS administration utility.
    (C) Copyright 2000-2002 Microsoft Corp.
    {26082B7C-FAC5-4489-BE6C-298E2E1078CD} myjob SUSPENDED 0 / 1 0 / UNKNOWN
    Listed 1 job(s).

  7. To start it, we need to resume the job:

    C:\Program Files\Support Tools>bitsadmin /resume myjob
    BITSADMIN version 1.5 [ 5.2.3790.0 ]
    BITS administration utility.
    (C) Copyright 2000-2002 Microsoft Corp.
    Job resumed.
  8. In the system tray, you should see network activity on your network adapter (if the icon of the adapter is visible of course):

    C:\Program Files\Support Tools>bitsadmin /list
    BITSADMIN version 1.5 [ 5.2.3790.0 ]
    BITS administration utility.
    (C) Copyright 2000-2002 Microsoft Corp.
    {26082B7C-FAC5-4489-BE6C-298E2E1078CD} myjob TRANSFERRING 0 / 1 10418497 / 35565576
    Listed 1 job(s).


    The progress of the download can be queried at all times through the bitsadmin tool.
  9. If you want to suspend the job you can use the /suspend parameter, like this:

    C:\Program Files\Support Tools>bitsadmin /suspend myjob
    BITSADMIN version 1.5 [ 5.2.3790.0 ]
    BITS administration utility.
    (C) Copyright 2000-2002 Microsoft Corp.
    Job suspended.

    Don't execute this right now. However, when the download is taking place, the interactive users on the system should not see side effects of this when working with the network. That is, the file transfer will the throttled to limit the used bandwidth. You can actually test this by consuming other network resources (e.g. perform a couple of downloads on the internet using a browser) and monitoring the BITS download state using bitsadmin /list. You can also play with system restarts and disconnections of the network cable.
  10. While the download is taking place, take a look at the target folder. You'll see a file BITA1.tmp (or a similar name, note that it's a hidden file) that contains the download (so far). You'll see that the file is growing while the download is busy. After a while, you'll see the notification popping up, indicating that the download has finished. Query the jobs again:

    C:\Program Files\Support Tools>bitsadmin /list
    BITSADMIN version 1.5 [ 5.2.3790.0 ]
    BITS administration utility.
    (C) Copyright 2000-2002 Microsoft Corp.
    {26082B7C-FAC5-4489-BE6C-298E2E1078CD} myjob TRANSFERRED 1 / 1 35565576 / 35565576
    Listed 1 job(s).

    As you can see, the file has been transferred (one file out of a total of one files + size indications).
  11. Although the transfer has completed, the temporary file is still in the target folder. In order to get the file you need to complete the job:

    C:\Program Files\Support Tools>bitsadmin /complete myjob
    BITSADMIN version 1.5 [ 5.2.3790.0 ]
    BITS administration utility.
    (C) Copyright 2000-2002 Microsoft Corp.
    Job completed.

    Which makes the file available in the target folder.
    The associated job will be deleted as well:

    C:\Program Files\Support Tools>bitsadmin /list
    BITSADMIN version 1.5 [ 5.2.3790.0 ]
    BITS administration utility.
    (C) Copyright 2000-2002 Microsoft Corp.
    Listed 0 job(s).

I'm using this technology quite often right now and have a little C# tool for it (nothing special, just a Windows Forms tool that calls the bitsadmin.exe tool through the System.Diagnostics.Process class, and that allows to display a notification in the system tray when a download has finished).

Update: You can also get a .NET managed code wrapper for BITS on MSDN via this link http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwxp/html/WinXP_BITS.asp. If I find the time to complete my download manager implementation using BITS, I'll post the solution over here (up till now, I'm using the command-line tools to start a download job).

Del.icio.us | Digg It | Technorati | Blinklist | Furl | reddit | DotNetKicks

Filed under: ,

Comments

# re: Use BITS for your own downloads

Sunday, January 23, 2005 3:06 AM by bart

Last year I had the chance to work with BITS as an application building block. It has many advantages over implementing error tolerant downloading yourself. The downloading occurs in an NT service, which is great for multi-user machines. And it usually handles network faults well. But it does have some issues that can make it hard to use correctly.

It supports authentication, but auth failures are treated as transient errors so BITS keeps trying until the error limit is reached. The user/pass should be verified before creating the job. The transient vs hard error states caused me some other problems that I don't fully recall. Note that after a hard error the job and downloaded data is lost.

When downloading large sets of individual files you must decide to have 1 file per job or all files in 1. The files of a job are only available when the entire job completes. But 1 file per job also can be bad because creating a new job gets really slow as the number of existing jobs grows. I am talking about thousands of files here.

The HTTP server must support partial download ranges. No problem, they all do, except for when ASP/PHP pages serve the files. Fortunately it is easy to implement the "Range" request header and "Content-Range" response header in your ASP page. See sections 14.35 and 14.16 of the spec (RFC2616).

As a side note, BITS also is very useful for uploading. Just install the IIS extension, enable a vdir and everything will work in reverse (but only one file per upload job).

On the whole I would warn people to be careful when using BITS as an API. It could save you some time, but you also may spend an unexpected amount of time fighting with little oddities of BITS itself.

# SwitchBL8's gebazel - BITS

Wednesday, January 26, 2005 9:43 AM by TrackBack

SwitchBL8's gebazel - BITS

# re: Use BITS for your own downloads

Friday, February 18, 2005 10:40 AM by bart

A Download Manager using BITS can be found here: http://bits.language.nu/

# re: Use BITS for your own downloads

Monday, February 21, 2005 8:23 PM by bart

i tried to do this thing calling bitsadmin from C# program but I get this output

BITSADMIN version 2.0 [ 6.6.2600.2180 ]
BITS administration utility.
(C) Copyright 2000-2004 Microsoft Corp.

Unable to get console input mode - 0x80070006
The handle is invalid.



Exit Code : -2147024890

# re: Use BITS for your own downloads

Saturday, April 23, 2005 7:29 PM by bart

[QUOTE]
I'm using this technology quite often right now and have a little C# tool for it (nothing special, just a Windows Forms tool that calls the bitsadmin.exe tool through the System.Diagnostics.Process class, and that allows to display a notification in the system tray when a download has finished).
[/QUOTE]

Couls you make available for download your compiled tool?

# re: Use BITS for your own downloads

Saturday, May 07, 2005 12:22 AM by bart

I don't run this url :(

# re: Use BITS for your own downloads - in ASP.NET facing problem

Friday, June 17, 2005 12:27 PM by bart


sub: Is it posible to use this technology in ASP.NET

we need to provoid facility to download the file of large capacity from a ASP.NET browser. So wether it is posible to use BITS in downloadding files through ASP.NET?.

# re: Use BITS for your own downloads

Thursday, July 14, 2005 4:01 AM by bart

Yes, It is possible only by using scripts.

# re: Use BITS for your own downloads

Wednesday, August 24, 2005 4:28 PM by bart

no comments

# re: Use BITS for your own downloads

Thursday, September 01, 2005 5:30 PM by bart

Let me get this straight... If you run "bitsadmin /complete myjob" before the transfer is Completed.. the transfer is aborted??? What???? W H Y ???????!!!!!!

How can I quite simply run one command, or one batch, for instance a logon script, and make BITS download files... And complete the transfer automatically when it's it's done.. "/setnotifycmdline myjob bitsadmin '/complete myjob'" does not work.. It's accepted by bitsadmin, but it does not do anything! Duh!

# re: Use BITS for your own downloads

Tuesday, October 18, 2005 10:20 AM by bart

bitsadmin /setnotifycmdline myjob c:\windows\system32\bitsadmin.exe "bitsadmin /complete myjob"

# re: Use BITS for your own downloads

Wednesday, April 26, 2006 12:13 AM by chadpad

A batch file could be used with this syntax:

bitsadmin /create job1
bitsadmin /addfile job1 http://servername/bitsinbox/filename.zip c:\filename.zip
bitsadmin /resume job1
bitsadmin /setnotifycmdline job1 "C:\Program Files\Support Tools\bitsadmin.exe" "bitsadmin /complete job1"