Get started with Azure Blob Storage and .NET

Article
10/12/2023

This article shows you how to connect to Azure Blob Storage by using the Azure Blob Storage client library for .NET. Once connected, your code can operate on containers, blobs, and features of the Blob Storage service.

API reference | Library source code | Package (NuGet) | Samples | Give feedback

Prerequisites

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

Set up your project

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

From your project directory, install packages for the Azure Blob Storage and Azure Identity client libraries using the dotnet add package command. The Azure.Identity package is needed for passwordless connections to Azure services.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Add these using statements to the top of your code file.

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

Blob client library information:

Azure.Storage.Blobs: Contains the primary classes (client objects) that you can use to operate on the service, containers, and blobs.
Azure.Storage.Blobs.Specialized: Contains classes that you can use to perform operations specific to a blob type, such as block blobs.
Azure.Storage.Blobs.Models: All other utility classes, structures, and enumeration types.

Authorize access and connect to Blob Storage

To connect an application to Blob Storage, create an instance of the BlobServiceClient class. This object is your starting point to interact with data resources at the storage account level. You can use it to operate on the storage account and its containers. You can also use the service client to create container clients or blob clients, depending on the resource you need to work with.

To learn more about creating and managing client objects, see Create and manage client objects that interact with data resources.

You can authorize a BlobServiceClient object by using a Microsoft Entra authorization token, an account access key, or a shared access signature (SAS).

To learn more about each of these authorization mechanisms, see Authorize access to data in Azure Storage.

To authorize with Microsoft Entra ID, you'll need to use a security principal. The type of security principal you need depends on where your application runs. Use this table as a guide.

Where the application runs	Security principal	Guidance
Local machine (developing and testing)	Service principal	To learn how to register the app, set up a Microsoft Entra group, assign roles, and configure environment variables, see Authorize access using developer service principals
Local machine (developing and testing)	User identity	To learn how to set up a Microsoft Entra group, assign roles, and sign in to Azure, see Authorize access using developer credentials
Hosted in Azure	Managed identity	To learn how to enable managed identity and assign roles, see Authorize access from Azure-hosted apps using a managed identity
Hosted outside of Azure (for example, on-premises apps)	Service principal	To learn how to register the app, assign roles, and configure environment variables, see Authorize access from on-premises apps using an application service principal

Authorize access using DefaultAzureCredential

An easy and secure way to authorize access and connect to Blob Storage is to obtain an OAuth token by creating a DefaultAzureCredential instance. You can then use that credential to create a BlobServiceClient object.

The following example creates a BlobServiceClient object authorized using DefaultAzureCredential:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

If you know exactly which credential type you'll use to authenticate users, you can obtain an OAuth token by using other classes in the Azure Identity client library for .NET. These classes derive from the TokenCredential class.

Create a Uri by using the blob service endpoint and SAS token. Then, create a BlobServiceClient by using the Uri.

public static void GetBlobServiceClientSAS(ref BlobServiceClient blobServiceClient,
    string accountName, string sasToken)
{
    string blobUri = "https://" + accountName + ".blob.core.windows.net";

    blobServiceClient = new BlobServiceClient
    (new Uri($"{blobUri}?{sasToken}"), null);
}

To learn more about generating and managing SAS tokens, see the following articles:

Create a StorageSharedKeyCredential by using the storage account name and account key. Then use that object to initialize a BlobServiceClient.

public static void GetBlobServiceClient(ref BlobServiceClient blobServiceClient,
    string accountName, string accountKey)
{
    Azure.Storage.StorageSharedKeyCredential sharedKeyCredential =
        new StorageSharedKeyCredential(accountName, accountKey);

    string blobUri = "https://" + accountName + ".blob.core.windows.net";

    blobServiceClient = new BlobServiceClient
        (new Uri(blobUri), sharedKeyCredential);
}

You can also create a BlobServiceClient by using a connection string.

BlobServiceClient blobServiceClient = new BlobServiceClient(connectionString);

For information about how to obtain account keys and best practice guidelines for properly managing and safeguarding your keys, see Manage storage account access keys.

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.

To learn more about each of these authorization mechanisms, see Authorize access to data in Azure Storage.

Build your application

As you build applications to work with data resources in Azure Blob Storage, your code primarily interacts with three resource types: storage accounts, containers, and blobs. To learn more about these resource types, how they relate to one another, and how apps interact with resources, see Understand how apps interact with Blob Storage data resources.

The following guides show you how to work with data resources and perform specific actions using the Azure Storage client library for .NET:

Guide	Description
Create a container	Create containers.
Delete and restore containers	Delete containers, and if soft-delete is enabled, restore deleted containers.
List containers	List containers in an account and the various options available to customize a listing.
Manage properties and metadata	Get and set properties and metadata for containers.
Create and manage container leases	Establish and manage a lock on a container.
Create and manage blob leases	Establish and manage a lock on a blob.
Append data to blobs	Learn how to create an append blob and then append data to that blob.
Upload blobs	Learn how to upload blobs by using strings, streams, file paths, and other methods.
Download blobs	Download blobs by using strings, streams, and file paths.
Copy blobs	Copy a blob from one location to another.
List blobs	List blobs in different ways.
Delete and restore	Delete blobs, and if soft-delete is enabled, restore deleted blobs.
Find blobs using tags	Set and retrieve tags, and use tags to find blobs.
Manage properties and metadata	Get and set properties and metadata for blobs.
Set or change a blob's access tier	Set or change the access tier for a block blob.