Azure Storage Files Shares client library for C - version 12.19.0

++

Azure Files provides fully managed file shares in the cloud that are accessible through the Server Message Block (SMB) and Network File System (NFS) protocols. Azure file shares can be mounted concurrently by cloud or on-premises deployments and accessed through the Azure Files REST API.

Source code | Package (vcpkg) | API reference documentation | Product documentation | Samples

Getting started

Prerequisites

If you need to create a Storage account, you can use the Azure portal or the Azure CLI. When using the Azure CLI, replace <your-resource-group-name> and <your-storage-account-name> with your own values. Storage account names must be globally unique.

az login
az storage account create `
  --resource-group <your-resource-group-name> `
  --name <your-storage-account-name> `
  --sku Standard_LRS

Install the package

The easiest way to acquire the C++ SDK is with the vcpkg package manager and CMake. See the Azure SDK for C++ installation instructions for more information. The following commands use vcpkg in manifest mode.

Create a vcpkg manifest in the root of your project:

vcpkg new --application

Add Azure Storage Files Shares and Azure Identity to the manifest:

vcpkg add port azure-storage-files-shares-cpp azure-identity-cpp

Then add the following to your CMakeLists.txt file:

find_package(azure-identity-cpp CONFIG REQUIRED)
find_package(azure-storage-files-shares-cpp CONFIG REQUIRED)

target_link_libraries(
  <your project name>
  PRIVATE
    Azure::azure-identity
    Azure::azure-storage-files-shares)

Set CMAKE_TOOLCHAIN_FILE to the path to vcpkg.cmake before the project() statement in your CMakeLists.txt file:

set(CMAKE_TOOLCHAIN_FILE "vcpkg-root/scripts/buildsystems/vcpkg.cmake")

You can instead pass the path with the -DCMAKE_TOOLCHAIN_FILE argument when configuring CMake. For other ways to acquire and install the library, see the Azure C++ project setup samples.

Create and authenticate clients

ShareServiceClient operates on the Azure Files service at the Storage account level. From it, you can create clients for shares, directories, and files.

The following example uses DefaultAzureCredential, which supports multiple credential types and uses credentials from your development environment. After signing in with az login, set AZURE_STORAGE_FILE_ACCOUNT_URL to a URL such as https://<your-storage-account-name>.file.core.windows.net.

#include <azure/identity.hpp>
#include <azure/storage/files/shares.hpp>

#include <cstddef>
#include <cstdint>
#include <cstdlib>
#include <iostream>
#include <memory>
#include <stdexcept>
#include <string>
#include <vector>

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

int main()
{
  const char* accountUrl = std::getenv("AZURE_STORAGE_FILE_ACCOUNT_URL");
  if (accountUrl == nullptr)
  {
    throw std::runtime_error("AZURE_STORAGE_FILE_ACCOUNT_URL is not set.");
  }

  auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();
  ShareClientOptions options;
  options.ShareTokenIntent = Models::ShareTokenIntent::Backup;
  ShareServiceClient serviceClient(accountUrl, credential, options);

  ShareClient shareClient = serviceClient.GetShareClient("sample-share");
  ShareDirectoryClient directoryClient = shareClient.GetRootDirectoryClient();
  ShareFileClient fileClient = directoryClient.GetFileClient("sample-file");
}

For more information about credential selection and configuration, see DefaultAzureCredential.

Key concepts

Azure file shares can be used to:

  • Replace or supplement on-premises file servers and network-attached storage
  • Lift and shift applications that expect a file share
  • Share application settings, diagnostics, and development tools
  • Provide concurrently mounted storage to cloud and on-premises systems

Azure Files offers the following resource hierarchy:

  • The Storage account, accessed through ShareServiceClient
  • A file share, accessed through ShareClient
  • A directory, accessed through ShareDirectoryClient
  • A file, accessed through ShareFileClient

Authentication

The library supports Microsoft Entra ID credentials, connection strings, shared key credentials, and shared access signatures. Microsoft Entra ID with DefaultAzureCredential is recommended for getting started when the account and operation support OAuth authentication. Token-authenticated requests must specify ShareTokenIntent; the only currently supported value is Models::ShareTokenIntent::Backup. See the samples for other authentication options.

Thread safety

All client instance methods are thread-safe and independent of each other (guideline). Reusing client instances is safe, even across threads.

Additional concepts

Replaceable HTTP transport adapter | Response model types | Long-running operations

Examples

The examples below use the clients created in Create and authenticate clients.

Create a share and upload a file

const std::string fileContent = "Hello Azure!";

shareClient.CreateIfNotExists();

std::vector<uint8_t> buffer(fileContent.begin(), fileContent.end());
fileClient.UploadFrom(buffer.data(), buffer.size());

Download a file

auto properties = fileClient.GetProperties().Value;
std::vector<uint8_t> buffer(static_cast<std::size_t>(properties.FileSize));

fileClient.DownloadTo(buffer.data(), buffer.size());

List files and directories

for (auto page = directoryClient.ListFilesAndDirectories(); page.HasPage();
     page.MoveToNextPage())
{
  for (const auto& file : page.Files)
  {
    std::cout << "file: " << file.Name << std::endl;
  }
  for (const auto& directory : page.Directories)
  {
    std::cout << "directory: " << directory.Name << std::endl;
  }
}

Troubleshooting

Azure Files service operations throw an Azure::Storage::StorageException on failure. The exception includes the HTTP status code, service error code, request ID, and other details that can help diagnose the failure. See the File service error codes for service-specific errors.

try
{
  shareClient.Delete();
}
catch (const Azure::Storage::StorageException& exception)
{
  if (exception.ErrorCode == "ShareNotFound")
  {
    // The share has already been deleted.
  }
  else
  {
    throw;
  }
}

Next steps

The Azure Files getting-started sample demonstrates how to create a share and upload, download, and inspect a file.

Contributing

For details on contributing to this repository, see the contributing guide.

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 the Contributor License Agreement.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately. Follow the instructions provided by the bot. You only need to do this once across all repositories using the CLA.

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 questions or comments.

Reporting security issues and security bugs

Security issues and bugs should be reported privately to the Microsoft Security Response Center (MSRC) at secure@microsoft.com. You should receive a response within 24 hours. If you do not, follow up by email to confirm that your original message was received. For more information, including the MSRC PGP key, see the Security TechCenter.

License

Azure SDK for C++ is licensed under the MIT license.

  • Last updated on