Working With Connections and Sessions in ADOMD.NET

New: 5 December 2005

In XML for Analysis (XMLA), sessions provide support for 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 three XMLA session elements when you start a session, perform queries or retrieve data during the session, and close a 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 the SessionID property is set to a valid session ID when the Open method is called, the AdomdConnection object tries to connect to the specified session.

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

Note

After you have had ADOMD.NET create a session, you can connect multiple AdomdConnection objects to that single active session, or you can disconnect a single AdomdConnection object from that session and reconnect that object to another session.

Working in a Session

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

A session ID does not 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

The following example demonstrates how to open a connection, create a session, and close the connection while keeping the session open in ADOMD.NET:

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

See Also

Reference

Establishing Connections in ADOMD.NET

Help and Information

Getting SQL Server 2005 Assistance