SharpBITS.NET - A Wrapper for the BITS API

Sharpbits.NET - Winforms application based on the wrapper library

Introduction

SharpBITS is a library to wrap the BITS SDK for use with managed code on the .NET platform. It was intended and first implemented for a project designed to transfer large files over a slow and unstable WAN link. While there are some other options like use of FTP, BITS had some real advantages that made it the favorite selection.

As it uses the HTTP/HTTPS protocol to transfer files, it is immune to firewall restrictions. Also, it keeps a session (in default setting) for up to 14 days, which gives a reliable file transfer option in this case! The project where SharpBITS was developed consists of a small command line application, and the separate BITS wrapper library. Even if there are some custom implementations for the BITS wrapper available already, also for .NET managed code (see "Wrapping Bits" on MSDN), they are based on older versions of BITS and don't support some features like authentication, so the decision was to have a new C# based wrapper library.

Background

Background Intelligent Transfer Service (BITS) can be used to transfer (large) files asynchronously between a client and a server. Background transfers are optimal in that BITS uses idle network bandwidth to transfer the files, and can increase or decrease the rate at which files are transferred based on the amount of idle network bandwidth available. If a network application begins to consume more bandwidth, BITS decreases its transfer rate to preserve the user's interactive experience. BITS continues to transfer files after an application exits if the user who initiated the transfer remains logged on and a network connection is maintained. BITS suspends the transfer if a connection is lost or if the user logs off. BITS persists transfer information while the user is logged off, across network disconnects, and during computer restarts.

The complete description and documentation on BITS can be found on MSDN.

Requirements

For using BITS, the following requirements must be met:

Client

On the client side, Windows 2000 SP3 or later is required and the BITS service must be running. BITS is also supported on Windows Vista and Longhorn Server (with upcoming new features like P2P-functionality).

Windows 95/98/ME/NT are not supported.

Server

For uploads, BITS requires IIS 5.0 on Windows 2000 Server, and IIS 6.0 on Windows Server 2003 family; BITS does not support IIS 5.1 on Windows XP.

Using the code

All you have to do for getting started with SharpBITS is to create an instance of BitsManager. BitsManager is the single instance giving access to create a new job or list existing jobs.

To create a new job, the code looks as simple as that:

BitsManager manager = new BitsManager();
manager.EnumJobs(JobOwner.CurrentUser);

// populate current job list first
BitsJob job = manager.CreateJob("TestJob", JobType.Download);
job.AddFile("http://localhost/bits/mydownload.cab", "C:\\temp\\download.cab");
job.Resume();

Also, it is very simple to iterate through all existing jobs and list their properties. Each job has various properties like name, owner, priority, and of course, a list of files to transfer. (While a download job can have multiple files to transfer, an upload job is restricted to one file per job!)

manager.EnumJobs(JobOwner.CurrentUser);     
// list either all jobs or for current user only
System.Console.WriteLine("Job Count for current user: {0}", 
                manager.Jobs.Count.ToString());
foreach (BitsJob job in manager.Jobs.Values)
{
    System.Console.WriteLine("Displayname for job: {0}", job.DisplayName);
    System.Console.WriteLine("Owner: {0}", job.Owner);
    System.Console.WriteLine("Priority: {0}", job.Priority.ToString());
    job.EnumFiles();
    System.Console.WriteLine("File Count for current job: {0}", 
                    job.Files.Count.ToString());
    foreach (BitsFile file in job.Files)
    {
        System.Console.WriteLine("Local File Name: {0}", file.LocalName);
        System.Console.WriteLine("Remote File Name: {0}", file.RemoteName);
        System.Console.WriteLine("Bytes total: {0}", 
            file.Progress.BytesTotal.ToString());
        System.Console.WriteLine("Bytes transfered: {0}", 
            file.Progress.BytesTransferred.ToString());
    }
    System.Console.WriteLine("Job State: {0}", job.State.ToString());
    System.Console.WriteLine("Job Type: {0}", job.JobType.ToString());
}

Instead of polling for the status of a job all the time, BITS enables to set a callback pointer for the notification interface. In SharpBITS, this callback handling is wrapped to .NET events. There are three different kinds of events, raised if job is modified, completed, or if an error has occurred. The JobModifiedEvent event will also be fired if the JobProgress or FileProgress for a job is updated, so this can be used to display a job progress.

Event handlers can be attached to either a job to get events for that particular job only, or to the BitsManager to catch all events. Even for those, you have to set the kind of events fired for each particular job.

//Set flags to get notified on Job Completed or Job Error event
job.NotificationFlags = 
    NotificationFlags.JobTransferred | NotificationFlags.JobErrorOccured;
//never raised with the previous flags
job.OnJobModifiedEvent += 
    new EventHandler<JOBNOTIFICATIONEVENTARGS>(job_OnJobModifiedEvent);

Credits

The interop handling in this library is based on some implementations from the "Microsoft Updater Application Block for .NET" (http://msdn2.microsoft.com/en-us/library/ms978574.aspx), which is part of the Enterprise Library.

Conclusion

As it seems, BITS can be used to fulfill various requirements for transferring files in a reliable manner, and is somewhat underestimated currently. I started to develop a Windows Forms application also (where the above screenshot was taken from). This application development is still in progress, but a running version and more details (source code as well) can be found on the SharpBITS.NET homepage.