.Net SDK Tutorial 1: Connecting to the server

Last update Dec 2023
Environment Windows
Language C#
Compilers Microsoft Visual Studio
Prerequisites DSS login, internet access, having done the Quick Start
Source code Download .Net SDK Tutorials Code

Tutorial purpose

This is the first tutorial in a series of .Net SDK tutorials. In this one we:

  • Download and install a single copy of the .Net SDK libraries, for use by all the tutorials in this series.
  • Create a small project to create the work context, connect and authenticate to the DSS REST server.

This is the starting point, pre-requisite for the following tutorials which will use the same libraries.

To ensure both seasoned and beginner developers can benefit from this tutorial set, some very basic instructions topics are covered here. The following tutorials assume such knowledge has been acquired, and concentrate on the LSEG Tick History API.

 

Table of contents

 

Additional details on the prerequisites

An installed copy of Microsoft Visual Studio is required to experiment with the code.

A DSS user account (user name and password) is required because the API uses it to authenticate to the server. These username and password will be provided to LSEG Tick History customers and are valid in the API and the GUI.

An internet connection is required to download the software, and run it, as it connects to the DataScope server.

If you have not yet gone through the Quick Start, we recommend you do it now before proceeding further, as that is where you put your work directories in place, and discover a very useful learning tool: the DSS REST API C# example application.

 

Installing the LSEG Tick History REST .Net SDK

To install the required libraries, we start where we left off with the Quick Start.

Download the LSEG Tick History REST API .Net SDK, and save it in your Downloads folder:

 

Note: the API TH REST\lib directory was automatically created if you ran the Quick Start using Microsoft Visual Studio. It is not required by this series of tutorials, only the Quick Start uses it.

Create a libsdk folder (you can name it differently), and copy the contents of the .Net SDK zip file into it:

 

Installing the tutorials source code

Now we install the C# code samples for all the .Net SDK tutorials.

Download the .Net SDK Tutorials Code package, and save it in your Downloads folder:

 Copy the contents of the .Net SDK Tutorials Code zip file into the API TH REST directory:

 

Opening the solution

Navigate to the \API TH REST\Tutorial 1\Learning folder; double click on restful_api_core_gui_starter.sln to open the solution in Microsoft Visual Studio:

 

Referencing the LSEG Tick History SDK

Before anything else, you must reference the LSEG Tick History REST API .Net SDK in the Microsoft Visual Studio project.

Important: this will have to be done again for every single tutorial, for both the learning and refactored versions.

In Microsoft Visual Studio, in the Solution Explorer, right click on the References folder, select Add Reference... :

Click on Browse..., navigate to the API TH REST\libsdk directory (where you copied the contents of the LSEG Tick History REST API .Net SDK), select all the DLL files, and click on Add:

The DLLs are displayed in the list; now click on the OK button:

The DLLs now appear in the solution explorer under the project References:

 

Viewing the C# code

In Microsoft Visual Studio, in the Solution Explorer, double click on Program.cs:

The code appears in the main window:

 

Setting the user account

Before running the code, you must replace  YourUserId  with your DSS user name, and  YourPassword  with your DSS password, in these 2 lines:

    	
            
string dssUserName = "YourUserId";


string dssUserPassword = "YourPassword";

Important: this will have to be done again for every single tutorial, for both the learning and refactored versions.

Failure to do so will result in the following error at run time:

    	
            Unhandled Exception: DataScope.Select.Api.UnauthorizedException: Invalid username or password

 

Understanding the code

Relation between the LSEG Tick History REST API and the DSS REST API

The LSEG Tick History REST API connects to the same server as the DSS (LSEG DataScope Select) REST API; the server is called the hosted DataScope server. Both APIs share some API libraries and mechanisms. For this reason you will see references to DSS instead of LSEG Tick History in the code, API calls and libraries.

User authentication

The LSEG Tick History REST API requires a valid DSS username and password in order to access any of the API capabilities. These username and password will be provided to LSEG Tick History customers and are valid in the API and the GUI.

The C# .Net SDK takes care of authentication using the supplied credentials, and attaching the received session token to the request headers.

Session tokens are valid for 24 hours, after which a 401 (Authentication Required) status code is returned. Re-authentication is automatically handled by the C# .NET SDK.

Standard Extractions Context and user authentication code

At the top of the code we see a using directive referring to DataScope.Select.Api.StandardExtractions, giving us access to the types of the DSS API namespace, so that we do not have to qualify the full namespace each time we use them. It is followed by a second using directive, referring to the namespace of our code, DssRestfulApiTutorials:

    	
            
using System;


using DataScope.Select.Api.StandardExtractions;


using DssRestfulApiTutorials;

In the main code block we first define the URI of the DSS server, as well as your DSS user account:

    	
            
Uri dssUri = new Uri("https://selectapi.datascope.refinitiv.com/RestApi/v1/");


string dssUserName = "YourUserId";


string dssUserPassword = "YourPassword";

