Quickstart: Azure Blob Storage client library for .NET

Article
09/19/2024

Get started with the Azure Blob Storage client library for .NET. Azure Blob Storage is Azure's object storage solution for the cloud, and is optimized for storing massive amounts of unstructured data.

API reference documentation | Library source code | Package (NuGet) | Samples

Prerequisites

Azure subscription - create one trial account
Azure storage account - create a storage account
Latest .NET SDK for your operating system. Be sure to get the SDK and not the runtime.

Setting up

This section walks you through preparing a project to work with the Azure Blob Storage client library for .NET.

Create the project

Create a .NET console app using either the .NET CLI or Visual Studio 2022.

Visual Studio 2022
.NET CLI

At the top of Visual Studio, navigate to File > New > Project...
In the dialog window, enter console app into the project template search box and select the first result. Choose Next at the bottom of the dialog.
For the Project Name, enter BlobQuickstart. Leave the default values for the rest of the fields and select Next.
For the Framework, ensure the latest installed version of .NET is selected. Then choose Create. The new project opens inside the Visual Studio environment.

In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name BlobQuickstart. This command creates a simple "Hello World" C# project with a single source file: Program.cs.
```
dotnet new console -n BlobQuickstart
```
Switch to the newly created BlobQuickstart directory.
```
cd BlobQuickstart
```
Open the project in your desired code editor. To open the project in:
- Visual Studio, locate and double-click the BlobQuickStart.csproj file.
- Visual Studio Code, run the following command:
```
code .
```

Install the package

To interact with Azure Blob Storage, install the Azure Blob Storage client library for .NET.

Visual Studio 2022
.NET CLI

In Solution Explorer, right-click the Dependencies node of your project. Select Manage NuGet Packages.
In the resulting window, search for Azure.Storage.Blobs. Select the appropriate result, and select Install.

Use the following command to install the Azure.Storage.Blobs package:

dotnet add package Azure.Storage.Blobs

If this command to add the package fails, follow these steps:

Make sure that nuget.org is added as a package source. You can list the package sources using the dotnet nuget list source command:
```
dotnet nuget list source
```
If you don't see nuget.org in the list, you can add it using the dotnet nuget add source command:
```
dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org
```

Now that the package source is updated, run the command to install the package.

Set up the app code

Replace the starting code in the Program.cs file so that it matches the following example, which includes the necessary using statements for this exercise.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Object model

Azure Blob Storage is optimized for storing massive amounts of unstructured data. Unstructured data doesn't adhere to a particular data model or definition, such as text or binary data. Blob storage offers three types of resources:

The storage account
A container in the storage account
A blob in the container

The following diagram shows the relationship between these resources.

Diagram of Blob storage architecture.

Use the following .NET classes to interact with these resources:

BlobServiceClient: The BlobServiceClient class allows you to manipulate Azure Storage resources and blob containers.
BlobContainerClient: The BlobContainerClient class allows you to manipulate Azure Storage containers and their blobs.
BlobClient: The BlobClient class allows you to manipulate Azure Storage blobs.

Code examples

The sample code snippets in the following sections demonstrate how to perform the following tasks with the Azure Blob Storage client library for .NET:

Authenticate to Azure and authorize access to blob data
Create a container
Upload a blob to a container
List blobs in a container
Download a blob
Delete a container

Important

Make sure you've installed the correct NuGet packages and added the necessary using statements in order for the code samples to work, as described in the setting up section.

Authenticate to Azure and authorize access to blob data

Application requests to Azure Blob Storage must be authorized. Using the DefaultAzureCredential class provided by the Azure Identity client library is the recommended approach for implementing passwordless connections to Azure services in your code, including Blob Storage.

You can also authorize requests to Azure Blob Storage by using the account access key. However, this approach should be used with caution. Developers must be diligent to never expose the access key in an unsecure location. Anyone who has the access key is able to authorize requests against the storage account, and effectively has access to all the data. DefaultAzureCredential offers improved management and security benefits over the account key to allow passwordless authentication. Both options are demonstrated in the following example.

Passwordless (Recommended)
Connection String

DefaultAzureCredential is a class provided by the Azure Identity client library for .NET, which you can learn more about on the DefaultAzureCredential overview. DefaultAzureCredential supports multiple authentication methods and determines which method should be used at runtime. This approach enables your app to use different authentication methods in different environments (local vs. production) without implementing environment-specific code.

The order and locations in which DefaultAzureCredential looks for credentials can be found in the Azure Identity library overview.

For example, your app can authenticate using your Visual Studio sign-in credentials with when developing locally. Your app can then use a managed identity once it has been deployed to Azure. No code changes are required for this transition.

