Create and manage client objects that interact with data resources
The Azure SDKs are collections of libraries built to make it easier to use Azure services from different languages. The SDKs are designed to simplify interactions between your application and Azure resources. Working with Azure resources using the SDK begins with creating a client instance. This article shows how to create client objects to interact with data resources in Azure Blob Storage, and offers best practices on how to manage clients in your application.
About client objects
The Azure Blob Storage client libraries allow you to interact with three types of resources in the storage service:
- Storage accounts
- Blob containers
- Blobs
Depending on the needs of your application, you can create client objects at any of these three levels.
For blobs, there's a general blob client that covers common blob operations across all types, and there are specialized blob clients for each type (block blob, append blob, and page blob).
The following table lists the different client classes for each language:
1 For Python, BlobClient
includes methods for specialized blob types.
Each client type can be instantiated by calling a simple constructor, or an overload that takes various configuration options. For Java, each client type has a separate class which provides a builder API to help with configuration and instantiation. Depending on the language SDK, these client configuration options are passed to the constructor in different ways. See the class reference from the table for details.
Authorize a client object
For an app to access blob resources and interact with them, a client object must be authorized. The code samples in this article use DefaultAzureCredential to authenticate to Azure via a Microsoft Entra security principal. The authentication process includes obtaining an access token for authorization. This access token is passed as a credential when the client is instantiated, and the credential persists throughout the client lifetime. The Microsoft Entra security principal requesting the token must be assigned an appropriate Azure RBAC role that grants access to blob data. To learn more, see Assign an Azure role for access to blob data.
The following authorization mechanisms can be used to grant the appropriate level of access to a client object:
- Microsoft Entra ID: recommended for optimal security
- Shared access signature (SAS): supported, and most secure when using a user delegation SAS token
- Account access key (Shared Key): supported, but not recommended as it can be less secure
To learn more about authorization, see Authorize access to data in Azure Storage.
Create a client object
Working with any Azure resource using the SDK begins with creating a client object. In this section, you learn how to create client objects to interact with the three types of resources in the storage service: storage accounts, containers, and blobs.
When your application creates a client object, you pass a URI referencing the endpoint to the client constructor. You can construct the endpoint string manually, as shown in the examples in this article, or you can query for the endpoint at runtime using the Azure Storage management library. To learn how to query for an endpoint, see Query for a Blob Storage endpoint.
Create a BlobServiceClient object
An authorized BlobServiceClient
object allows your app to interact with resources at the storage account level. BlobServiceClient
provides methods to retrieve and configure account properties, as well as list, create, and delete containers within the storage account. This client object is the starting point for interacting with resources in the storage account.
A common scenario is to instantiate a single service client, then create container clients and blob clients from the service client, as needed. To work with a specific container or blob, you can use the BlobServiceClient
object to create a container client or blob client. Clients created from a BlobServiceClient
will inherit its client configuration, including client options and credentials.
The following examples show how to create a BlobServiceClient
object:
Add the following using
directives:
using Azure.Identity;
using Azure.Storage.Blobs;
Add the following code to create the client object:
public BlobServiceClient GetBlobServiceClient(string accountName)
{
BlobServiceClient client = new(
new Uri($"https://{accountName}.blob.core.windows.net"),
new DefaultAzureCredential());
return client;
}
Create a BlobContainerClient object
You can use a BlobServiceClient
object to create a new BlobContainerClient
object (ContainerClient
for JavaScript and Python). A BlobContainerClient
object allows you to interact with a specific container resource. This resource doesn't need to exist in the storage account for you to create the client object. BlobContainerClient
provides methods to create, delete, or configure a container, and includes methods to list, upload, and delete the blobs within it. To perform operations on a specific blob within the container, you can create a blob client.
The following examples show how to create a container client from a BlobServiceClient
object to interact with a specific container resource:
public BlobContainerClient GetBlobContainerClient(
BlobServiceClient blobServiceClient,
string containerName)
{
// Create the container client using the service client object
BlobContainerClient client = blobServiceClient.GetBlobContainerClient(containerName);
return client;
}
If your work is narrowly scoped to a single container, you might choose to create a BlobContainerClient
object directly without using BlobServiceClient
. You can still set client options on a container client just like you would on a service client.
The following examples show how to create a container client directly without using BlobServiceClient
:
public BlobContainerClient GetBlobContainerClient(
string accountName,
string containerName,
BlobClientOptions clientOptions)
{
// Append the container name to the end of the URI
BlobContainerClient client = new(
new Uri($"https://{accountName}.blob.core.windows.net/{containerName}"),
new DefaultAzureCredential(),
clientOptions);
return client;
}
Create a BlobClient object
To interact with a specific blob resource, create a BlobClient
object from a service client or container client. A BlobClient
object allows you to interact with a specific blob resource. This resource doesn't need to exist in the storage account for you to create the client object. BlobClient
provides methods to upload, download, delete, and create snapshots of a blob.
The following examples show how to create a blob client to interact with a specific blob resource:
public BlobClient GetBlobClient(
BlobServiceClient blobServiceClient,
string containerName,
string blobName)
{
BlobClient client =
blobServiceClient.GetBlobContainerClient(containerName).GetBlobClient(blobName);
return client;
}
Manage client objects
A best practice for Azure SDK client management is to treat a client as a singleton, meaning that a class will only have one object at a time. There's no need to keep more than one instance of a client for a given set of constructor parameters or client options. This concept can be implemented in many ways, including:
- Creating a single client object and passing it as a parameter throughout the application. This approach is shown in the code examples in this article.
- Storing a client instance in a field. To learn more about C# fields, see Fields (C# Programming Guide).
- Registering the client object as a singleton in a dependency injection container of your choice. For more information on dependency injection in ASP.NET Core apps, see Dependency injection with the Azure SDK for .NET.
This approach is far more efficient at scale than calling a constructor for each client that you need.
Client immutability and thread safety
Azure SDK clients are immutable after they're created, which means that you can't change the endpoint it connects to, the credential used for authorization, or other values passed in as client options. Client immutability also means that clients are safe to share and reuse throughout the application.
If your app needs to use different configurations or credentials for clients of the same type, you can instantiate a client for each set of configuration options.
The Azure SDK guarantees that all client instance methods are thread-safe and independent of each other. This design ensures that sharing and reusing client instances is always safe, even across threads.
Next steps
To learn more about using the Azure Storage client libraries to work with data resources, see the following articles: