Connections in ADOMD.NET - Working with Connections and Sessions

In XML for Analysis (XMLA), sessions support stateful operations during analytical data access. Sessions frame the scope and context of commands and transactions for an analytical data source. The XMLA elements used to manage sessions are BeginSession, Session, and EndSession.

ADOMD.NET uses these XMLA session elements to start a session, run queries or retrieve data, and close the session.

Starting a session

The SessionID property of the AdomdConnection object contains the identifier of the active session associated with the AdomdConnection object. By using this property correctly, you can effectively control both client and server statefulness in your application:

• If the SessionID property is not set to a valid session ID when the Open method is called, the AdomdConnection object requests a new session ID from the provider. ADOMD.NET initiates a session by sending an XMLA BeginSession header to the provider. If ADOMD.NET is successful is starting a session, ADOMD.NET sets the value of the SessionID property to the session ID of the newly created session.

• If an application sets the SessionID property to a valid session ID before calling the Open method, the AdomdConnection object tries to connect to that session.

If the AdomdConnection object cannot connect to the specified session, or if the provider does not support sessions, an exception is thrown.

Working in a session

After ADOMD.NET connects the AdomdConnection object to a valid session, ADOMD.NET sends an XMLA Session header to the provider with every application request for data or metadata. Every request has the session ID set to the value of the SessionID property.

A session ID doesn't guarantee that a session remains valid. If the session expires (for example, if the session times out or the connection is lost), the provider can choose to end and roll back the actions of that session. If this occurs, all subsequent method calls from the AdomdConnection object will throw an exception. Because exceptions are thrown only when the next request is sent to the provider, not when the session expires, your application must be able to handle these exceptions any time that your application retrieves data or metadata from the provider.

Closing a session

If the Close method is called without specifying the value of the endSession parameter, or if the endSession parameter is set to True, both the connection to the session and the session associated with the AdomdConnection object are closed. To close a session, ADOMD.NET sends an XMLA EndSession header to the provider, with the session ID set to the value of the SessionID property.

If the Close method is called with the endSession parameter set to False, the session associated with the AdomdConnection object remains active but the connection to the session is closed.

Example of managing a session

This ADOMD.NET example opens a connection, creates a session, and closes the connection without closing the session:

Public Function CreateSession(ByVal connectionString As String) As String  
    Dim strSessionID As String = ""  
    Dim objConnection As New AdomdConnection  
  
    Try  
        ' First, try to connect to the specified data source.  
        ' If the connection string is not valid, or if the specified  
        ' provider does not support sessions, an exception is thrown.  
        objConnection.ConnectionString = connectionString  
        objConnection.Open()  
  
        ' Now that the connection is open, retrieve the new  
        ' active session ID.  
        strSessionID = objConnection.SessionID  
        ' Close the connection, but leave the session open.  
        objConnection.Close(False)  
        Return strSessionID  
  
    Finally  
        objConnection = Nothing  
    End Try  
End Function  

static string CreateSession(string connectionString)  
{  
    string strSessionID = "";  
    AdomdConnection objConnection = new AdomdConnection();  
    try  
    {  
        /*First, try to connect to the specified data source.  
          If the connection string is not valid, or if the specified  
          provider does not support sessions, an exception is thrown. */  
        objConnection.ConnectionString = connectionString;  
        objConnection.Open();  
  
        // Now that the connection is open, retrieve the new  
        // active session ID.  
        strSessionID = objConnection.SessionID;  
        // Close the connection, but leave the session open.  
        objConnection.Close(false);  
        return strSessionID;  
    }  
    finally  
    {  
        objConnection = null;  
    }  
}