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