B# .NET Blog

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).