Downloader 3.3.1
dotnet add package Downloader --version 3.3.1
NuGet\Install-Package Downloader -Version 3.3.1
<PackageReference Include="Downloader" Version="3.3.1" />
paket add Downloader --version 3.3.1
#r "nuget: Downloader, 3.3.1"
// Install Downloader as a Cake Addin #addin nuget:?package=Downloader&version=3.3.1 // Install Downloader as a Cake Tool #tool nuget:?package=Downloader&version=3.3.1
Downloader
🚀 Fast, cross-platform, and reliable multipart downloader in .Net
🚀
Downloader is a modern, fluent, asynchronous, and portable library for .NET, built with testability in mind. It supports multipart downloads with real-time asynchronous progress events. The library is compatible with projects targeting .NET Standard 2.1
, .NET 8
, and later versions.
Downloader works on Windows, Linux, and macOS.
Note: Support for older versions of .NET was removed in Downloader
v3.2.0
. From this version onwards, only.Net 8.0
and higher versions are supported.
If you need compatibility with older .NET versions (e.g.,.NET Framework 4.6.1
), use Downloaderv3.1.*
.
For a complete example, see the Downloader.Sample project in this repository.
Sample Console Application
Key Features
- Simple interface for download requests.
- Asynchronous, non-blocking file downloads.
- Supports all file types (e.g., images, videos, PDFs, APKs).
- Cross-platform support for files of any size.
- Real-time progress updates for each download chunk.
- Downloads files in multiple parts (parallel download).
- Resilient to client-side and server-side errors.
- Configurable
ChunkCount
to control download segmentation. - Supports both in-memory and on-disk multipart downloads.
- Parallel saving of chunks directly into the final file (no temporary files).
- Pre-allocates file size before download begins.
- Ability to resume downloads with a saved package object.
- Provides real-time speed and progress data.
- Asynchronous pause and resume functionality.
- Download files with dynamic speed limits.
- Supports downloading to memory streams (without saving to disk).
- Supports large file downloads and live-streaming (e.g., music playback during download).
- Download a specific byte range from a large file.
- Lightweight, fast codebase with no external dependencies.
- Manage RAM usage during downloads.
Installation via NuGet
PM> Install-Package Downloader
Installation via the .NET CLI
dotnet add package Downloader
Usage
Step 1: Create a Custom Configuration
Simple Configuration
var downloadOpt = new DownloadConfiguration()
{
ChunkCount = 8, // Number of file parts, default is 1
ParallelDownload = true // Download parts in parallel (default is false)
};
Complex Configuration
Note: Only include the options you need in your application.
var downloadOpt = new DownloadConfiguration()
{
// usually, hosts support max to 8000 bytes, default value is 8000
BufferBlockSize = 10240,
// file parts to download, the 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,
// release memory buffer after each 50 MB
MaximumMemoryBufferBytes = 1024 * 1024 * 50,
// download parts of the file as parallel or not. The default value is false
ParallelDownload = true,
// number of parallel downloads. The default value is the same as the chunk count
ParallelCount = 4,
// 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 chunks data when download completed with failure, default value is false
ClearPackageOnCompletionWithFailure = true,
// minimum size of chunking to download a file in multiple parts, the default value is 512
MinimumSizeOfChunking = 1024,
// Before starting the download, reserve the storage space of the file as file size, the default value is false
ReserveStorageSpaceBeforeStartingDownload = true,
// Get on demand downloaded data with ReceivedBytes on downloadProgressChanged event
EnableLiveStreaming = false,
// config and customize request headers
RequestConfiguration =
{
Accept = "*/*",
CookieContainer = cookies,
Headers = ["Accept-Encoding: gzip, deflate, br"], // { your custom headers }
KeepAlive = true, // default value is false
ProtocolVersion = HttpVersion.Version11, // default value is HTTP 1.1
// 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
}
}
};
Step 2: Create the Download Service
var downloader = new DownloadService(downloadOpt);
Step 3: Handle Download Events
// Provide `FileName` and `TotalBytesToReceive` at the start of each download
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 errors or
// canceled or download completed successfully.
downloader.DownloadFileCompleted += OnDownloadFileCompleted;
Step 4: Start the Download
string file = @"Your_Path\fileName.zip";
string url = @"https://file-examples.com/fileName.zip";
await downloader.DownloadFileTaskAsync(url, file);
Step 4b: Start the download without file name
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);
Step 4c: Download in MemoryStream
// After download completion, it gets a MemoryStream
Stream destinationStream = await downloader.DownloadFileTaskAsync(url);
How to pause and resume downloads quickly
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();
How to stop and resume downloads other time
The DownloadService
class has a property called Package
that stores each step of the download. To stop 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 cancellation:
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 and start continuing your download. The packages are your snapshot of the download instance. Only the downloaded file 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.
Fluent download builder usage
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 download
Resume 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 quickly
When does the Downloader fail to download in multiple chunks?
Content-Length:
If 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.
Accept-Ranges:
If the server returns 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.
Content-Range:
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.
How to serialize and deserialize the downloader package
What is Serialization?
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 another type of system. This information could be serialized 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 the download to keep downloading data and resuming that every time you want.
You can serialize packages even using memory storage for caching download data which is used MemoryStream
.
JSON Serialization
Serializing the package to JSON
is very simple like this:
var packageJson = JsonConvert.SerializeObject(package);
Deserializing into the new package:
var newPack = JsonConvert.DeserializeObject<DownloadPackage>(packageJson);
For more detail see PackageSerializationTest method
Binary Serialization
To serialize or deserialize the package into a binary file, first, you need to serialize it to JSON and next save it with BinaryWriter.
NOTE: The BinaryFormatter type is dangerous and is not recommended for data processing. Applications should stop using BinaryFormatter as soon as possible, even if they believe the data they're processing to be trustworthy. BinaryFormatter is insecure and can't be made secure. So, BinaryFormatter is deprecated and we can no longer support it. Reference
Instructions for Contributing
Welcome to contribute, feel free to change and open a PullRequest to develop the 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 the information needed to be a world-class contributor!
Git Workflow
The general process for working with Downloader is:
- Fork on GitHub
- Make sure your line endings are correctly configured and fix your line endings!
- Clone your fork locally
- Configure the upstream repo (
git remote add upstream git://github.com/bezzad/downloader
) - Switch to the latest development branch (e.g. vX.Y.Z, using
git checkout vX.Y.Z
) - Create a local branch from that (
git checkout -b myBranch
). - Work on your feature
- Rebase if required
- Push the branch up to GitHub (
git push origin myBranch
) - Send a Pull Request on GitHub - the PR should target (have as a base branch) the latest development branch (eg
vX.Y.Z
) rather thanmaster
.
We accept pull requests from the community. But, you should never work on a clone of the master, and you should never send a pull request from the 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.
You can run tests with the Docker Compose file with the following command:
docker-compose -p downloader up
Or with docker file:
docker build -f ./dockerfile -t downloader-linux .
docker run --name downloader-linux-container -d downloader-linux --env=ASPNETCORE_ENVIRONMENT=Development .
Or run the following command to call docker directly:
docker run --rm -v ${pwd}:/app --env=ASPNETCORE_ENVIRONMENT=Development -w /app/tests mcr.microsoft.com/dotnet/sdk:6.0 dotnet test ../ --logger:trx
License
Licensed under the terms of the MIT License
Contributors
Thanks go to these wonderful people (List made with contrib. rocks):
<a href="https://github.com/bezzad/downloader/graphs/contributors"> <img alt="downloader contributors" src="https://contrib.rocks/image?repo=bezzad/downloader" /> </a>
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.1 is compatible. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.1
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.1)
-
net8.0
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.1)
NuGet packages (10)
Showing the top 5 NuGet packages that depend on Downloader:
Package | Downloads |
---|---|
Wabbajack.Networking.Http
Package Description |
|
SquareMinecraftLauncher.Core
BaiBaoStudio |
|
EasyUpdate
Easy Update 提供简单的自动更新服务。 |
|
Orobouros
A fully-featured and modular online scraper tool. Yes we know the name is spelled wrong. Icon Credit: Hyliian @ DeviantArt |
|
Dove.Avalonia.Extensions.WebView
WebView Extensions for Avalonia. |
GitHub repositories (21)
Showing the top 5 popular GitHub repositories that depend on Downloader:
Repository | Stars |
---|---|
2dust/v2rayN
A GUI client for Windows and Linux, support Xray core and sing-box-core and others
|
|
rocksdanister/lively
Free and open-source software that allows users to set animated desktop wallpapers and screensavers powered by WinUI 3.
|
|
goatcorp/FFXIVQuickLauncher
Custom launcher for FFXIV
|
|
yaobiao131/downkyicore
哔哩下载姬(跨平台版)downkyi,哔哩哔哩网站视频下载工具,支持批量下载,支持8K、HDR、杜比视界,提供工具箱(音视频提取、去水印等)。
|
|
Paving-Base/APK-Installer
An Android Application Installer for Windows
|
Version | Downloads | Last updated | |
---|---|---|---|
3.3.1 | 758 | 11/28/2024 | |
3.3.0 | 1,078 | 11/20/2024 | |
3.2.1 | 4,344 | 10/4/2024 | |
3.2.0 | 1,393 | 9/22/2024 | |
3.1.2 | 19,853 | 6/30/2024 | |
3.1.0-beta | 740 | 1/2/2024 | |
3.0.6 | 82,569 | 6/6/2023 | |
3.0.5 | 393 | 6/3/2023 | |
3.0.4 | 45,670 | 3/11/2023 | |
3.0.3 | 4,545 | 1/29/2023 | |
3.0.2 | 1,121 | 1/7/2023 | |
3.0.1 | 5,278 | 11/2/2022 | |
3.0.0-beta | 193 | 10/12/2022 | |
2.4.1 | 12,130 | 9/21/2022 | |
2.4.0 | 1,062 | 9/16/2022 | |
2.3.9 | 518 | 9/14/2022 | |
2.3.8 | 886 | 9/5/2022 | |
2.3.7 | 1,720 | 8/23/2022 | |
2.3.6 | 644 | 8/20/2022 | |
2.3.5 | 79,312 | 5/6/2022 | |
2.3.4 | 1,217 | 5/3/2022 | |
2.3.3 | 5,447 | 2/23/2022 | |
2.3.2 | 1,482 | 1/24/2022 | |
2.3.1 | 641 | 1/2/2022 | |
2.3.0 | 5,113 | 11/15/2021 | |
2.2.9 | 10,421 | 8/12/2021 | |
2.2.8 | 35,774 | 4/1/2021 | |
2.2.7 | 715 | 3/31/2021 | |
2.2.6 | 3,785 | 3/26/2021 | |
2.2.5 | 1,028 | 3/24/2021 | |
2.2.4 | 683 | 3/19/2021 | |
2.2.3 | 2,872 | 3/1/2021 | |
2.2.2 | 803 | 2/24/2021 | |
2.2.1 | 394 | 2/23/2021 | |
2.2.0 | 422 | 2/22/2021 | |
2.1.4 | 409 | 2/21/2021 | |
2.1.3 | 377 | 2/19/2021 | |
2.1.2 | 553 | 2/14/2021 | |
2.1.1 | 411 | 2/14/2021 | |
2.1.0 | 437 | 2/10/2021 | |
2.0.9 | 466 | 2/4/2021 | |
2.0.8 | 517 | 2/3/2021 | |
2.0.7 | 607 | 1/24/2021 | |
2.0.6 | 445 | 1/13/2021 | |
2.0.5 | 492 | 1/10/2021 | |
2.0.4 | 647 | 1/5/2021 | |
2.0.3 | 444 | 1/2/2021 | |
2.0.1 | 602 | 12/19/2020 | |
2.0.0 | 634 | 12/6/2020 | |
1.9.9 | 705 | 12/1/2020 | |
1.9.8 | 445 | 12/1/2020 | |
1.9.7 | 543 | 11/12/2020 | |
1.9.6 | 486 | 11/11/2020 | |
1.9.5 | 560 | 11/11/2020 | |
1.9.4 | 564 | 10/24/2020 | |
1.9.3 | 487 | 10/19/2020 | |
1.9.2 | 466 | 10/12/2020 | |
1.9.1 | 523 | 9/28/2020 | |
1.9.0 | 556 | 9/27/2020 | |
1.8.0 | 856 | 7/31/2020 | |
1.7.0 | 770 | 7/17/2020 | |
1.6.0 | 538 | 7/14/2020 | |
1.5.0 | 531 | 7/6/2020 | |
1.4.0 | 611 | 7/4/2020 | |
1.3.0 | 962 | 6/21/2020 | |
1.2.1 | 605 | 6/21/2020 | |
1.2.0 | 581 | 6/16/2020 | |
1.1.0 | 565 | 5/29/2020 | |
1.0.9 | 589 | 5/16/2020 | |
1.0.8 | 534 | 5/11/2020 | |
1.0.7 | 575 | 5/3/2020 | |
1.0.6 | 531 | 4/22/2020 | |
1.0.5 | 524 | 4/21/2020 | |
1.0.4 | 558 | 4/16/2020 | |
1.0.3 | 659 | 3/28/2020 | |
1.0.2 | 554 | 3/28/2020 | |
1.0.1 | 1,127 | 3/28/2020 |
* Fixed download file on current path without create directory. issue #174