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