Azure Storage Blobs Client Library for C++

Azure Blob storage is Microsoft's object storage solution for the cloud. Blob storage is optimized for storing massive amounts of unstructured data. Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data.

Getting started

Install the package

The easiest way to acquire the C++ SDK is leveraging vcpkg package manager. See the corresponding Azure SDK for C++ readme section.

To install Azure Storage packages via vcpkg:

vcpkg install azure-storage-blobs-cpp

Then, use in your CMake file:

find_package(azure-storage-blobs-cpp CONFIG REQUIRED)
target_link_libraries(<your project name> PRIVATE Azure::azure-storage-blobs)

Prerequisites

You need an Azure subscription and a Storage Account to use this package.

To create a new Storage Account, you can use the Azure Portal, Azure PowerShell, or the Azure CLI.

Build from Source

First, download the repository to your local folder:

git clone https://github.com/Azure/azure-sdk-for-cpp.git

Create a new folder under the root directory of local cloned repo, switch into this folder and run below commands:

Windows:

cmake .. -A x64
cmake --build . --target azure-storage-blobs

or Unix:

cmake .. -DCMAKE_BUILD_TYPE=Debug
cmake --build . --target azure-storage-blobs

Key concepts

Blob storage is designed for:

• Serving images or documents directly to a browser.
• Storing files for distributed access.
• Streaming video and audio.
• Writing to log files.
• Storing data for backup and restore, disaster recovery, and archiving.
• Storing data for analysis by an on-premises or Azure-hosted service.

Blob storage offers three types of resources:

• The storage account used via BlobServiceClient
• A container in the storage account used via BlobContainerClient
• A blob in a container used via BlobClient

Learn more about options for authentication (including Connection Strings, Shared Key, Shared Key Signatures, Active Directory, and anonymous public access) in our samples.

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client Options | Accessing the response | Long-running operations | Handling failures

Examples

Uploading a blob

const std::string connectionString = "<connection_string>";
const std::string containerName = "sample-container";
const std::string blobName = "sample-blob";
 
auto containerClient = BlobContainerClient::CreateFromConnectionString(connectionString, containerName);
containerClient.CreateIfNotExists();
 
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);
// upload from local file
blobClient.UploadFrom(localFilePath);
// or upload from memory buffer
blobClinet.UploadFrom(bufferPtr, bufferLength);

Downloading a blob

// download to local file
blobClient.DownloadTo(localFilePath);
// or download to memory buffer
blobClinet.DownloadTo(bufferPtr, bufferLength);

Enumerating blobs

for (auto blobPage = containerClient.ListBlobs(); blobPage.HasPage(); blobPage.MoveToNextPage()) {
  for (auto& blob : blobPage.Blobs) {
    // Below is what you want to do with each blob
    std::cout << "blob: " << blob.Name << std::endl;
  }
}

Troubleshooting

All Blob service operations will throw a StorageException on failure with helpful ErrorCodes. Many of these errors are recoverable.

try
{
  containerClient.Delete();
}
catch (Azure::Storage::StorageException& e)
{
  if (e.ErrorCode == "ContainerNotFound")
  {
    // ignore the error if the container does not exist.
  }
  else
  {
    // handle other errors here
  }
}

Next steps

Get started with our Blob samples:

1. Upload and download blobs
2. List operations

Contributing

See the Storage CONTRIBUTING.md for details on building, testing, and contributing to these libraries.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.