Get started with Azure Blob Storage and .NET

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

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

Prerequisites

Set up your project

Open a command prompt and change directory (cd) into your project folder. Then, install the Azure Blob Storage client library for .NET package by using the dotnet add package command.

cd myProject
dotnet add package Azure.Storage.Blobs

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

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

Authorize access and connect to Blob Storage

To connect to Blob Storage, create an instance of the BlobServiceClient class. This object is your starting point. You can use it to operate on the blob service instance and its containers. You can authorize access and create a BlobServiceClient object by using an Azure Active Directory (Azure AD) authorization token, an account access key, or a shared access signature (SAS).

To authorize with Azure AD, 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 In this method, dedicated application service principal objects are set up using the App registration process for use during local development. The identity of the service principal is then stored as environment variables to be accessed by the app when it's run in local development.

This method allows you to assign the specific resource permissions needed by the app to the service principal objects used by developers during local development. This approach ensures the application only has access to the specific resources it needs and replicates the permissions the app will have in production.

The downside of this approach is the need to create separate service principal objects for each developer that works on an application.

Authorize access using developer service principals
Local machine (developing and testing) User identity In this method, a developer must be signed-in to Azure from either Visual Studio, the Azure Tools extension for VS Code, the Azure CLI, or Azure PowerShell on their local workstation. The application then can access the developer's credentials from the credential store and use those credentials to access Azure resources from the app.

This method has the advantage of easier setup since a developer only needs to sign in to their Azure account from Visual Studio, VS Code or the Azure CLI. The disadvantage of this approach is that the developer's account likely has more permissions than required by the application, therefore not properly replicating the permissions the app will run with in production.

Authorize access using developer credentials
Hosted in Azure Managed identity Apps hosted in Azure should use a managed identity service principal. Managed identities are designed to represent the identity of an app hosted in Azure and can only be used with Azure hosted apps.

For example, a .NET web app hosted in Azure App Service would be assigned a managed identity. The managed identity assigned to the app would then be used to authenticate the app to other Azure services.

Authorize access from Azure-hosted apps using a managed identity
Hosted outside of Azure (for example, on-premises apps) Service principal Apps hosted outside of Azure (for example on-premises apps) that need to connect to Azure services should use an application service principal. An application service principal represents the identity of the app in Azure and is created through the application registration process.

For example, consider a .NET web app hosted on-premises that makes use of Azure Blob Storage. You would create an application service principal for the app using the App registration process. The AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET would all be stored as environment variables to be read by the application at runtime and allow the app to authenticate to Azure using the application service principal.

Authorize access from on-premises apps using an application service principal

The easiest 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.

public static void GetBlobServiceClient(ref BlobServiceClient blobServiceClient, string accountName)
{
    TokenCredential credential = new DefaultAzureCredential();

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

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

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.

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

Build your application

As you build your application, your code will primarily interact with three types of resources:

  • The storage account, which is the unique top-level namespace for your Azure Storage data.

  • Containers, which organize the blob data in your storage account.

  • Blobs, which store unstructured data like text and binary data.

The following diagram shows the relationship between these resources.

Diagram of Blob storage architecture

Each type of resource is represented by one or more associated .NET classes. This table lists the basic classes with a brief description:

Class Description
BlobServiceClient Represents the Blob Storage endpoint for your storage account.
BlobContainerClient Allows you to manipulate Azure Storage containers and their blobs.
BlobClient Allows you to manipulate Azure Storage blobs.
AppendBlobClient Allows you to perform operations specific to append blobs such as periodically appending log data.
BlockBlobClient Allows you to perform operations specific to block blobs such as staging and then committing blocks of data.

The following guides show you how to use each of these classes to build your application.

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 leases Establish and manage a lock on a container or the blobs in a container.
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 account to another account.
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.

See also