Edit

Download a blob with .NET

  • Article

This article shows how to download a blob using the Azure Storage client library for .NET. You can download blob data to various destinations, including a local file path, stream, or text string. You can also open a blob stream and read from it.

Prerequisites

  • This article assumes you already have a project set up to work with the Azure Blob Storage client library for .NET. To learn about setting up your project, including package installation, adding using directives, and creating an authorized client object, see Get started with Azure Blob Storage and .NET.
  • The authorization mechanism must have permissions to perform a download operation. To learn more, see the authorization guidance for the following REST API operation:

Download a blob

You can use any of the following methods to download a blob:

You can also open a stream to read from a blob. The stream only downloads the blob as the stream is read from. You can use either of the following methods:

Download to a file path

The following example downloads a blob to a local file path. If the specified directory doesn't exist, the code throws a DirectoryNotFoundException. If the file already exists at localFilePath, it's overwritten by default during subsequent downloads.

public static async Task DownloadBlobToFileAsync(
    BlobClient blobClient,
    string localFilePath)
{
    await blobClient.DownloadToAsync(localFilePath);
}

Download to a stream

The following example downloads a blob by creating a Stream object and then downloads to that stream. If the specified directory doesn't exist, the code throws a DirectoryNotFoundException.

public static async Task DownloadBlobToStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

Download to a string

The following example assumes that the blob is a text file, and downloads the blob to a string:

public static async Task DownloadBlobToStringAsync(BlobClient blobClient)
{
    BlobDownloadResult downloadResult = await blobClient.DownloadContentAsync();
    string blobContents = downloadResult.Content.ToString();
}

Download from a stream

The following example downloads a blob by reading from a stream:

public static async Task DownloadBlobFromStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    using (var stream = await blobClient.OpenReadAsync())
    {
        FileStream fileStream = File.OpenWrite(localFilePath);
        await stream.CopyToAsync(fileStream);
    }
}

Download a block blob with configuration options

You can define client library configuration options when downloading a blob. These options can be tuned to improve performance and enhance reliability. The following code examples show how to use BlobDownloadToOptions to define configuration options when calling a download method. Note that the same options are available for BlobDownloadOptions.

Specify data transfer options on download

You can configure the values in StorageTransferOptions to improve performance for data transfer operations. The following code example shows how to set values for StorageTransferOptions and include the options as part of a BlobDownloadToOptions instance. The values provided in this sample aren't intended to be a recommendation. To properly tune these values, you need to consider the specific needs of your app.

public static async Task DownloadBlobWithTransferOptionsAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var transferOptions = new StorageTransferOptions
    {
        // Set the maximum number of parallel transfer workers
        MaximumConcurrency = 2,

        // Set the initial transfer length to 8 MiB
        InitialTransferSize = 8 * 1024 * 1024,

        // Set the maximum length of a transfer to 4 MiB
        MaximumTransferSize = 4 * 1024 * 1024
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferOptions = transferOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

To learn more about tuning data transfer options, see Performance tuning for uploads and downloads.

Specify transfer validation options on download

You can specify transfer validation options to help ensure that data is downloaded properly and hasn't been tampered with during transit. Transfer validation options can be defined at the client level using BlobClientOptions, which applies validation options to all methods called from a BlobClient instance.

You can also override transfer validation options at the method level using BlobDownloadToOptions. The following code example shows how to create a BlobDownloadToOptions object and specify an algorithm for generating a checksum. The checksum is then used by the service to verify data integrity of the downloaded content.

public static async Task DownloadBlobWithChecksumAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var validationOptions = new DownloadTransferValidationOptions
    {
        AutoValidateChecksum = true,
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferValidation = validationOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

The following table shows the available options for the checksum algorithm, as defined by StorageChecksumAlgorithm:

Name Value Description
Auto 0 Recommended. Allows the library to choose an algorithm. Different library versions may choose different algorithms.
None 1 No selected algorithm. Don't calculate or request checksums.
MD5 2 Standard MD5 hash algorithm.
StorageCrc64 3 Azure Storage custom 64-bit CRC.

Resources

To learn more about how to download blobs using the Azure Blob Storage client library for .NET, see the following resources.

REST API operations

The Azure SDK for .NET contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar .NET paradigms. The client library methods for downloading blobs use the following REST API operation:

Code samples

Client library resources

See also