After that we create a Standard Extractions Context, using as parameters the DSS URI and account (user name and password):

    	
            
StandardExtractionsContext standardExtractionsContext =


    new StandardExtractionsContext(dssUri, dssUserName, dssUserPassword); 

The Standard Extractions Context is used for VBD (Venue By Day) extractions, it is the starting point for all of the API methods we shall use for VBD data, the foundation element of our code.

It also logs us into the DSS server.

    	
            
string sessionToken = extractionsContext.SessionToken;


Console.WriteLine("Returned session token: " + sessionToken);

The session token is returned, we display it for testing purposes. The session token contains authentication credentials, and can be used in other contexts. It is only generated if the server connection is successful.

If the connection fails, which will be the case if the DSS user account details are not valid, attempting to retrieve the session token will result in an unhandled exception of type DataScope.Select.Api.UnauthorizedException.

Full code

The full code is also included here as this is the first tutorial, and the code is short. For the other tutorials, the full code can be displayed by opening the appropriate solution file in Microsoft Visual Studio.

    	
            
//============================================================================


//LSEG Tick History REST API Learning Tutorial 1: main program code


//Goal: connect and authenticate to the DSS REST server


//============================================================================


using System;


using DataScope.Select.Api.StandardExtractions;


using DssRestfulApiTutorials;


 


namespace DssRestfulApiTutorials


{


    class Program


    {


        static void Main()


        {


            //-----------------------------------------------------------------


            //Connect and authenticate to the DSS server:


            //-----------------------------------------------------------------


            Uri dssUri = new Uri("https://selectapi.datascope.refinitiv.com/RestApi/v1/");


            string dssUserName = "YourUserId";


            string dssUserPassword = "YourPassword";


 


            StandardExtractionsContext standardExtractionsContext =


                new StandardExtractionsContext(dssUri, dssUserName, dssUserPassword);


 


            string sessionToken = standardExtractionsContext.SessionToken;


 


            Console.WriteLine("Returned session token: " + sessionToken);


            Console.WriteLine("Press Enter to exit");


            Console.ReadLine();


        }


    }


}

 

Building and running the code

Build

Open the top menu BUILD, and click on Rebuild Solution. This will check your code for errors, and prepare it to run.

In the lower part of the screen you should get a success message:

If there are errors, they will be displayed and highlighted in the code. Errors must be corrected before the code can run.

Run

Click on  to run the code.

 

Code run results

Successful run

At run time the session token is displayed, that means we have successfully logged into the REST API:

Press Enter to close the pop-up and end the program.

 

Invalid credentials error

Failure to set valid DSS credentials will result in an Invalid username or password error (at the first run the code will complain about a missing file AyncHelper.cs before generating the error):

    	
            Unhandled Exception: DataScope.Select.Api.UnauthorizedException: Invalid username or password

To solve this:

  1. Stop the program by closing the popup, or click on the stop button (red square top right of Microsoft Visual Studio): 
  2. Set a valid DSS user name and password in the code, as described under .Net SDK Tutorials code: setting the user account.
  3. Build and run the code again.

 

Note on using directives: DSS namespaces

If a namespace is not specified or included with a using statement, it will be flagged when you add code to a project. To determine which namespace is required, there are several methods.

Obviously, with recent versions of Microsoft Visual Studio, the easiest is to use IntelliSense. In the following screenshot we commented out a required using statement. Using IntelliSense we see that StandardExtractionsContext is part of the DataScope.Select.Api.StandardExtractions namespace:

 

Understanding the refactored version

The refactored version is located in directory \API TH REST\Tutorial 1\Refactored

To view the entire code, navigate to that folder and double click on restful_api_core_gui_starter.sln to open the solution in Microsoft Visual Studio.

Refactoring

Refactoring is restructuring a program's code, to make it easier to understand and cheaper to modify, without changing its observable behaviour. The idea behind this refactoring is to encourage code re-use, and use classes to separate functionality. There is no ideal solution; consider this one as a suggestion that you can adapt to your own needs.

Explanations

DSS client helper class file: DssClient.cs

As the LSEG Tick History REST API connects to the same server as the DSS (LSEG DataScope Select) REST API, and as both APIs share some API libraries and mechanisms, we called this class the DSS client. Nevertheless, it is used here for RTH.

This DSS client helper class stores the DSS API related members and methods that could be re-used by other programs. That way we keep them separate from the main program.

Methods that are specific to our use case but are not DSS API related do not belong here.

At the top of the code we find the using directive referring to DataScope.Select.Api.StandardExtractions, giving us access to the required API types:

    	
            using DataScope.Select.Api.StandardExtractions;

We declare a standard extractions context, for use by the methods we created in this class:

    	
            private StandardExtractionsContext standardExtractionsContext;

We also declare the DSS server URI here (it is unlikely to change):

    	
            private Uri dssUri = new Uri("https://selectapi.datascope.refinitiv.com/RestApi/v1/");