Assign roles to your Microsoft Entra user account

When developing locally, make sure that the user account that is accessing blob data has the correct permissions. You'll need Storage Blob Data Contributor to read and write blob data. To assign yourself this role, you'll need to be assigned the User Access Administrator role, or another role that includes the Microsoft.Authorization/roleAssignments/write action. You can assign Azure RBAC roles to a user using the Azure portal, Azure CLI, or Azure PowerShell. You can learn more about the available scopes for role assignments on the scope overview page.

In this scenario, you'll assign permissions to your user account, scoped to the storage account, to follow the Principle of Least Privilege. This practice gives users only the minimum permissions needed and creates more secure production environments.

The following example will assign the Storage Blob Data Contributor role to your user account, which provides both read and write access to blob data in your storage account.

Important

In most cases it will take a minute or two for the role assignment to propagate in Azure, but in rare cases it may take up to eight minutes. If you receive authentication errors when you first run your code, wait a few moments and try again.

In the Azure portal, locate your storage account using the main search bar or left navigation.
On the storage account overview page, select Access control (IAM) from the left-hand menu.
On the Access control (IAM) page, select the Role assignments tab.
Select + Add from the top menu and then Add role assignment from the resulting drop-down menu.
Use the search box to filter the results to the desired role. For this example, search for Storage Blob Data Contributor and select the matching result and then choose Next.
Under Assign access to, select User, group, or service principal, and then choose + Select members.
In the dialog, search for your Microsoft Entra username (usually your user@domain email address) and then choose Select at the bottom of the dialog.
Select Review + assign to go to the final page, and then Review + assign again to complete the process.

To assign a role at the resource level using the Azure CLI, you first must retrieve the resource id using the az storage account show command. You can filter the output properties using the --query parameter.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Copy the output Id from the preceding command. You can then assign roles using the az role command of the Azure CLI.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

To assign a role at the resource level using Azure PowerShell, you first must retrieve the resource ID using the Get-AzResource command.

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Copy the Id value from the preceding command output. You can then assign roles using the New-AzRoleAssignment command in PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

You can authorize access to data in your storage account using the following steps:

For local development, make sure you're authenticated with the same Microsoft Entra account you assigned the role to. You can authenticate via popular development tools, such as the Azure CLI or Azure PowerShell. The development tools with which you can authenticate vary across languages.
Sign-in to Azure through the Azure CLI using the following command:
```
az login
```
Select the Sign in button in the top right of Visual Studio.

Sign-in using the Microsoft Entra account you assigned a role to previously.
You will need to install the Azure CLI to work with DefaultAzureCredential through Visual Studio Code.

On the main menu of Visual Studio Code, navigate to Terminal > New Terminal.

Sign-in to Azure through the Azure CLI using the following command:
```
az cloud set -n AzureChinaCloud
az login
```
Sign-in to Azure using PowerShell via the following command:
```
Connect-AzAccount -Environment AzureChinaCloud
```
To use DefaultAzureCredential, add the Azure.Identity package to your application.
- Visual Studio
- .NET CLI
1. In Solution Explorer, right-click the Dependencies node of your project. Select Manage NuGet Packages.
2. In the resulting window, search for Azure.Identity. Select the appropriate result, and select Install.
```
dotnet add package Azure.Identity
```

Update your Program.cs code to match the following example. When the code is run on your local workstation during development, it will use the developer credentials of the prioritized tool you're logged into to authenticate to Azure, such as the Azure CLI or Visual Studio.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.chinacloudapi.cn"),
        new DefaultAzureCredential());

Make sure to update the storage account name in the URI of your BlobServiceClient. The storage account name can be found on the overview page of the Azure portal.

Note

When deployed to Azure, this same code can be used to authorize requests to Azure Storage from an application running in Azure. However, you'll need to enable managed identity on your app in Azure. Then configure your storage account to allow that managed identity to connect. For detailed instructions on configuring this connection between Azure services, see the Auth from Azure-hosted apps tutorial.

A connection string includes the storage account access key and uses it to authorize requests. Always be careful to never expose the keys in an unsecure location.

Note

To authorize data access with the storage account access key, you'll need permissions for the following Azure RBAC action: Microsoft.Storage/storageAccounts/listkeys/action. The least privileged built-in role with permissions for this action is Reader and Data Access, but any role which includes this action will work.

Sign in to the Azure portal.
Locate your storage account.
In the storage account menu pane, under Security + networking, select Access keys. Here, you can view the account access keys and the complete connection string for each key.
In the Access keys pane, select Show keys.
In the key1 section, locate the Connection string value. Select the Copy to clipboard icon to copy the connection string. You'll add the connection string value to an environment variable in the next section.

