See on GitHub

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

    related articlesRelated Articles

    Client API

    Querying

    Home / Docs / Client Api / Session / Opening A Session