Edit

Develop for Azure Files with C++

  • Article

Tip

Try the Microsoft Azure Storage Explorer

Microsoft Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, macOS, and Linux.

Applies to

File share type SMB NFS
Standard file shares (GPv2), LRS/ZRS Yes No
Standard file shares (GPv2), GRS/GZRS Yes No
Premium file shares (FileStorage), LRS/ZRS Yes No

About this tutorial

In this tutorial, you'll learn how to do basic operations on Azure Files using C++. If you're new to Azure Files, going through the concepts in the sections that follow will be helpful in understanding the samples. Some of the samples covered are:

  • Create and delete Azure file shares
  • Create and delete directories
  • Upload, download, and delete a file
  • Set and list the metadata for a file

Note

Because Azure Files may be accessed over SMB, it is possible to write simple applications that access the Azure file share using the standard C++ I/O classes and functions. This article will describe how to write applications that use the Azure Storage C++ SDK, which uses the File REST API to talk to Azure Files.

Prerequisites

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-files-shares-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 FilesShareQuickstartV12.

Visual Studio dialog for configuring a new C++ Windows console app

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.

    Screenshot that shows where the access key settings are in the Azure portal

  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.

    Screenshot showing how to copy a connection string from the Azure portal

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.

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

Code examples

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

Add include files

From the project directory:

  1. Open the FilesShareQuickstartV12.sln solution file in Visual Studio.
  2. Inside Visual Studio, open the FilesShareQuickstartV12.cpp source file.
  3. Remove any code inside main that was autogenerated.
  4. Add #include statements.
#include <iostream>
#include <stdlib.h>
#include <vector>

#include <azure/storage/files/shares.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 Files Share

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

Add this code to the end of main():

using namespace Azure::Storage::Files::Shares;

std::string shareName = "sample-share";

// Initialize a new instance of ShareClient
auto shareClient = ShareClient::CreateFromConnectionString(connectionString, shareName);

// Create the files share. This will do nothing if the files share already exists.
std::cout << "Creating files share: " << shareName << std::endl;
shareClient.CreateIfNotExists();

Upload files to a Files Share

The following code snippet:

  1. Declares a string containing "Hello Azure!".
  2. Gets a reference to a ShareFileClient object by getting the root ShareDirectoryClient and then calling GetFileClient on the files share from the Create a Files Share section.
  3. Uploads the string to the file by calling the ​Upload​From function. This function creates the file if it doesn't already exist, or updates it if it does.

Add this code to the end of main():

std::string fileName = "sample-file";
uint8_t fileContent[] = "Hello Azure!";

// Create the ShareFileClient
ShareFileClient fileClient = shareClient.GetRootDirectoryClient().GetFileClient(fileName);

// Upload the file
std::cout << "Uploading file: " << fileName << std::endl;
fileClient.UploadFrom(fileContent, sizeof(fileContent));

Set the metadata of a File

Set the metadata properties for a file by calling the ShareFileClient.SetMetadata function.

Add this code to the end of main():

Azure::Storage::Metadata fileMetadata = { {"key1", "value1"}, {"key2", "value2"} };
fileClient.SetMetadata(fileMetadata);

List the metadata of a File

Get the metadata properties for a file by calling the ShareFileClient.GetProperties function. The metadata is under the Metadata field of the returned Value. The metadata will be a key-value pair, similar to the example in Set the metadata of a File.

// Retrieve the file properties
auto properties = fileClient.GetProperties().Value;
std::cout << "Listing blob metadata..." << std::endl;
for (auto metadata : properties.Metadata)
{
    std::cout << metadata.first << ":" << metadata.second << std::endl;
}

Download files

Having retrieved the properties of the file in List the metadata of a File a new std::vector<uint8_t> object by using the properties of the uploaded file. Download the previously created file into the new std::vector<uint8_t> object by calling the ​DownloadTo function in the ShareFileClient base class. Finally, display the downloaded file data.

Add this code to the end of main():

std::vector<uint8_t> fileDownloaded(properties.FileSize);
fileClient.DownloadTo(fileDownloaded.data(), fileDownloaded.size());

std::cout << "Downloaded file contents: " << std::string(fileDownloaded.begin(), fileDownloaded.end()) << std::endl;

Delete a file

The following code deletes the blob from the Azure Storage Files Share by calling the ShareFileClient.Delete function.

std::cout << "Deleting file: " << fileName << std::endl;
fileClient.DeleteIfExists();

Delete a files share

The following code cleans up the resources the app created by deleting the entire Files Share by using ShareClient.​Delete.

Add this code to the end of main():

std::cout << "Deleting files share: " << shareName << std::endl;
shareClient.DeleteIfExists();

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 Files Shares storage v12 - C++ quickstart sample
Creating files share: sample-share
Uploading file: sample-file
Listing file metadata...
key1:value1
key2:value2
Downloaded file contents: Hello Azure!
Deleting file: sample-file
Deleting files share: sample-share

Next steps

In this quickstart, you learned how to upload, download, and list files using C++. You also learned how to create and delete an Azure Storage Files Share.

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

Azure Storage Files Share SDK v12 for C++ samples