Foundation API Client Library C# Installation Guide

(1)

Foundation API Client Library C# – Installation Guide

By: Jürgen Rolf Revision Version: 1.0 Revision Date: 2018-08-28 Company Unrestricted

(2)

Company Unrestricted

Revision Version 1.0, Revision Date 2018-08-28, Author: Jürgen Rolf www.factset.com | 2

Document Information

Document Details

File Name MDG Foundation API Client Library C# - Installation Guide_v1.0 external.docx Contents Installation Guide for the Foundation API Client Library – C#

Author Jürgen Rolf Version 1.0

Date 2018-08-28

Intended Audience

This document provides a step-by-step guide to installing the MDG Foundation API Client Module for C#

on hosts that are running a Java Virtual Machine.

The intended audience of this document are system administrators and developers. System administrators will be enabled to install the library on any server that need access to the Market Data Gateway.

Developers will be enabled to install the library on their development environment.

Revision History

Revision Date Version Notes Author Status

2018-08-28 1.0 Initial Release J. Rolf Released

References

No. Document Version Date

1. Quick Start Guide - Market Data Gateway (MDG) APIs

1.0 2017-12-04

2. MDG Foundation API Client Library C# - Usage Examples

x.x 20xx-xx-xx

(3)

Document Information ... 2

Document Details ... 2

Intended Audience ... 2

Revision History ... 2

References ... 2

Table of Contents ... 3

Terminology ... 4

Prerequisites ... 5

1 How to Read this Document ... 6

2 Setup & Installation of the C# Client Library ... 7

2.1 Common setup of a C# based application ... 7

3 Installation of the MDG Foundation API Client Library for C# ... 9

3.1 Contents of the Download package ... 9

3.2 Setting up the .dll Libraries in Visual Studio ... 11

4 Accessing library’s functionality from C# code ... 15

4.1 Integration of Foundation API class files ... 15

4.2 Connecting to the MDG via the C# Foundation API Client Library ... 15

5 Troubleshooting ... 18

6 Next Steps and further Readings ... 19

(4)

Terminology

Term Description

API Application Programming Interface, a piece of software that exposes data from a system to another application.

CAS Customized API Service – a server that contains customer-specific setups for back end services and hosts endpoints.

Client An application that requests data from the MDG. Also a company that is a customer of FactSet Digital Solutions.

CLR Common Language Runtime, the virtual machine for interpretation of .NET code

Endpoint A piece of software that is located on a customized API service (see CAS). It provides an abstraction layer for back-end requests and advanced business logic.

Foundation API

The set of defined requests and responses that the MDG exposes. Other programs can use these to interact with the MDG.

HTML Hypertext Markup Language, a language that describes documents, predominantly for display of web sites.

HTTP Hypertext Transfer Protocol, the Internet’s most common transfer protocol on the application layer.

HTTPS Hypertext Transfer Protocol Secure, a layer that secures transmissions over HTTP.

MDG Market Data Gateway, the market data platform of FactSet Digital Solutions PTL A proprietary protocol definition language, abbreviation for Protocol Template

Language. This definition language defines the internal binary serialization format of messages.

TCP Transmission Control Protocol, a common connection-orientated protocol used e.g. on the internet.

.NET Software Framework that allows software development mainly for Microsoft Windows environments. It supports several programming languages and C# is one of these.

(5)

Prerequisites

In order to make use of this installation guide, you need access to the Client Library Module. The online documentation is available here:

If you are missing this item, please contact your FactSet Digital Solutions contact to get access to the missing resources.

(6)

1 How to Read this Document

The introductory documentation of the MDG APIs is split into two parts:

As indicated above, each reader should start with Part I – the Quick Start Guide and afterwards pick his desired technology from Part II – the individual Technology Guides. Each of these Technology Guides carries information on a specific client library using a different technology (e.g. PHP, Java, etc.).

This document is part of the Technology Guide (Part II – documentation) of the MDG Foundation API Client Library for C#. The MDG Foundation API Client Library for C# allows clients to connect to and

communicate with FactSet Digital Solutions’ MDG Platform.

This document provides a step-by-step guide covering the installation of the client library on a target host.

The remainder of the document is structured as follows:

