Azure SDK for C++

Welcome to the Azure SDK for C++ Documentation

This documentation provides comprehensive guides, tutorials, and API references for developing applications with Azure services using C++. The Azure SDK for C++ is designed to be idiomatic, efficient, and easy to use, enabling you to leverage the power of Microsoft Azure from your C++ projects.

Whether you are building new cloud-native applications or integrating existing C++ systems with Azure, this SDK offers robust tools and libraries to connect to and manage a wide range of Azure services.

Explore the sections to the left to learn about installation, get started with a quickstart guide, understand core concepts, and dive into specific service SDKs.

Installation

The Azure SDK for C++ is typically managed using CMake. We recommend using vcpkg, the C++ package manager, for the easiest installation experience.

Using vcpkg

Install vcpkg: Follow the instructions on the vcpkg GitHub repository.

Install an Azure SDK library:

vcpkg install azure-storage-blobs azidentity

Integrate with your project: Add your vcpkg toolchain file to your CMakeLists.txt:
```
set(CMAKE_TOOLCHAIN_FILE "path/to/vcpkg/scripts/buildsystems/vcpkg.cmake")
```

Manual Installation

Alternatively, you can build the SDK from source. Visit the Azure SDK for C++ GitHub repository for detailed instructions on building and integrating the libraries manually.

Quickstart: Upload a Blob to Azure Blob Storage

This quickstart guides you through uploading a file to Azure Blob Storage using the Azure SDK for C++.

Prerequisites:

