Channels ▼
RSS

.NET

Using the Microsoft C++ REST SDK


Visual Studio 2013 includes the C++ REST SDK version 1.0, also known as Casablanca. This Microsoft open source project is evolving in CodePlex, and takes advantage of the new set of capabilities introduced in C++ 11 to simplify cloud-based coding with a modern, asynchronous, and multi-platform API design. In this first article in a two-part series on this C++ REST SDK, I explain how you can use this SDK to consume REST services. In the next article, I'll show how to use the SDK to retrieve and send JSON documents.

Understanding C++ REST SDK Architecture

When you need the best performance, you usually evaluate going native, and C++ is one of the best options for doing so. Microsoft believes C++ is valuable in the cloud; and the company's new C++ REST SDK enables developers to work with C++ to consume REST services and achieve both great performance and scalability. It allows you to stay in C++ when consuming REST services or developing other code closely related to the cloud.

If you use C++ to consume cloud services but you use a C-based and synchronous API with callbacks, you aren't taking full advantage of the improvements included in the latest C++ versions. In addition, your code will be difficult to read and debug, and the synchronous API will make it difficult for you to create a responsive UI. Most modern Web APIs try to reduce unnecessary boilerplate and so offer asynchronous methods without the complexity of C-style callbacks.

For example, if you work with C++ 11 but you use it to make calls to a synchronous C-based API to make an HTTP GET call, your productivity levels cannot even be compared to other programming languages such as C# or Python. Microsoft developed the C++ REST SDK on top of the Parallel Patterns Library (PPL), and leverages PPL's task-based programming model. Whenever you perform an asynchronous operation with the C++ REST SDK, you are creating a new PPL task. To make the C++ REST SDK portable to Linux, Microsoft made the necessary portions of PPL run on Linux (and compile cleanly with GCC). Thus, the C++ REST SDK uses a concurrency runtime for C++ that relies heavily on C++ 11 features. Instead of working with callbacks, you can write elegant C++ 11 code that creates tasks and schedules other tasks to be executed when certain other tasks finish execution. If you have previous experience with PPL, you will find it easier to work with the C++ REST SDK.

The C++ REST SDK relies on the following four low-level stacks or APIs that ride on top of the services provided by the different operating system (see Figure 1):

  • WinHTTP: also known as Microsoft Windows HTTP Services. It is a C-based HTTP client API.
  • PPL (short for Parallel Patterns Library): the programming model for composing asynchronous operations. The C++ REST SDK uses WinHTTP on different Windows versions.
  • Boost.Asio: a cross-platform C++ library for network and low-level I/O programming that provides a consistent asynchronous model. The library uses a modern C++ approach. The C++ REST SDK uses Boost.Asio to manage communications on Linux.
  • HTTP.sys: the Windows server-side API for HTTP. The C++ REST SDK uses HTTP.sys on different Windows versions.

REST SDK
Figure 1: The four low-level stacks used by the C++ REST SDK uses.

At the time of writing, the C++ REST SDK supports the following operating systems. Note that support for both Windows XP and Windows Phone 8.x is still considered experimental.

  • Windows XP
  • Windows Vista
  • Windows 7
  • Windows 8.x
  • Windows Phone 8.x
  • Linux

The C++ REST SDK offers the following pieces that use the different low-level stacks (see Figure 2):

  • Asynchronous streams and stream buffers: These provide a base asynchronous stream, a base asynchronous stream buffer, and many implementations, such as asynchronous file streams. There are specific Interop Streams that support interoperability between STL iostreams and C++ REST SDK asynchronous streams.
  • HTTP client and listener: The HTTP client allows you to maintain a connection to an HTTP service and send requests to the server. The HTTP listener allows you to accept messages directed at a particular URI.
  • JSON parser and writer: JSON is usually a problem for static-type languages such as C++. The C++ REST SDK uses a single class (web::json::value) to represent JSON values and provides the necessary helpers to assist in serialization. You can determine the type associated with this JSON value at runtime. The C++ REST SDK enables you to pull JSON values from streams by using the parser and write JSON values to streams.
  • TCP client and listener: The TCP client provides client connections for TCP network services. The TCP listener listens for connections from TCP network clients. The primary benefit of the TCP client and listener is that it works with non-blocking asynchronous operations. However, these components are still considered experimental. If you have ever worked with the System.Net.Sockets::TcpListener and System.Net.Sockets::TcpClient classes, you will enjoy working with the experimental TCP client and listener and its simpler non-blocking asynchronous operations.