• Chapter 2 describes the general setup and guides the reader through the installation of the necessary software components (i.e., MDG Foundation API Client Library for C#).

• Chapter 3 describes how the library is included in a project with Visual Studio.

• Chapter 4 provides details of how the C# library needs to be integrated into the application’s server-side code and shows how a connection can be initialized to FactSet Digital Solutions’ MDG Platform.

• Chapter 5 gives some hints how to overcome common problems in the integration.

• Chapter 6 points out which other document to read next.

(7)

2 Setup & Installation of the C# Client Library

The MDG Platform allows for the retrieval of financial data and exposes advanced business logic via APIs.

It supports different connectivity scenarios, such as a request/response scenario or a setup with stateful connections (more information on this can be found in the Quick Start Guide or the available listings of the connectivity scenarios, see references). In contrast to the request/response scenario stateful connections allow for so called “subscription based” or “push” updates, which is the continuous interchange of updated data (e.g. updated stock quotes).

2.1 Common setup of a C# based application

This section serves as an example and describes common setups of the MDG APIs in a typical scenario.

Two basic architectures are available:

2.1.1 Web based application

A client on a desktop computer should be able to display financial data and use business logic available in the MDG platform. A webserver executes the application which authenticates itself against the MDG, collects the necessary financial data, issues API requests and delivers this data in form of dynamic HTML pages (e.g. ASP.NET) to the client. This architectural setup is depicted in the following illustration:

(8)

Please note, that the communication between the .NET application (located on the webserver) and the MDG Platform uses a proprietary communication protocol. This protocol is designed to be very efficient and thus uses a binary message exchange format. The protocol is called the Foundation PTL protocol. The easiest way to access the MDG platform from .NET applications without having to implement the full Foundation PTL protocol stack (e.g., serialization and deserialization of binary PTL messages) is to use the client library provided by FactSet Digital Solutions. All required low-level messages are already

implemented and encapsulated in easy to use C# objects as provided by the library.

This client library is called the MDG Foundation API Client Library for C# (or C# Extension Module).

Amongst other things, this client library for C# is used to:

• Perform the authentication handshake with the platform.

• Submit any foundation request message

• Provide a sophisticated caching layer to guarantee very low latency.

Whereas clients could (in principle) request the MDG Foundation API on a low level protocol basis, the recommended way to connect to the MDG is via the provided C# extension module, which then encapsulates the aforementioned core functionalities in a transparent way.

The communication flow is as follows: The webserver retrieves the desired financial data from the platform and executes the .NET application which is using the provided C# library. The library itself communicates with the MDG using PTL. Once received, the data is processed within the .NET application, which generates dynamic HTML pages. These HTML pages are then delivered to the requesting client device (either over HTTP or HTTPS). In this scenario there is no direct interaction between each individual client (i.e., browser) and the platform. The HTML pages are created e.g. in the ASP.NET application and then forwarded to the client via the webserver.

2.1.2 Terminal based application

A client on a desktop computer should be able to display financial data and use business logic available in the MDG platform. The C# code is executed directly on the user’s client machine’s Common Language Runtime (CLR). The CLR executes the .NET application which authenticates itself against the MDG, collects the necessary financial data, issues API requests and delivers this data in form of outputs to the client.

This architectural setup is depicted in the following illustration:

(9)

3 Installation of the MDG Foundation API Client Library for C#

This section explains the installation of the C# extension module on Visual Studio. The .NET framework is available for different platforms and this document gives details on the most common environment, which is Visual Studio on Windows.

3.1 Contents of the Download package

The Client Library comes as one zipped download package. The package contains three main folders:

• \doc

• \example

• \lib

Figure 1: Contents of the Client Library Package

(10)

3.1.1 \doc folder

This folder contains the documentation of protocol messages and thereby valuable information about the classes provided inside the library.

In order to facilitate the development, the Foundation API Client Library for .NET provides C# classes for every message specified in the Foundation API Message Protocol. Each of these C# classes is available in a separate file. The library ships with extensive documentation on the individual C# classes and the

underlying API messages. This documentation can be found in your library folder in

<LIBRARY_FOLDER>\doc (e.g., access: <LIBRARY_FOLDER>\doc\ptl\html\index.html)

3.1.2 \example folder

This folder contains an example program that demonstrates the basic use of the classes provided in the Client Library’s .dll file.

3.1.3 \lib folder

This folder contains the Client Library’s .dll files. There are four different files in this folder:

Figure 2: Files in the \lib folder

The core elements here are the two .dlls “MDGFoundationAPI_x-y-z.dll” and “MDGFoundationAPI_x-y- z_CSLIB.dll”. The .debug-File is, as the name suggests, only of interest in bug tracking efforts and the MDGFoundationAPI_x-y-z_CSLIB_sources zip-file is an alternative to MDGFoundationAPI_x-y-z_CSLIB.dll in the case that the API classes shall be compiled into a solution not as a library, but by code.

(11)

3.2 Setting up the .dll Libraries in Visual Studio

To set up the Libraries for usage has two steps:

• Placing the primary .dll library as a “Reference” in a .NET Solution

• Placing the secondary .dll as an addition resource in the Solution These two steps are described next.

3.2.1 Place the primary .dll library as a “Reference” in a .NET Solution

The “MDGFoundationAPI_x-y-z_CSLIB.dll” file is compiled to fit into a Visual Studio project as a

“Reference”. To add the .dll to your solution by bringing up the context menu of the References section in the solution and next by using the “Browse” button to find and select the .dll file.

Figure 3: “Add Reference” in the context menu

(12)

Figure 4: “Browse” button in the Reference Manager

(13)

3.2.2 Place the secondary .dll as an addition resource in the Solution

The “MDGFoundationAPI_x-y-z.dll” file is compiled as a runtime-resource for the primary .dll. That means, this .dll does not need to be included in your solution as a reference. The file has only to be included as a generic resource which has to be copied to the folder where the compiled solution is executed. That is done by opening the context menu on the Solution name (not the References section). Use the “Existing Item” entry under the “Add” submenu.

Figure 5: “Existing Item” in the context menu

When that is completed successfully, the .dll shows up in the solution explorer as a file.

(14)

Figure 6: dll shows in Solution Explorer

To finish the setup of this file, the file must be marked as one that must be copied to the working directory of the solution when the solution is built.

The settings for that are located in the “Properties” view, that by default opens under the Solution Explorer when the file is selected with either left or tight mouse click.

Figure 7: File properties in the Properties view

(15)

In the properties, set the value of “Copy to Output Directory” to “Copy Always”. This means the file will be copied into the same folder as the solution’s compiled file (debug or release- .exe files). This was this .dll is available to the MDGFoundationAPI_x-y-z_CSLIB.dll at runtime.

4 Accessing library’s functionality from C# code

4.1 Integration of Foundation API class files

In order to facilitate the development of applications with market data from the MDG, the Foundation API Client Library for C# provides C# classes for every message specified in the Foundation API Message Protocol.

The classes are bundled inside the MDGFoundationAPI_x-y-z_CSLIB.dll and are alternatively available in the MDGFoundationAPI_x-y-z_CSLIB_sources.zip, where each of these classes is available in a separate file.

The library ships with extensive documentation on the individual classes and the underlying API messages.

This documentation can be found in your library folder in <LIBRARY_FOLDER>/doc (e.g., access:

<LIBRARY_FOLDER>\doc\ptl\html\foundation_ptl_index.html).

Once you have integrated the .dll into Visual Studio, as described in chapter 3, you can use the classes from your Visual Studio project and connect to the MDG with them.

4.2 Connecting to the MDG via the C# Foundation API Client Library

This section shows how to establish a connection to the MDG using the library. This is a typical step to verify the installation.

Step 1) Enter needed credentials and properties

