Fast and reliable multipart downloader with asynchronous progress events for .NET
Get Started
$ dotnet add package DownloaderReadme
Fast and reliable multipart downloader with asynchronous progress events for .NET
$ dotnet add package Downloader
:rocket: Fast, cross-platform and reliable multipart downloader with .Net Core supporting :rocket:
Downloader is a modern, fluent, asynchronous, testable and portable library for .NET. This is a multipart downloader with asynchronous progress events.
This library can added in your .Net Core v2 and later or .Net Framework v4.5 or later projects.
Downloader is compatible with .NET Standard 2.0 and above, running on Windows, Linux, and macOS, in full .NET Framework or .NET Core.
For a complete example see Downloader.Sample project from this repository.
ChunkCount to define the parts count of the download file.in-memory or in-temp files cache mode.JSON or Binary)PM> Install-Package Downloader
dotnet add package Downloader
var downloadOpt = new DownloadConfiguration()
{
ChunkCount = 8, // file parts to download, default value is 1
OnTheFlyDownload = true, // caching in-memory or not? default values is true
ParallelDownload = true // download parts of file as parallel or not. Default value is false
};Note: Do not use all of the below options in your applications, just add which one you need.
var downloadOpt = new DownloadConfiguration()
{
// usually, hosts support max to 8000 bytes, default values is 8000
BufferBlockSize = 10240,
// file parts to download, default value is 1
ChunkCount = 8,
// download speed limited to 2MB/s, default values is zero or unlimited
MaximumBytesPerSecond = 1024*1024*2,
// the maximum number of times to fail
MaxTryAgainOnFailover = 5,
// caching in-memory or not? default values is true
OnTheFlyDownload = false,
// download parts of file as parallel or not. Default value is false
ParallelDownload = true,
// number of parallel downloads. The default value is the same as the chunk count
ParallelCount = 4,
// Set the temp path for buffering chunk files, the default path is Path.GetTempPath()
TempDirectory = @"C:\temp",
// timeout (millisecond) per stream block reader, default values is 1000
Timeout = 1000,
// set true if you want to download just a specific range of bytes of a large file
RangeDownload = false,
// floor offset of download range of a large file
RangeLow = 0,
// ceiling offset of download range of a large file
RangeHigh = 0,
// clear package temp files when download completed with failure, default value is true
ClearPackageOnCompletionWithFailure = false,
// config and customize request headers
RequestConfiguration =
{
Accept = "*/*",
CookieContainer = cookies,
Headers = new WebHeaderCollection(), // { your custom headers }
KeepAlive = true, // default value is false
ProtocolVersion = HttpVersion.Version11, // default value is HTTP 1.1
UseDefaultCredentials = false,
// your custom user agent or your_app_name/app_version.
UserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
Proxy = new WebProxy() {
Address = new Uri("http://YourProxyServer/proxy.pac"),
UseDefaultCredentials = false,
Credentials = System.Net.CredentialCache.DefaultNetworkCredentials,
BypassProxyOnLocal = true
}
}
};var downloader = new DownloadService(downloadOpt);// Provide `FileName` and `TotalBytesToReceive` at the start of each downloads
downloader.DownloadStarted += OnDownloadStarted;
// Provide any information about chunker downloads,
// like progress percentage per chunk, speed,
// total received bytes and received bytes array to live streaming.
downloader.ChunkDownloadProgressChanged += OnChunkDownloadProgressChanged;
// Provide any information about download progress,
// like progress percentage of sum of chunks, total speed,
// average speed, total received bytes and received bytes array
// to live streaming.
downloader.DownloadProgressChanged += OnDownloadProgressChanged;
// Download completed event that can include occurred errors or
// cancelled or download completed successfully.
downloader.DownloadFileCompleted += OnDownloadFileCompleted;string file = @"Your_Path\fileName.zip";
string url = @"https://file-examples.com/fileName.zip";
await downloader.DownloadFileTaskAsync(url, file);DirectoryInfo path = new DirectoryInfo("Your_Path");
string url = @"https://file-examples.com/fileName.zip";
// download into "Your_Path\fileName.zip"
await downloader.DownloadFileTaskAsync(url, path); // After download completion, it gets a MemoryStream
Stream destinationStream = await downloader.DownloadFileTaskAsync(url); When you want to resume a download quickly after pausing a few seconds. You can call the Pause function of the downloader service. This way, streams stay alive and are only suspended by a locker to be released and resumed whenever you want.
// Pause the download
DownloadService.Pause();
// Resume the download
DownloadService.Resume();The DownloadService class has a property called Package that stores each step of the download. To stopping the download you must call the CancelAsync method. Now, if you want to continue again, you must call the same DownloadFileTaskAsync function with the Package parameter to resume your download. For example:
// At first, keep and store the Package file to resume
// your download from the last download position:
DownloadPackage pack = downloader.Package;Stop or cancel download:
// This function breaks your stream and cancels progress.
downloader.CancelAsync();Resuming download after cancelation:
await downloader.DownloadFileTaskAsync(pack);So that you can even save your large downloads with a very small amount in the Package and after restarting the program, restore it again and start continuing your download. The packages are your snapshot of the download instance. If your download config has OnTheFlyDownload, the downloaded bytes will be stored in the package itself. But otherwise, if you download on temp, only the downloaded temp files' addresses will be included in the package and you can resume it whenever you want.
For more detail see StopResumeDownloadTest method
Note: Sometimes a server does not support downloading in a specific range. That time, we can't resume downloads after canceling. So, the downloader starts from the beginning.
For easy and fluent use of the downloader, you can use the DownloadBuilder class. Consider the following examples:
Simple usage:
await DownloadBuilder.New()
.WithUrl(@"https://host.com/test-file.zip")
.WithDirectory(@"C:\temp")
.Build()
.StartAsync();Complex usage:
IDownload download = DownloadBuilder.New()
.WithUrl(@"https://host.com/test-file.zip")
.WithDirectory(@"C:\temp")
.WithFileName("test-file.zip")
.WithConfiguration(new DownloadConfiguration())
.Build();
download.DownloadProgressChanged += DownloadProgressChanged;
download.DownloadFileCompleted += DownloadFileCompleted;
download.DownloadStarted += DownloadStarted;
download.ChunkDownloadProgressChanged += ChunkDownloadProgressChanged;
await download.StartAsync();
download.Stop(); // cancel current downloadResume the existing download package:
await DownloadBuilder.Build(package).StartAsync();Resume the existing download package with a new configuration:
await DownloadBuilder.Build(package, config).StartAsync();var download = DownloadBuilder.New()
.Build()
.WithUrl(url)
.WithFileLocation(path);
await download.StartAsync();
download.Pause(); // pause current download quickly
download.Resume(); // continue current download quicklyIf your URL server does not provide the file size in the response header (Content-Length).
The Downloader cannot split the file into multiple parts and continues its work with one chunk.
If the server return Accept-Ranges: none in the responses header then that means the server does not support download in range and
the Downloader cannot use multiple chunking and continues its work with one chunk.
At first, the Downloader sends a GET request to the server to fetch the file's size in the range.
If the server does not provide Content-Range in the header then that means the server does not support download in range.
Therefore, the Downloader has to continue its work with one chunk.
Serialization is the process of converting an object's state into information that can be stored for later retrieval or that can be sent to another system. For example, you may have an object that represents a document that you wish to save. This object could be serialized to a stream of binary information and stored as a file on disk. Later the binary data can be retrieved from the file and deserialized into objects that are exact copies of the original information. As a second example, you may have an object containing the details of a transaction that you wish to send to a non-.NET system. This information could be serialised to XML before being transmitted. The receiving system would convert the XML into a format that it could understand.
In this section, we want to show how to serialize download packages to JSON text or Binary, after stopping download to keep download data and resuming that every time you want.
You can serialize packages even using memory storage for caching download data which is used MemoryStream.
To serialize or deserialize the package into a binary file, just you need to a BinaryFormatter of IFormatter and then create a stream to write bytes on that:
DownloadPackage pack = downloader.Package;
IFormatter formatter = new BinaryFormatter();
Stream serializedStream = new MemoryStream();Serializing package:
formatter.Serialize(serializedStream, pack);Deserializing into the new package:
var newPack = formatter.Deserialize(serializedStream) as DownloadPackage;For more detail see PackageSerializationTest method.
Serializing the package to JSON is very simple like this:
var packageJson = JsonConvert.SerializeObject(package);But to deserializing the IStorage Storage property of chunks you need to declare a JsonConverter to override the Read method of JsonConverter. So you should add the below converter to your application:
public class StorageConverter : Newtonsoft.Json.JsonConverter<IStorage>
{
public override void WriteJson(JsonWriter writer, IStorage value, JsonSerializer serializer)
{
throw new NotImplementedException();
}
public override IStorage ReadJson(JsonReader reader, Type objectType, IStorage existingValue, bool hasExistingValue, JsonSerializer serializer)
{
if (reader.TokenType == JsonToken.Null)
return null;
var obj = JObject.Load(reader); // Throws an exception if the current token is not an object.
if (obj.ContainsKey(nameof(FileStorage.FileName)))
{
var filename = obj[nameof(FileStorage.FileName)]?.Value<string>();
return new FileStorage(filename);
}
if (obj.ContainsKey(nameof(MemoryStorage.Data)))
{
var data = obj[nameof(MemoryStorage.Data)]?.Value<string>();
return new MemoryStorage() { Data = data };
}
return null;
}
}Then you can deserialize your packages from JSON:
var settings = new Newtonsoft.Json.JsonSerializerSettings();
settings.Converters.Add(new StorageConverter());
var newPack = Newtonsoft.Json.JsonConvert.DeserializeObject<DownloadPackage>(serializedJson, settings);For more detail see PackageSerializationTest method
Welcome to contribute, feel free to change and open a PullRequest to develop branch. You can use either the latest version of Visual Studio or Visual Studio Code and .NET CLI for Windows, Mac and Linux.
For GitHub workflow, check out our Git workflow below this paragraph. We are following the excellent GitHub Flow process, and would like to make sure you have all of the information needed to be a world-class contributor!
The general process for working with Downloader is:
git remote add upstream git://github.com/bezzad/downloader)git checkout vX.Y.Z)git checkout -b myBranch).git push origin myBranch)vX.Y.Z) rather than master.We accept pull requests from the community. But, you should never work on a clone of master, and you should never send a pull request from master - always from a branch. Please be sure to branch from the head of the latest vX.Y.Z develop branch (rather than master) when developing contributions.
Licensed under the terms of the MIT License
Thanks go to these wonderful people (List made with contrib.rocks):