Session: Opening a Session

• A Session object is obtained from the Document Store.

• A Session can operate Synchronously or Asynchronously.

  • OpenSession() - Open a Session for a Synchrounous mode of operation.
  • OpenAsyncSession() - Open a Session for Asychrounous mode of operation.

• Various Session options can be configured using the SessionOptions object.

• Be sure to wrap the Session variable with a 'using' statement to ensure proper disposal.

• If no database is specified then the Default Database (stored in the Document Store) is assumed.

• In this page:

  • Syntax
  • Session Options
  • Example

Syntax

OpenSession() / OpenAsyncSession() have three overloads:

• Sync
• Async

// Open a Session for the default database configured in `DocumentStore.Database`
IDocumentSession OpenSession();

// Open a Session for a specified database
IDocumentSession OpenSession(string database);

// Open a Session and pass it a preconfigured SessionOptions object
IDocumentSession OpenSession(SessionOptions options);

// Open a Session for the default database configured in `DocumentStore.Database`
IAsyncDocumentSession OpenAsyncSession();

// Open a Session for a specified database
IAsyncDocumentSession OpenAsyncSession(string database);

// Open a Session and pass it a preconfigured SessionOptions object
IAsyncDocumentSession OpenAsyncSession(SessionOptions options);

Parameter	Type	Description
database	string	The Session will operate on this database, overriding the default database set in the document store
options	SessionOptions	An object with Session configuration options. See details below

Return Value	Description
IDocumentSession / IAsyncDocumentSession	Instance of a Session object

Session Options

The SessionOptions object contains various options to configure the Session's behavior.

Option	Type	Description	Default Value
Database	string	The Session will operate on this database, overriding the Default Database.	null - the Session operates on the Default Database
NoTracking	boolean	Whether the Session should track changes made to all entities that it has either loaded, stored, or queried on. See Disable Tracking Example	false
NoCaching	boolean	Whether the Session should cache the server responses. See Disable Caching Example	false
RequestExecutor	RequestExecutor	(Advanced) The request executor the Session should use	null - the default request executor is used
TransactionMode	TransactionMode	Specify the Session's transaction mode (SingleNode / ClusterWide). See Cluster-Wide Transactions	SingleNode

Example

Here is an example of opening a Session using a SessionOptions object:

• Sync
• Async

using (var store = new DocumentStore())
{
  // Open a Session in synchronous operation mode for cluster-wide transactions

  SessionOptions options = new SessionOptions
  {
      Database = "your_database_name",
      TransactionMode = TransactionMode.ClusterWide
  };

  using (IDocumentSession Session = store.OpenSession(options))
  {
      //   Run your business logic:
      //   
      //   Store documents
      //   Load and Modify documents
      //   Query indexes & collections 
      //   Delete documents
      //   ... etc.

      Session.SaveChanges();
  }
}

using (var store = new DocumentStore())
{
  // Open a Session in asynchronous operation mode for cluster-wide transactions

  SessionOptions options = new SessionOptions
  {
      Database = "your_database_name",
      TransactionMode = TransactionMode.ClusterWide
  };

  using (IAsyncDocumentSession Session = store.OpenAsyncSession(options))
  {
      //   Run your business logic:
      //   
      //   Store documents
      //   Load and Modify documents
      //   Query indexes & collections 
      //   Delete documents
      //   ... etc.

      await Session.SaveChangesAsync();
  }
}