Copy the file “tutorial.cfg” to your installation directory. This file contains credentials and properties for connection setup.

At least you have to set two values, authentication and credentials. Use the following syntax:

•

authentication app:<YOUR ID APPLICATION>

•

credentials <YOUR CREDENTIALS>

Per default the configuration connects to the Show Server, i.e. the properties are set as follows:

•

deployment_stage show

•

hosts frontgate.show.mdgms.com:8200 For stage “production” use “frontgate.mdgms.com”.

If you want to connect via ssl tls set the property

(16)

•

ssl_settings tls

and set the port in property hosts to 8400, e.g.

•

hosts frontgate.show.mdgms.com:8400

Step 2) Initiate a connection

The previously defined parameters are now used to establish the connection.

Initiate the connection at a central loading position of your application. In this example, located in a package “connect”, you find a main program that sets up a connection included in your application.

(17)

using Foundation;

using System;

using System.IO;

namespace connect {

public class MyConnect {

private static MDGConnection connection;

public MyConnect() {

int i = 0;

}

public static void Main(String[] args) {

// ~~~~~~~~~~~~~~~~~~~~~

// Setup connection // ~~~~~~~~~~~~~~~~~~~~~

UUID uuid = new UUID();

connection = new MDGConnection(1, uuid);

// ~~~~~~~~~~~~~~~~~~~~~

// Connection parameters // ~~~~~~~~~~~~~~~~~~~~~

// The library comes with a number of options set to reasonable // defaults. You might however need to change some of these to match // your requirements. Two methods to pass options to the library exist.

// Either load specific config files or set options in the code.

// ~~~~~~~~~~~~~~~~~~~~~

// Load options via config file // ~~~~~~~~~~~~~~~~~~~~~

if (File.Exists("tutorial.cfg")) {

connection.ReadConfig("tutorial.cfg");

}

// ~~~~~~~~~~~~~~~~~~~~~

// Write options including defaults to config file // ~~~~~~~~~~~~~~~~~~~~~

connection.WriteConfig("tutorial.cfg.out");

// ~~~~~~~~~~~~~~~~~~~~~

// Establish connection // ~~~~~~~~~~~~~~~~~~~~~

bool okay = connection.Connect(60000);

if (okay) {

Console.Out.WriteLine("Connected...");

} else {

Console.Out.WriteLine("got connection timeout");

}

MDGConnectionContext myContext = connection.GetContext("thread 1");

} } }

