RPC

Integrating another JSON Library

Introduction

This doc is available to help guide you in the process of integrating other JSON Libraries into RPC.

Overview

The RPC (Remote Procedure Call) library is a part of the MSTDK (Microsoft Studios Test Development Kit) suite, and is referred to simply as “RPC” for the remainder of this document. RPC allows you to remotely interact with your title for test automation and other custom tooling specific to your title.

The JSON library used to serialize and parse messages in MSTDK RPC can be customized by implementing the provided IJsonNode interface and creating build configurations that define symbols instructing the compiler to use your implementation.

Implementing IJsonNode

The implementation of IJsonNode for a particular JSON library is chosen at compile time since only one JSON library can be used. Instead of deriving from an abstract class and overriding virtual functions you derive directly from IJsonNode and implement all of its public methods. IJsonNode declares but does not define any of the methods, so forgetting to define one of them will result in a missing symbol error.

Your new class derived from IJsonNode must be called “JsonNode”, so it can be statically substituted for every use of JsonNode in RPC. There could be many classes called JsonNode but only one will be compiled into a build of RPC through the use of precompiler logic.

Follow these steps to implement IJsonNode with another JSON library of your choice:

  1.        Create a folder to house your IJsonNode implementation under Internal\Json in Rpc.NativeServer project. Name this folder according to the JSON library chosen. For example: RapidJson.
  2.        Create a filter with the same name under Internal/Json in Rpc.NativeServer project:
  3.        Add a new header to the project to house your implementation, ensuring it goes into the folder created in step 1. Name your header the same as the filter but with “Impl” appended, and move it to be contained by the filter. For example RapidJsonImpl.
  4.        Copy the contents of RapidJsonImpl.h (an existing non-default JSON implementation) into this new header, and clear the private class variables and the body of all the functions to prepare them for your custom code that integrates with another JSON library.
  5.        Customize the name of the symbol used to select this JSON implementation. Replace USE_RAPIDJSON with another symbol starting with USE_ and ending with a short (all caps) name of the new JSON library you are integrating (e.g. USE_MYJSONLIB).
  6.        Add code to all of the public functions to produce expected behavior with the new JSON library. Most functions should not throw exceptions, and the ones that do must throw specific exceptions according to remarks section in the comments for each function. Consult another JSON implementation (such as RapidJson or WindowsDataJson) as sample code to implement IJsonNode for your JSON library.

Creating Build Configurations

To create build configurations based on your customized IJsonNode implementation, do the following:

  1.        Create new Debug and Release build configurations in the RPC solution by cloning them from existing configurations for RapidJson (Debug RapidJson and Release RapidJson), and appending the short name of your JSON library to the end of each cloned configuration name (e.g. Debug MyJsonLib, Release MyJsonLib):
  2.        Define the symbol chosen in step 5 of the previous section (e.g. USE_MYJSONLIB) in each of the new build configurations (e.g. Debug MyJsonLib, Release MyJsonLib). Since the configurations were previously cloned from Debug RapidJson and Release RapidJson will have already define USE_RAPIDJSON, so this is a simple matter of replacing USE_RAPIDJSON with your own symbol:

Testing the new JSON library

The test suite includes unit tests that start with “TestJsonNode…” to help verify that the JsonNode implementation used in a build of RPC works as expected. Run these tests after implementing JsonNode using another JSON library:

See also

  •          RPC – Getting Started Guide.docx

Last edited May 1, 2015 at 10:59 PM by vanovy, version 2