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

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

// 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:

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