category: Getting Started

Once you have a server application deployed, you can build client application that will connect to it using the library targeting your development platform.

Creating a client object

You must first create a configuration object. This object contains all the information the client need to connect to your server app.

var config = ClientConfiguration.ForAccount("6a575873-eed0-4564-af84-58b516b1f624" /*Account Id */, "chat" /*App Id */);    
var config = Stormancer.Configuration.forAccount("6a575873-eed0-4564-af84-58b516b1f624" /*Account Id */, "chat" /*App Id */);

Using this configuration object, create a client object.

var client = new Stormancer.Client(config);

The client can be used to interact with scenes and other Stormancer services.

Obtaining a scene object

Now that you have a client, you can connect to scenes of your application. The client expose two methods to do that: GetPublicScene and GetScene. Get scene allows you to connect to a scene using an authentication token. That enable you to restrict exactly who can connect to the scene whereas GetPublicScene only enables you to connect to publicly available scenes.

To learn more about private scenes and the GetScene method, read working with private scenes

To obtain a scene object by calling GetPublicScene, pass it a scene identifiant and some userdata as arguments. This data will be serialized and associated with the connection on the server. It allows you to add some metadata to your connection, for instance for authentication purpose. See Authentication plugin for an actual implementation.

Note that your server application shouldn't trust the data coming from a GetPublicScene call. If you need trusted data, use GetScene with a signed token instead.

var userData = new User{ Name="Lolth"};
var scene = await client.GetPublicScene("mySceneId",userData);

Once in possession of a scene object, you can perform some initialization logic on it. Let's keep it simple for now and just connect.

await scene.Connect();

You are done. Now your client app is connected to the Stormancer scene. Now let's see what happen on the server:

Server-side

On the server, when a client connects, 2 events are fired:

First, the OnConnecting event. If you throw an exception in this event, the connection attemp will be cancelled, and an exception thrown on the client. Use The ClientException class to provide a customized exception message to the client.

Next the OnConnected event. When this eventf is fired, the connection process is already completed, and the connection is available in the list of connections to the scene. The client is also able to receive messages. That's the perfect place to run logic when client connect to the app.

 scene.OnConnecting.Add(async c=>{
   //Application access forbidden to Lolth. That's it, nb: Deal with the consequences later.
   if(c.GetUserData<User>().Name == "Lolth")
   {
     throw new ClientException("Forbidden because I don't like you.");
   }
 });

 scene.OnConnected.Add(async c=>{
    //Broadcast message to all connected.
    var user = c.GetUserData<User>();
    this.AssociatedObject.BroadCast(string.Format("{0} just connected.",user.Name);
 });

Order: 5