.Net SDK Tutorial 1 Connecting to the DSS server
Last update Nov 2023
Environment Windows
Language C#
Compilers Microsoft Visual Studio 2019
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 LSEG DataScope Select (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 DSS API.

 

Table of contents

Additional details on the prerequisites

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

A DSS user account (user name and password) is required, because this application uses it to authenticate to the DSS server.

An internet connection is required to download the software, and run it, as it connects to the DSS 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 DSS REST .Net SDK

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

Download the LSEG DSS .NET SDK and save it in your Downloads folder:

Note: the DSS REST API\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 DSS REST API directory:

Opening the solution

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

Referencing the DSS SDK

Before anything else, you must reference the DSS 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 DSS REST API\libsdk directory (where you copied the contents of the DSS 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:

Understanding the code

User authentication

The DSS REST API requires a valid DSS username and password in order to access any of the API capabilities. These username and password are the same as those used for your DSS web GUI, FTP or DSS SOAP API credentials.

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.

Extractions Context and user authentication code

At the top of the code we see a using directive referring to DataScope.Select.Api.Extractions, 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 System.Collections.Generic;


using System.Linq;


using System.Text;


using System.Threading.Tasks;


using DataScope.Select.Api.Extractions;


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 an Extractions Context, using as parameters the DSS URI and account (user name and password):

    	
            ExtractionsContext extractionsContext = new ExtractionsContext(dssUri, dssUserName, dssUserPassword);

The Extractions Context is the starting point for all of the API methods, 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.

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


//DSS REST API Learning Tutorial 1: main program code


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


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


using System;


using System.Collections.Generic;


using System.Linq;


using System.Text;


using System.Threading.Tasks;


using DataScope.Select.Api.Extractions;


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";


 


            ExtractionsContext extractionsContext = new ExtractionsContext(dssUri, dssUserName, dssUserPassword);


            


            string sessionToken = extractionsContext.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:

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 ExtractionsContext is part of the DataScope.Select.Api.Extractions namespace:

You can also explore the namespaces in the REST API Reference Tree on the DSS web site:

Understanding the refactored version

The refactored version is located in directory \DSS REST API\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

We created a DSS client helper class, to store 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.Extractions, giving us access to the required API types:

    	
            using DataScope.Select.Api.Extractions;

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

    	
            private ExtractionsContext extractionsContext;

We also delcare 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)


{


  extractionsContext = new ExtractionsContext(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 extractionsContext.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
    	
            
//============================================================================


//DSS 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 an extraction context.


//  Retrieve the session token from the extraction context.


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


using System;


using System.Collections.Generic;


using System.Linq;


using System.Text;


using System.Threading.Tasks;


using DataScope.Select.Api.Extractions;


using DssRestfulApiTutorials;


 


namespace DssRestfulApiTutorials


{


    class DssClient


    {


        private ExtractionsContext extractionsContext;


 


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


 


        public void ConnectToServer(string dssUserName, string dssUserPassword)


        {


            extractionsContext = new ExtractionsContext(dssUri, dssUserName, dssUserPassword);


        }


 


        public string SessionToken


        {


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


            get { return extractionsContext.SessionToken; }           


        }


    }


}

Main program file: Program.cs

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


//DSS 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 System.Collections.Generic;


using System.Linq;


using System.Text;


using System.Threading.Tasks;


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 \DSS REST API\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 DSS 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.