Sessions - Definitions and Use Cases

The following page will take you through session creation, configuration and usage.

You will see examples on how to set a default session, a specific desktop or platform session, how to use multiple sessions in a given program and what options each of the session types has. Along the way, you will be introduced to several session related concepts, like session state, global settings, several authentication and authorization features and configuration.

Session Methods

AppName(string appName)

Application Name defined by user and used for request tracking purposes

AppKey(string appKey)

Application key necessary to authenticate the specific application with the session.

GetSession()

Retrieve/create a session. A session provides an interface to establish communication.

DESKTOP ONLY

Port(params int[] ports)

Port(IEnumerable ports)

Optional Desktop Proxy ports. Default: Value extracted from .portInUse

Available for Desktop Session only.

PLATFORM ONLY

OAuthGrantType(IGrant grant)

The OAuthGrantType specification. The specification presently supports the GrantPassword and GrantRefreshToken grant types.

TakeSignonControl(bool takeControl)

Defines whether the request for authorization will take control over any existing sign-on sessions for this user. Only applies to the legacy Password Grant OAuth 2.0 type. Default is false.

Host(string host)

The Host refers to the IP address or hostname and port of the Advanced Distribution Server (ADS) streaming realtime content. When defined, all streaming communication will be through this streaming interface, by default. Host format: <IP>|<hostname>:<port>. Eg: elektron:15000

DacsUserName(string username)

The DACs user name. Username is optional.

Default: Based on the machine login ID.

DacsPosition(string position)

The IP address position of the application logging in.

Position is optional. Default: local IP address.

DacsApplicationID(string applicationId)

The ID of the application connecting in. Default: 256

Session State

Session Event Codes

Examples

The following example will create a default session. The session type is set based on library configuration.

using (ISession session = Sessions.GetSession())
{
    if (session.Open() == Session.State.Opened)
    {
        logger.Info("Created session. Done.");
    }
} 

To setup a specific session, we can specify the session name in GetSession() or create a specific session object using the respective fluent interface

// Desktop Session 
using (ISession desktopSession = Sessions.GetSession("desktop"))
{
    // Open and use session here
}

// Platform Session
var platformSession = PlatformSession.Definition(resource).GetSession();

Sessions can also be configured by creating a json file in your project.
The example bellow presumes there is an embedded file at the root level.

At runtime, it looks at the assembly and asks for this file to be read as a stream

The stream is provided to the session object in the Definition() call.

When using a custom configuration, several other details will be required as follows:

var resources = Assembly.GetExecutingAssembly().GetManifestResourceNames();
using var resource = Assembly.GetExecutingAssembly().GetManifestResourceStream(resources[0]);

// We need to also specify an ADS (Advanced Distribution Server) host 
var session = PlatformSession.Definition(resource)
                             .Host(GlobalSettings.RTDSHost)
                             .GetSession();

// Alternatively, we can use an OAuth grant
// We recommend using Global Settings to load this information from environment variables and avoid hard-coding

var grantPassword = new GrantPassword().UserName(GlobalSettings.MachineID)
                                       .Password(GlobalSettings.MachinePasswd);

using (var platformSession = PlatformSession.Definition(resource)
                                            .AppKey(GlobalSettings.AppKey)
                                            .OAuthGrantType(grantPassword)
                                            .TakeSignonControl(true)
                                            .GetSession())
{
    platformSession.OnStreamingEndpoint((api, endpoints, s) => DisplayEndpoints(api, endpoints))
                   .OnState((state, msg, s) => Console.WriteLine($"State: {state}. {msg}"))
                   .OnEvent((eventCode, msg, s) => Console.WriteLine($"Event: {eventCode}. {msg}"));

}

The example bellow shows how to register and use callbacks for session state and events.

List<Session.EventCode> events = new();
List<Session.State> states = new();

var platformSession = PlatformSession.Definition().GetSession();

var sessionState = platformsession.OnEvent((e, o, s) =>
                                  {
                                      output.WriteLine($"Event: {e} - {o}");
                                      events.Add(e);
                                  }).OnState((state, o, s) =>
                                  {
                                      output.WriteLine($"State: {state} - {o}");
                                      states.Add(state);
                                  }).Open();

var isSessionClosed = session.Close();