An Azure Subscription.
An Azure Storage Account.
A connection string for your storage account (you can find this in the Azure portal under your storage account's "Access keys").

Create a C++ Project:

Set up a new C++ project and ensure you have CMake configured.

Add the necessary dependencies to your CMakeLists.txt:

find_package(azure-storage-blobs CONFIG REQUIRED)
find_package(azidentity CONFIG REQUIRED) # For authentication

add_executable(my_azure_app main.cpp)
target_link_libraries(my_azure_app PRIVATE azure-storage-blobs::azure-storage-blobs azidentity::azidentity)

Write the Code:

Create a main.cpp file and add the following code:

#include <iostream>
#include <storage/blobs/blob_client_options.hpp>
#include <storage/blobs/blobs_client.hpp>
#include <storage/blobs/append_blob_client.hpp>
#include <storage/blobs/page_blob_client.hpp>
#include <storage/blobs/block_blob_client.hpp>
#include <azure/core/context.hpp>
#include <azure/core/http/policies/policy.hpp>
#include <fstream>
#include <sstream>

int main() {
    const std::string connectionString = "YOUR_AZURE_STORAGE_CONNECTION_STRING";
    const std::string containerName = "my-cpp-container";
    const std::string blobName = "my-sample-blob.txt";
    const std::string localFilePath = "sample.txt";

    // Create a dummy file to upload
    std::ofstream ofs(localFilePath);
    ofs << "Hello from Azure SDK for C++!";
    ofs.close();

    try {
        // 1. Create a credential
        auto credential = std::make_shared<Azure::Storage::StorageSharedKeyCredential>(
            Azure::Core::Credentials::StorageSharedKeyCredential(connectionString));

        // 2. Create a BlobServiceClient
        Azure::Storage::Blobs::BlobServiceClient blobServiceClient(
            Azure::Core::Url("YOUR_STORAGE_ACCOUNT_URL"), // e.g., https://youraccount.blob.core.windows.net
            credential,
            Azure::Storage::Blobs::BlobClientOptions());

        // 3. Create a ContainerClient
        auto containerClient = blobServiceClient.GetContainerClient(containerName);

        // Create container if it doesn't exist
        try {
            containerClient.Create();
            std::cout << "Container created: " << containerName << std::endl;
        } catch (const Azure::Core::RequestFailedException& e) {
            if (e.StatusCode != 409) { // 409 Conflict means it already exists
                throw;
            }
            std::cout << "Container already exists: " << containerName << std::endl;
        }

        // 4. Create a BlockBlobClient
        auto blockBlobClient = containerClient.GetBlockBlobClient(blobName);

        // 5. Upload the blob
        std::ifstream fileStream(localFilePath, std::ios::binary);
        Azure::Core::IO::BodyStream& fileBody = *Azure::Core::IO::FileStream::Create(fileStream);

        auto uploadResult = blockBlobClient.Upload(fileBody, Azure::Core::Http::HttpMethod::Put);

        std::cout << "Blob uploaded successfully!" << std::endl;
        std::cout << "ETag: " << uploadResult.Value.ETag.ToString() << std::endl;

    } catch (const Azure::Core::RequestFailedException& e) {
        std::cerr << "Azure Request Failed: " << e.Message << std::endl;
        std::cerr << "Status Code: " << static_cast<int>(e.StatusCode) << std::endl;
        return 1;
    } catch (const std::exception& e) {
        std::cerr << "Standard Exception: " << e.what() << std::endl;
        return 1;
    }

    return 0;
}

Note: Replace YOUR_AZURE_STORAGE_CONNECTION_STRING and YOUR_STORAGE_ACCOUNT_URL with your actual Azure Storage details.

Build and Run:

mkdir build
cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build .
./my_azure_app

Core Concepts

Understanding these core concepts will help you effectively use the Azure SDK for C++:

Client Objects: The SDK exposes client objects for each Azure service (e.g., BlobServiceClient, CosmosDbClient). These clients are the primary interface for interacting with Azure resources.
Credentials: You'll need to authenticate your requests. The SDK supports various credential types, including shared key credentials, Azure Identity tokens, and managed identity.
Options: Client objects can be configured with options (e.g., BlobClientOptions) to customize behavior like retry policies, logging, and HTTP pipelines.
Asynchronous Operations: For I/O-bound operations, consider using the asynchronous APIs provided by the SDK to improve application responsiveness. (Note: Full async support is still evolving for C++).
Error Handling: Azure SDKs for C++ use exceptions for error reporting. Specific exceptions like Azure::Core::RequestFailedException provide detailed information about service errors.

Azure Storage

Interact with Azure Blob, Queue, Table, and File storage services.

Blob Storage

azure-storage-blobs: For managing blobs (block, append, page).
Upload, download, list, and delete blobs.
Manage containers and blob metadata.

Queue Storage

azure-storage-queues: For reliable messaging between applications.
Send, receive, peek, and delete messages.

Table Storage

azure-storage-tables: For NoSQL key-value storage.
Create tables, entities, and perform queries.

Learn More about Azure Storage SDK

Azure Cosmos DB

The SDK for Azure Cosmos DB provides access to Microsoft's globally distributed, multi-model database service.

azure-cosmos-cpp: The C++ SDK for Cosmos DB.
Perform CRUD operations on documents.
Query data using SQL syntax.
Manage databases, collections, and request units.

Learn More about Azure Cosmos DB SDK

Azure Identity

Simplify authentication to Azure services using various credential types.

azure-identity: Provides credential classes like DefaultAzureCredential, ManagedIdentityCredential, and ClientSecretCredential.
Easily manage authentication in different environments (local development, Azure VMs, App Service, etc.).

Learn More about Azure Identity SDK

Azure Key Vault

Securely manage secrets, keys, and certificates with Azure Key Vault.

azure-keyvault-secrets, azure-keyvault-keys, azure-keyvault-certificates: SDKs for interacting with Key Vault secrets, keys, and certificates respectively.
Store and retrieve sensitive information.
Perform cryptographic operations using managed keys.

Learn More about Azure Key Vault SDK

API Reference

For detailed information on classes, methods, and parameters, consult the official API reference documentation.

View Full API Reference

Code Samples

Explore a collection of practical code samples demonstrating how to use the Azure SDK for C++ with various services.

Browse Code Samples

Contributing

The Azure SDK for C++ is open source. We welcome contributions from the community!

Find out how you can contribute by visiting the project's GitHub repository and checking the contribution guidelines.

How to Contribute