Chapter 4. Native Windows

Download

API Documentation

4.1. Introduction

This is a standard Windows Phone Native App.

The SDK itself is an open source project that is hosted here. Feel free to fork it and make contribution to this project.

Before using this SDK, make sure you have Windows Phone developer tools installed. You can download them from here.

4.2. NuGet

NuGet is a dependency management tool for the Microsoft development platform including .NET and is used to share and distribute C# code. It serves as the primary tool for distributing the RHMAP .NET Client SDK.

4.2.1. Install the NuGet CLI using the Installer

To install NuGet on Windows-based Systems, download and run the NuGet Commandline installer.

4.2.2. Install NuGet Using Chocolatey

If you are using Chocolatey, you can install NuGet by executing the following command on the Windows command line: 

choco install nuget.commandline

4.3. New App

Download the sample app to get started with a new Windows Phone App which has the RHMAP SDK already included.

4.4. Existing App

You can install the SDK to your project either automatically (using NuGet) or manually.

4.4.2. Manually

Download the SDK and unzip it. Adding the .dll assembly files inside the wp80 folder as references to your project.

image

image

If you are developing a Portable Class Library project, only reference the FHSDK.dll file.

The SDK is depending on Json.Net and Microsoft HTTP Client Libraries. You need to install the assemblies of those libraries as well if they are not available in your project.

4.4.3. Set up Configuration

You need to create a new file called fhconfig.json in your project. The content of the file should be look like this: 

{
  "appid": "__ID_OF_APP_IN_PROJECT__",
  "appkey": "__APP_API_KEY_OF_APP_IN_PROJECT__",
  "connectiontag": "__CONNECTION_TAG_TO_USE_FOR_CLOUD__",
  "host": "__APP_STUDIO_HOST__",
  "projectid": "__PROJECT_ID__"
}

Make sure the build action of the file is Content.

image

4.4.4. Initialise

To use the RHMAP .NET SDK, you will need to initialise the SDK like this (normally when app is started). 

try
{
  bool inited = await FHClient.Init();
  if(inited) {
    //Initialisation is successful
  }
}
catch(FHException e)
{
  //Initialisation failed, handle exception
}

More information on connections can be found here.

Note

The Init method is the only one that is called using FHClient class, and is the only one that needs to be called from a platform-specific project (for example, can not be called from a PCL project).

All the other SDK methods are called using FH class which is defined in the FHSDK.dll assembly. This assembly can be referenced by other PCL projects. This way if your cross-platform solution contains a PCL project, you can reference this assembly file and call SDK functions from there.

4.5. Use your own choice of HttpClient

By default, the .NET SDK will use the Microsoft HTTP Client Libraries to perform all the HTTP requests. However, if you are developing iOS and Android apps using Xamarin, the ModernHttpClient is a better choice. If you want to use that, all you have to do is to install the ModernHttpClient component in your app, then use it like this: 

//the following should be called BEFORE FHClient.Init is called
//use ModernHttpClient on Android
FHHttpClientFactory.Get = (() => new HttpClient(new OkHttpNetworkHandler()));

If you don’t like either of these, you can use whatever HTTP (or REST) client you like. All you need is the cloud host of the app, which you can get using the following method: 

string cloudHost = FH.GetCloudHost();

However, the downside of the approach is that your app won’t be able to use the analytics service provided by the platform as some meta data is missing in the requests. To re-enable that, all you have to do is to add the meta data returned by the following method as a set of headers to each HTTP request: 

IDictionary<string, string> metaData = FH.GetDefaultParamsAsHeaders();
HttpRequestMessage requestMessage = new HttpRequestMessage(...);
//then loop through the metaData and add each entry as a http header to your request, using the key as the header name and value as the header value
foreach(var item in metaData){
  requestMessage.Headers.Add(item.Key, item.Value);
}
...

4.6. Use SDK

See API Docs for full details on the APIs available within the SDK.