(18)

This demo code checks the result of the method Connect(). If this code does not throw an exception, the MDG Foundation API client library for Java is configured properly and ready to use.

5 Troubleshooting

If the connection cannot be established with the code example in chapter 4.2, try the following approaches to solve possible issues:

Make sure the tutorial.cfg file exists in your output directories

The directories are (\bin\Debug and bin\Release by default). The tutorial classes assume that the file is present and try to access it at runtime.

Make sure tutorial.cfg has the correct syntax

The tutorial configuration for the authentication type is “authentication app:<ID_APPLICATION>” were

<ID_APPLICATION> is the identifier of your data account on the MDG and the credentials for the backend connection are specified as “credentials <CREDENTIAL_STRING>”, where <CREDENTIAL_STRING> is the secret combination of characters that allows you to access the MDG backend.

Make sure you have the right application and credentials

Application-level credential strings typically start with “$9”. If you have a different credential string, that might be another kind of secret identifier, for example a one-time token to create a connection to the MDG.

The tutorial classes assume that you have credential string available to proceed.

Make sure the CPU setting for your project match the selected libraries

There are different versions of the Foundation API Client Library available, one for 32bit and one for 64bit operating systems. If you receive an error of type “Foundation.MDGFoundationAPIPINVOKE”, it is possible that the computing architecture of your runtime environment, your Visual Studio Project and the .dll might be mismatched. If errors persist, try to set all settings to 32bit, use the respective .dll from the x68 client library and check your setup with this.

Check if “unsafe code” is allowed

If you are using the .cs files from “MDGFoundationAPI_x-y-z_CSLIB_source.zip” instead of the pre- compiled .dll, you may need to enable the option “Allow unsafe code” in the Solution’s properties, so that the resulting solution can make use of the native code in “MDGFoundationAPI_x-y-z.dll”. The native code is essential for the connectivity to the MDG.

Make sure MDGFoundationAPI_x-y-z.dll is copied to your output folder Especially if you get error messages such as “The type initializer for

'Foundation.MDGFoundationAPIPINVOKE' threw an exception“, check if the secondary .dll is available to the compied solution, i.e. if MDGFoundationAPI_x-y-z.dll is copied to your output folder (\bin\Debug or

\bin\Release by default)

(19)

6 Next Steps and further Readings

After going through this document, the environment should be set up correctly to send requests to the MDG via the MDG Foundation API Client Library. To see how requests can be done, an additional “Usage Examples” document, which primarily addresses C# developers exists. This is the natural next step in getting yourself acquainted with the MDG API. To access this document please refer to the “References”

section at the beginning of this document.

Please Note: The Usage Example document is not yet officially released, please refer to the tutorial code in the \example folder of the Library package for equivalent information.