Downloads

This guide describes how to manage file downloads, track download progress, get the notification on download completion, and so on.

Overview

To manage file downloads, use the IDownloads interface:

IDownloads downloads = engine.Downloads;

Every time the DotNetBrowser needs to download a file, the StartDownloadHandler is used. In this handler, you can decide whether the file should be downloaded or the download request must be canceled.

The code sample below demonstrates how to cancel all download requests:

browser.StartDownloadHandler = 
    new Handler<StartDownloadParameters, StartDownloadResponse>(p =>
    {
        return StartDownloadResponse.Cancel();
    });

By default, all download requests are canceled.

Accepting a download

To change the default behavior and allow to download a file, use the following approach:

browser.StartDownloadHandler = 
    new Handler<StartDownloadParameters, StartDownloadResponse>((p) =>
    {
        return StartDownloadResponse.DownloadTo(Path.Combine(Path.GetTempPath(),
            p.Download.Info.SuggestedFileName));
    });

In the code sample above, we tell the library that the file can be downloaded and saved to a given destination file.

Make sure that Chromium main process has rights to create files in the provided destination directory. If the given directory already has a file with the identical name, then the file will be overridden automatically. We recommend checking the rights and the file existence before accepting the file download.

Controlling a download process

To control the download process, use the IDownload instance which you can obtain from using the StartDownloadHandler.

Pausing a download

To pause the download, use the IDownload.Pause() method:

download.Pause();

Resuming a download

To resume the paused download, use the IDownload.Resume() method:

if (download.IsPaused) {
    download.Resume();
}

Canceling a download

You can cancel the download anytime unless the download is in a terminal state. This includes the successfully completed downloads, canceled downloads, and interrupted downloads that cannot be resumed. To find out whether download is in the terminal state, use the IDownload.State property. To cancel the download, use the IDownload.Cancel() method as shown in the code sample below:

if (download.State != DownloadState.Complete) {
    download.Cancel();
}

Download events

You can track the download progress, get notifications when the download is canceled, paused, interrupted, or complete.

Download Canceled event

To get notifications when the IDownload is canceled, use the Canceled event:

download.Canceled += (s, e) => { };

Download Finished event

To get notifications when the IDownload is finished, use the Finished event:

download.Finished += (s, e) => { };

Download Paused event

To get notifications when the IDownload is paused, use the Paused event:

download.Paused += (s, e) => { };

Download Updated event

To track the download progress, use the Updated event:

download.Updated += (s, e) =>
{
    // Get download progress in percents.
    float progress = e.Progress;
    // The current download speed estimate in bytes/second.
    long currentSpeed = e.CurrentSpeed;
    // The total size of a file in bytes.
    long totalBytes = e.TotalBytes;
    // The number or received (downloaded) bytes.
    long receivedBytes = e.ReceivedBytes;
};

Download Interrupted event

To get notifications when the Download is interrupted for some reason, use the Interrupted event:

download.Interrupted += (s, e) =>
{
    // The interrupt reason such as file access denied, network failed, etc.
    DownloadInterruptionReason reason = e.InterruptionReason;
};
Go Top