Introducing the new Azure SDK for C++ Beta

Jeffrey Richter

The new Azure SDK for C++ is idiomatic to the C++ language and ensures consistency in behavior and API surface when communicating with Azure services.

Some of the key features of the Azure C++ SDK are:

  • Customers of our SDK compile our source code along with their own

  • The SDK is easily consumable by environments using CMake

  • We target C++ 14 and test for x86, x64, ARM32, and ARM64 CPU architectures using gcc, clang, XCode, & MS Visual C++ compilers

  • We support Linux, Windows, and Mac platforms

  • We fully embrace exception handling to report errors from SDK methods

  • We offer very few abstractions making our code easy to understand and debug

Azure Core

At the heart of our SDK is what we refer to as Azure Core. This code defines several data types and functions for use by the client libraries that build on top of it, such as the Azure Storage Blobs client library. Here are just some of Azure Core’s features:

  • A replaceable HTTP stack allowing customers to select and use the HTTP stack that they desire. We ship a libcurl transport adapter which enables our SDK to work on all supported CPU architectures and OSes. We will soon have a WinHTTP transport adapter specifically for Windows.

  • Like our other language SDKs, Azure Core offers an HTTP pipeline of policies which can be configured at runtime.

  • All I/O operations are cancelable using our own Context mechanism.

  • We have our own easy-to-use BodyStream base class enabling the upload and download of byte streams typically used by blobs and files. Using the decorator pattern, you can create your own BodyStream-derived classes to compose features such as progress reporting, encryption, compression, and so on.

In addition to the above features, Azure Core provides features available to client libraries written to access other Azure services. Customers use these features indirectly by way of interacting with a client library. By providing these features in Azure Core, the client libraries built on top of us share a common implementation and many features behave identically across client libraries. For example, Azure Core offers a standard set of credential types and an HTTP pipeline with logging, retry, and telemetry policies.

Example Code using the C++ Storage Blob Client Library

The code below demonstrates how to create a storage blob container, create a blob in that container by uploading a data buffer in memory, and how to download the blob’s data back to a memory buffer. The comments in the code describe what is happening.

#include "azure/storage/blobs/blob.hpp"

#include <iostream>
#include <string>

using namespace Azure::Storage::Blobs;

int main()
{
  // Create a BlobContainerClient from a connection string & container name
  auto containerClient = BlobContainerClient::CreateFromConnectionString(
      "[StorageConnectionString]",
      "sample-container");
  try
  {
    containerClient.Create();  // Attempt to create the blob container
  }
  catch (std::runtime_error& e)
  {
    // The container may already exist
    std::cout << e.what() << std::endl;
    return -1;
  }

  // Create a BlockBlobClient from a container & blob name
  BlockBlobClient blobClient = containerClient.GetBlockBlobClient(
    "sample-blob");

  {
    // Create blob whose content is the specified data buffer
    std::string blobContent;
    blobContent.resize(50 * 1024ULL * 1024, 'x');  // 50 MB of x

    blobClient.UploadFrom(
        reinterpret_cast<const uint8_t*>(blobContent.data()),
        blobContent.size());
  }

  {
    // Download the blob’s contents to a data buffer
    blobClient.DownloadTo(
      reinterpret_cast<uint8_t*>(&blobContent[0]), blobContent.size());
  }

  return 0;
}

Azure SDK Blog Contributions

Thank you for reading this Azure SDK blog post! We hope that you learned something new and welcome you to share this post. We are open to Azure SDK blog contributions. Please contact us at azsdkblog@microsoft.com with your topic and we’ll get you setup as a guest blogger.

3 comments

Discussion is closed. Login to edit/delete existing comments.

  • Dusan Jovanovic 0

    It is the year 2021, and the Q is 2: 2021Q2

    Let’s assume there are 4 Azure customers: A,B,C and D. Customers A,B,C have written DLL’s using Azure SDK as above. The error handling (as advised) is all C++ exceptions. Customer D is using all of those dll’s in her Azure service also developed using the same Azure SDK.

    What can possibly go wrong?

    • Jeffrey RichterMicrosoft employee 0

      All the DLLs in question need to be built with the same, or at least an ABI compatible, compiler. (e.g. VS2015 through VS2019 are currently compatible, VS2013 is not). C++ exceptions rely on thread local variables that live inside the C runtime bits. All the DLLs in question need to be built with the same version of our Azure Core library since this is where our base class exception type lives.

  • Greg Keogh 0

    You urgently need to expand the documentation so it has better Getting Started instructions with details on how to build, reference and use the library. The public developer docs page links back to itself in many places and contains no useful instructions or links on library usage. I cloned the repo and opened the folder in Visual Studio 2019 but was confronted by a bewildering assault of problems: which configuration to use?, missing dependencies (although I have them installed), CURL missing, and many more. I have been web searching and experimenting in all sorts of daring ways to try and overcome the build errors, but have only succeeded in reducing the number. After 3 solid hours of suffering I am unable to build the library.

    I must admit that I have not used C++ since 2003 so I’m at a disadvantage there, but I do have 40 years development experience, and if I can’t get off first base in compiling or using this library then I really think you should consider providing Getting Started documentation for an audience who you must not assume are steeped in modern C++ culture and conventions. How does the library interact with vcpkg? How does this library relate to others, especially the azure-storage-cpp?

    Practical examples would be especially welcome. My first task is to perform a classic stream “readline loop” to read utf-8 lines out of a blob, and without help I have no idea if this seemingly simple task is possible let alone exactly how to do it (a quick scan of the source hints that this is not implemented, but I’m not sure).

    Thanks, Greg

Feedback usabilla icon