Open a Session

• A Session object is obtained from the Document Store.

• A Session can operate Synchronously or Asynchronously.

  • OpenSession() - Open a Session for a Synchronous mode of operation.
  • OpenAsyncSession() - Open a Session for Asynchronous mode of operation.

• Various Session options can be configured using the SessionOptions object.
  If no database is specified in the options then the Default Database (stored in the Document Store) is assumed.

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

• In this page:

  • Syntax
  • Session options
  • Open session example

Syntax

• Use OpenSession() / OpenAsyncSession() to open a session from the Document Store.
• The following overloads are available:

• 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	bool	true - The Session tracks changes made to all entities it loaded, stored, or queried for. false - Tracking will be turned off. Learn more in Disable tracking	false
NoCaching	bool	true - Server responses will Not be cached. false - The Session caches the server responses. Learn more in Disable caching	false
RequestExecutor	RequestExecutor	( Advanced option ) The request executor the Session should use.	null - the default request executor is used
TransactionMode	TransactionMode	Specify the Session's transaction mode SingleNode / ClusterWide Learn more in Cluster-wide vs. Single-node	SingleNode

• Experts Only:

Option	Type	Description	Default Value
DisableAtomicDocumentWrites- InClusterWideTransaction	bool?	( Experts only ) true - Disable Atomic-Guards in cluster-wide sessions. false - Automatic atomic writes in cluster-wide sessions are enabled. Learn more in Atomic-Guards	false

Open session example

• The following example opens a cluster-wide Session:

• Sync
• Async

using (var store = new DocumentStore())
{
  // Define the Session's options object
  SessionOptions options = new SessionOptions
  {
      Database = "your_database_name",
      TransactionMode = TransactionMode.ClusterWide
  };

  // Open the Session in a Synchronous mode
  // Pass the options object to the session
  using (IDocumentSession session = store.OpenSession(options))
  {
      //   Run your business logic:
      //   
      //   Store entities
      //   Load and Modify entities
      //   Query indexes & collections 
      //   Delete entities
      //   ... etc.

      session.SaveChanges();
      // When 'SaveChanges' returns successfully,
      // all changes made to the entities in the session are persisted to the documents in the database
  }
}

using (var store = new DocumentStore())
{
  // Define the Session's options object
  SessionOptions options = new SessionOptions
  {
      Database = "your_database_name",
      TransactionMode = TransactionMode.ClusterWide
  };

  // Open the Session in an Asynchronous mode
  // Pass the options object to the session
  using (IAsyncDocumentSession asyncSession = store.OpenAsyncSession(options))
  {
      //   Run your business logic:
      //   
      //   Store entities
      //   Load and Modify documentitiesents
      //   Query indexes & collections 
      //   Delete documents
      //   ... etc.

      await asyncSession.SaveChangesAsync();
      // When 'SaveChanges' returns successfully,
      // all changes made to the entities in the session are persisted to the documents in the database
  }
}