REST SDK
Figure 2: Pieces that use the different low-level stacks.

The Microsoft team working with the C++ REST SDK has plans for adding these pieces in the near future:

  • Web Sockets client and listener.
  • UDP client and listener.
  • Additional product-specific APIs built on top of the C++ REST SDK, such as Azure Storage, Mobile Services, and Bing Maps.

Working with the C++ REST SDK in a Visual Studio project

To create a project that uses the SDK in Visual Studio and builds without unexpected issues, you need to download and install the latest version from CodePlex at http://casablanca.codeplex.com/. I use version 1.3 in my examples, so if you download a different version, you will have to change some configuration values.

The default installation folder for version 1.3 is C:\Program Files (x86)\Microsoft Cpp REST SDK for VS 2013 v1.3\SDK. The VSProject subfolder includes two property files for your Visual Studio projects: CppRest.props and version.props.

After you create a C++ project for which you want to use the C++ REST SDK, you must follow these steps:

  • Copy the two property files found in the VSProject subfolder (CppRest.props and version.props) within the C++ REST SDK installation folder and paste them in main folder in which you created your Visual Studio project.
  • Open cpprest.props file where there are two properties that might have wrong values: CppRestSDKPath and CppRestRuntimeBaseFileName. If you find the following two lines, you will need to replace the 110 value with 120, as shown in the next lines. In 64-bit Windows versions, the key value name that defines the base installation folder for the C++ REST SDK is InstallDir within HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\CppRestSDK\OpenSourceRelease\120\v1.3\SDK. Unluckily, some versions of the SDK didn't check the property values and you won't be able to have a successful build if you don't replace 110 with 120 because the registry entry will never be found during the build process. The samples included with the C++ REST SDK also have the same problem, and therefore, you must make the replacements in the property files to build them.

The lines with wrong values (to be replaced) are:

<CppRestSDKPath>$([MSBuild]::GetRegistryValue(`HKEY_LOCAL_MACHINE\Software\Microsoft\CppRestSDK\OpenSourceRelease\110\v$(CppRestSDKVersionString)\SDK`, `InstallDir`))</CppRestSDKPath>
<CppRestRuntimeBaseFileName>$(CppRestBaseFileName)110$(DebugFileSuffix)_$(CppRestSDKVersionFileSuffix)</CppRestRuntimeBaseFileName>

The lines with the right values:

<CppRestSDKPath>$([MSBuild]::GetRegistryValue(`HKEY_LOCAL_MACHINE\Software\Microsoft\CppRestSDK\OpenSourceRelease\120\v$(CppRestSDKVersionString)\SDK`, `InstallDir`))</CppRestSDKPath>
<CppRestRuntimeBaseFileName>$(CppRestBaseFileName)120$(DebugFileSuffix)_$(CppRestSDKVersionFileSuffix)</CppRestRuntimeBaseFileName>

  • Now open the Visual Studio vcxproj file for your C++ project in your favorite editor and add the following line within the main Project element. This way, the project will include the CppRest.props definition. Notice that CppRest.props includes a line that imports the previously copied version.props file: <Import Project="CppRest.props" />
  • Open in the project in Visual Studio, go to the project's properties. Add the entire path to the include subfolder of the C++ REST SDK installation folder to the Include Directories within Configuration Properties | VC++ Directories. If you used the default installation folder, you need to add C:\Program Files (x86)\Microsoft Cpp REST SDK for VS 2013 v1.3\SDK\include.
  • Add the entire path to the lib subfolder of the C++ REST SDK installation folder to the Library Directories within Configuration Properties | VC++ Directories. If you used the default installation folder, you need to add C:\Program Files (x86)\Microsoft Cpp REST SDK for VS 2013 v1.3\SDK\lib.
  • Add the C++ REST SDK library, cpprest120d_1_3.lib, to Additional Dependencies within Configuration Properties | Linker | Input.

Now your C++ project is ready to start working with the C++ REST SDK. (You could also install the latest C++ REST SDK version by running the command Install-Package cpprestsdk in the Package Manager Console, and using the package to add the C++ REST SDK to an existing project with the properties set for you. However, the best way to make the latest versions work with a new project without problems is to perform the steps I've outlined.)


Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 

Video