Quickstart: Azure Blob Storage client library v12 for C++

Get started with the Azure Blob Storage client library v12 for C++. Azure Blob Storage is Microsoft's object storage solution for the cloud. Follow steps to install the package and try out example code for basic tasks. Blob Storage is optimized for storing massive amounts of unstructured data.

Use the Azure Blob Storage client library v12 for C++ to:

• Create a container
• Upload a blob to Azure Storage
• List all of the blobs in a container
• Download the blob to your local computer
• Delete a container

Resources:

• API reference documentation
• Library source code
• Samples

Prerequisites

• Azure subscription
• Azure storage account
• C++ compiler
• CMake
• Vcpkg - C and C++ package manager

Setting up

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

Install the packages

The vcpkg install command will install the Azure Storage Blobs SDK for C++ and necessary dependencies:

vcpkg.exe install azure-storage-blobs-cpp:x64-windows

For more information, visit GitHub to acquire and build the Azure SDK for C++.

Create the project

In Visual Studio, create a new C++ console application for Windows called BlobQuickstartV12.

Copy your credentials from the Azure portal

When the sample application makes a request to Azure Storage, it must be authorized. To authorize a request, add your storage account credentials to the application as a connection string. To view your storage account credentials, follow these steps:

1. Sign in to the Azure portal.

2. Locate your storage account.

3. 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.

   

4. In the Access keys pane, select Show keys.

5. 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.

   

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>"

Linux and macOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

After you add the environment variable in Windows, you must start a new instance of the command window.

Restart programs

After you add the environment variable, restart any running programs that will need to read the environment variable. For example, restart your development environment or editor before you continue.

Object model

Azure Blob Storage is optimized for storing massive amounts of unstructured data. Unstructured data is data that 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.

Use these C++ 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. It's the base class for all specialized blob classes.
• BlockBlobClient: The BlockBlobClient class allows you to manipulate Azure Storage block blobs.

Code examples

These example code snippets show you how to do the following tasks with the Azure Blob Storage client library for C++:

• Add include files
• Get the connection string
• Create a container
• Upload blobs to a container
• List the blobs in a container
• Download blobs
• Delete a container

Add include files

From the project directory:

1. Open the BlobQuickstartV12.sln solution file in Visual Studio
2. Inside Visual Studio, open the BlobQuickstartV12.cpp source file
3. Remove any code inside main that was autogenerated
4. Add #include statements

#include <stdlib.h>
#include <iostream>
#include <azure/storage/blobs.hpp>

Get the connection string

The code below retrieves the connection string for your storage account from the environment variable created in Configure your storage connection string.

Add this code inside main():

        // Retrieve the connection string for use with the application. The storage
        // connection string is stored in an environment variable on the machine
        // running the application called AZURE_STORAGE_CONNECTION_STRING.
        // Note that _MSC_VER is set when using MSVC compiler.
        static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";
#if !defined(_MSC_VER)
        const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
        // Use getenv_s for MSVC
        size_t requiredSize;
        getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
        if (requiredSize == 0) {
            throw std::runtime_error("missing connection string from env.");
        }
        std::vector<char> value(requiredSize);
        getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
        std::string connectionStringStr = std::string(value.begin(), value.end());
        const char* connectionString = connectionStringStr.c_str();
#endif

Create a container

Create an instance of the BlobContainerClient class by calling the CreateFromConnectionString function. Then call CreateIfNotExists to create the actual container in your storage account.

Important

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

Add this code to the end of main():

using namespace Azure::Storage::Blobs;

std::string containerName = "myblobcontainer";

// Initialize a new instance of BlobContainerClient
BlobContainerClient containerClient
    = BlobContainerClient::CreateFromConnectionString(connectionString, containerName);

// Create the container. This will do nothing if the container already exists.
std::cout << "Creating container: " << containerName << std::endl;
containerClient.CreateIfNotExists();

Upload blobs to a container

The following code snippet:

1. Declares a string containing "Hello Azure!".
2. Gets a reference to a BlockBlobClient object by calling GetBlockBlobClient on the container from the Create a container section.
3. Uploads the string to the blob by calling the ​Upload​From function. This function creates the blob if it doesn't already exist, or updates it if it does.

Add this code to the end of main():

std::string blobName = "blob.txt";
uint8_t blobContent[] = "Hello Azure!";
// Create the block blob client
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);

// Upload the blob
std::cout << "Uploading blob: " << blobName << std::endl;
blobClient.UploadFrom(blobContent, sizeof(blobContent));

List the blobs in a container

List the blobs in the container by calling the ListBlobs function. Only one blob has been added to the container, so the operation returns just that blob.

Add this code to the end of main():

std::cout << "Listing blobs..." << std::endl;
auto listBlobsResponse = containerClient.ListBlobs();
for (auto blobItem : listBlobsResponse.Blobs)
{
    std::cout << "Blob name: " << blobItem.Name << std::endl;
}

Download blobs

Get the properties of the uploaded blob. Then, declare and resize a new std::vector<uint8_t> object by using the properties of the uploaded blob. Download the previously created blob into the new std::vector<uint8_t> object by calling the ​DownloadTo function in the BlobClient base class. Finally, display the downloaded blob data.

Add this code to the end of main():

auto properties = blobClient.GetProperties().Value;
std::vector<uint8_t> downloadedBlob(properties.BlobSize);

blobClient.DownloadTo(downloadedBlob.data(), downloadedBlob.size());
std::cout << "Downloaded blob contents: " << std::string(downloadedBlob.begin(), downloadedBlob.end()) << std::endl;

Delete a Blob

The following code deletes the blob from the Azure Blob Storage container by calling the BlobClient.Delete function.

std::cout << "Deleting blob: " << blobName << std::endl;
blobClient.Delete();

Delete a container

The following code cleans up the resources the app created by deleting the entire container by using BlobContainerClient.​Delete.

Add this code to the end of main():

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

Run the code

This app creates a container and uploads a text file to Azure Blob Storage. The example then lists the blobs in the container, downloads the file, and displays the file contents. Finally, the app deletes the blob and the container.

The output of the app is similar to the following example:

Azure Blob Storage v12 - C++ quickstart sample
Creating container: myblobcontainer
Uploading blob: blob.txt
Listing blobs...
Blob name: blob.txt
Downloaded blob contents: Hello Azure!
Deleting blob: blob.txt
Deleting container: myblobcontainer

Next steps

In this quickstart, you learned how to upload, download, and list blobs using C++. You also learned how to create and delete an Azure Blob Storage container.

To see a C++ Blob Storage sample, continue to:

Azure Blob Storage SDK v12 for C++ sample