This tutorial explains the various ways available to create new or connect to existing cms sessions.
We start with a easiest method first:



using System;
using System.Net;
using erminas.SmartAPI.CMS.Utils;

public class MyClass {
  public void DoSomething() {
    //your cms username and password
    var authData = new PasswordAuthentication("username", "password");

    //url of the cms server
    var url = "http://mycmsserver/cms";

    var login = new ServerLogin(url, authData);
    //this tries to create a new session. if the user can't open any more sessions, an exception is thrown
    using (var session = SessionBuilder.CreateSession(login))
    {
      ...
    }
    //at the end of the using block, the session will be closed automatically
  }
}

This works fine, as long as the user can create more sessions. But what, if the user can’t open more session and you want to get a session anyway?
This works the same as in web interface, you just select which open session you want to replace.
The following method replaces the oldest session in such a case and is therefor the standard way to create sessions with the SmartAPI:

...

using (var session = SessionBuilder.CreateOrReplaceOldestSession(login))
{
  ...
}
//at the end of the using block, the session will be closed automatically

...



If you want to replace a session, but not the oldest one, use the following method.
The second parameter of CreateOrReplaceSession() is a function which gets a list of all available sessions as input and returns the session you want to replace. In the following example a session in which the ‘test’ project is open gets replaced.

...

using (session = SessionBuilder.CreateOrReplaceSession(login,
                                                       sessionInfos =>
                                                       sessionInfos.First(info => info.ProjectName == "test")) )
{
  ...
}
//at the end of the using block, the session will be closed automatically

...

You can access cms servers which also require a windows authentication of the user, too. This is done by setting the associated property of the login object:

...

login.WindowsAuthentication = new NetworkCredential("windowsuser", "windowspassword");
using (var session = SessionBuilder.CreateOrReplaceOldestSession(login))
{
  ...
}
//at the end of the using block, the session will be closed automatically

...

If you have to deal with multiple sessions in your application, it is recommended to set the Name property of the login object, too. You can use it for your internal organization of the sessions and it also is used for the built in logging, so you can easily distinguish which messages/rql commands come from which session.

...

login.Name = "Session for Server 1";
using (var session = SessionBuilder.CreateOrReplaceOldestSession(login))
{
  ...
}
//at the end of the using block, the session will be closed automatically

...

If you want to create a session object for an existing cms session (e.g. when you want to use the SmartAPI for a plugin), use the following method. Note that the session does not get closed by the code. This is the usual behaviour you want in a plugin or something simliar, because otherwise the active user would get logged out once your plugin is done.

...
//url of the cms server
var url = "http://mycmsserver/cms";

//Authentication data can be null, if you want to use an existing session.
//Note that there are some methods however which require the users password to be set,
//e.g. the deletion of keywords. This is stated in the documentation of the according methods.
var login = new ServerLogin(url, null);

Guid loginGuid = ...;
string sessionKey = ...;
Guid projectGuid = ...;
var sessionBuilder = new SessionBuilder(login, loginGuid, sessionKey, projectGuid);

//note that we don't use the using statement because we usually
//do not want to close the running cms session, when we are done (e.g. in a plugin)
var session = sessionBuilder.CreateSession();
...

If you need access to the same session multiple times, you can just store your SessionBuilder object and call CreateSession() on it, when needed.
This is especially usefull in ASP.NET applications where you can store the SessionBuilder in the users ASP.NET session, so you don’t have to retransmit all data on every action the user calls.