We create a method to connect to the DSS server, taking the user name and password as input parameters:

    	
            
public void ConnectToServer(string dssUserName, string dssUserPassword)


{


    standardExtractionsContext =


        new StandardExtractionsContext(dssUri, dssUserName, dssUserPassword);


}

We also create a method to retrieve the session token:

    	
            
public string SessionToken


{


    //The session token is only generated if the server connection is successful.


    get { return standardExtractionsContext.SessionToken; }


}

Main program file: Program.cs

Member declarations are moved to the start of the code, before the main method:

    	
            
private static string dssUserName = "YourUserId";


private static string dssUserPassword = "YourPassword";

The user account could be read from file, entered in a popup, or hard coded like here. The choice of the mechanism is more related to the use case than the DSS API, that is why it is here and not in our DSS client helper class.

In the main method we create an instance of our DSS client helper class:

    	
            DssClient dssClient = new DssClient();

We can then call our DSS client helper methods, to connect to the DSS server, and retrieve the session token:

    	
            
dssClient.ConnectToServer(dssUserName, dssUserPassword);


DebugPrintAndWaitForEnter("Returned session token: " + dssClient.SessionToken);

The second line above uses another bespoke method to print a message and wait for a key press. We put that method in the main program file, after the main method, and not in the DSS helper class file, because it is not DSS related:

    	
            
static void DebugPrintAndWaitForEnter(string messageToPrint)


{


    Console.WriteLine(messageToPrint);


    Console.WriteLine("Press Enter to continue");


    Console.ReadLine();


}

 

Full code

The full code is also included here as this is the first tutorial, and the code is short. For the other tutorials, the full code can be displayed by opening the appropriate solution file in Microsoft Visual Studio.

DSS client helper class file: DssClient.cs
    	
            
//============================================================================


//LSEG Tick History REST API Refactored Tutorial 1: DssClient class


//DssClient class responsibilities:


//Connection:


//  Hold DSS server URI.


//  Connect (and authenticate) to the DSS REST server, by creating a standard extraction context.


//  Retrieve the session token from the standard extraction context.


//============================================================================


using System;


using DataScope.Select.Api.StandardExtractions;


using DssRestfulApiTutorials;


 


namespace DssRestfulApiTutorials


{


    class DssClient


    {


        private StandardExtractionsContext standardExtractionsContext;


 


        private Uri dssUri = new Uri("https://selectapi.datascope.refinitiv.com/RestApi/v1/");


 


        public void ConnectToServer(string dssUserName, string dssUserPassword)


        {


            standardExtractionsContext =


                new StandardExtractionsContext(dssUri, dssUserName, dssUserPassword);


        }


 


        public string SessionToken


        {


            //The session token is only generated if the server connection is successful.


            get { return standardExtractionsContext.SessionToken; }           


        }


    }


}

Main program file: Program.cs

    	
            
//============================================================================


//LSEG Tick History REST API Refactored Tutorial 1: main program code


//Goal: connect and authenticate to the DSS REST server


//============================================================================


//To facilitate the learning process, the member declarations are at the start,


//followed by the main and finally the methods.


//============================================================================


using System;


using DssRestfulApiTutorials;


 


namespace DssRestfulApiTutorials


{


    class Program


    {


        //=====================================================================


        //Member declarations


        //=====================================================================


        private static string dssUserName = "YourUserId";


        private static string dssUserPassword = "YourPassword";


 


        //=====================================================================


        //Main program entry


        //=====================================================================


        static void Main()


        {


            //-----------------------------------------------------------------


            //Connect and authenticate to the DSS server:


            //-----------------------------------------------------------------


            DssClient dssClient = new DssClient();


 


            dssClient.ConnectToServer(dssUserName, dssUserPassword);


            DebugPrintAndWaitForEnter("Returned session token: " + dssClient.SessionToken);


        }


 


        //=====================================================================


        //Helper methods


        //=====================================================================


        static void DebugPrintAndWaitForEnter(string messageToPrint)


        {


            Console.WriteLine(messageToPrint);


            Console.WriteLine("Press Enter to continue");


            Console.ReadLine();


        }


    }


}

Build and run

The refactored version is located in directory \API TH REST\Tutorial 1\Refactored

The actions described above for the learning version are applied similarly to the refactored version. Proceed to:

  1. Open the solution in Microsoft Visual Studio.
  2. Reference the LSEG Tick History SDK.
  3. View the C# code: open both DssClient.cs and Program.cs code files.
  4. Set your user account in Program.cs.
  5. Build and run. The results will be exactly the same.

 

Conclusions

The next tutorials follow the same philosophy, and re-use methods as required.

The DSS client helper class grows as we progress, gaining more and more methods to create a library of re-usable code. For that reason we do not remove any as we progress through the tutorials, and that of the last tutorial is the most complete.

The main program file also includes helper methods, and we also apply code re-use here. But as these are more specific to a use case, we only include those that we actually use in each tutorial.