You can see the connection string for your storage account using the az storage account show-connection-string command.

az storage account show-connection-string --name "<your-storage-account-name>"

You can assemble a connection string with PowerShell using the Get-AzStorageAccount and Get-AzStorageAccountKey commands.

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.chinacloudapi.cn'

Configure your storage connection string

After you copy the connection string, write it to a new environment variable on the local machine running the application. To set the environment variable, open a console window, and follow the instructions for your operating system. Replace <yourconnectionstring> with your actual connection string.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

After you add the environment variable in Windows, you must start a new instance of the command window. If you're using Visual Studio on Windows, you may need to relaunch Visual Studio after creating the environment variable for the change to be detected.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

The code below retrieves the connection string for the storage account from the environment variable created earlier, and uses the connection string to construct a service client object.

Add following code to the end of the Program.cs file:

// Retrieve the connection string for use with the application. 
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

// Create a BlobServiceClient object 
var blobServiceClient = new BlobServiceClient(connectionString);

Important

The account access key should be used with caution. If your account access key is lost or accidentally placed in an insecure location, your service may become vulnerable. Anyone who has the access key is able to authorize requests against the storage account, and effectively has access to all the data. DefaultAzureCredential provides enhanced security features and benefits and is the recommended approach for managing authorization to Azure services.

Create a container

Create a new container in your storage account by calling the CreateBlobContainerAsync method on the blobServiceClient object. In this example, the code appends a GUID value to the container name to ensure that it's unique.

Add the following code to the end of the Program.cs file:

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.chinacloudapi.cn"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

To learn more about creating a container, and to explore more code samples, see Create a blob container with .NET.

Important

Container names must be lowercase. For more information about naming containers and blobs, see Naming and Referencing Containers, Blobs, and Metadata.

Upload a blob to a container

Upload a blob to a container using UploadAsync. The example code creates a text file in the local data directory to upload to the container.

Add the following code to the end of the Program.cs file:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);

To learn more about uploading blobs, and to explore more code samples, see Upload a blob with .NET.

List blobs in a container

List the blobs in the container by calling the GetBlobsAsync method.

Add the following code to the end of the Program.cs file:

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

To learn more about listing blobs, and to explore more code samples, see List blobs with .NET.

Download a blob

Download the blob we created earlier by calling the DownloadToAsync method. The example code appends the string "DOWNLOADED" to the file name so that you can see both files in local file system.

Add the following code to the end of the Program.cs file:

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

To learn more about downloading blobs, and to explore more code samples, see Download a blob with .NET.

Delete a container

The following code cleans up the resources the app created by deleting the container using DeleteAsync. The code example also deletes the local files created by the app.

The app pauses for user input by calling Console.ReadLine before it deletes the blob, container, and local files. This is a good chance to verify that the resources were created correctly, before they're deleted.

Add the following code to the end of the Program.cs file:

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

To learn more about deleting a container, and to explore more code samples, see Delete and restore a blob container with .NET.

The completed code

After completing these steps, the code in your Program.cs file should now resemble the following:

Passwordless (Recommended)
Connection String

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.chinacloudapi.cn"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient("<storage-account-connection-string>");

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Run the code

This app creates a test file in your local data folder and uploads it to Blob storage. The example then lists the blobs in the container and downloads the file with a new name so that you can compare the old and new files.

If you're using Visual Studio, press F5 to build and run the code and interact with the console app. If you're using the .NET CLI, navigate to your application directory, then build and run the application.

dotnet build

dotnet run

The output of the app is similar to the following example (GUID values omitted for readability):

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.chinacloudapi.cn/quickstartblobsGUID/quickstartGUID.txt

Listing blobs...
        quickstartGUID.txt

Downloading blob to
        ./data/quickstartGUIDDOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Before you begin the clean-up process, check your data folder for the two files. You can open them and observe that they're identical.

Clean up resources

After you verify the files and finish testing, press the Enter key to delete the test files along with the container you created in the storage account. You can also use Azure CLI to delete resources.

Next step

Azure Storage samples and developer guides for .NET

Quickstart: Azure Blob Storage client library for .NET

Prerequisites

Setting up

Create the project

Install the package

Set up the app code

Object model

Code examples

Authenticate to Azure and authorize access to blob data

Assign roles to your Microsoft Entra user account

Sign in and connect your app code to Azure using DefaultAzureCredential

Create a container

Upload a blob to a container

List blobs in a container

Download a blob

Delete a container

The completed code

Run the code

Clean up resources

Next step

Additional resources