Table of Contents

Class RelationalConnection

Namespace
Microsoft.EntityFrameworkCore.Storage
Assembly
Microsoft.EntityFrameworkCore.Relational.dll

Represents a connection with a relational database.

This type is typically used by database providers (and other extensions). It is generally not used in application code.

The service lifetime is Scoped. This means that each Microsoft.EntityFrameworkCore.DbContext instance will use its own instance of this service. The implementation may depend on other services registered with any lifetime. The implementation does not need to be thread-safe. 

public abstract class RelationalConnection : IRelationalConnection, IRelationalTransactionManager, IDbContextTransactionManager, IResettableService, IDisposable, IAsyncDisposable, ITransactionEnlistmentManager
Inheritance
RelationalConnection
Implements
IDbContextTransactionManager
IResettableService
ITransactionEnlistmentManager
Inherited Members

Constructors

RelationalConnection(RelationalConnectionDependencies)

Initializes a new instance of the RelationalConnection class.

protected RelationalConnection(RelationalConnectionDependencies dependencies)

Parameters

dependencies RelationalConnectionDependencies

Parameter object containing dependencies for this service.

Properties

CommandTimeout

Gets the timeout for executing a command against the database.

public virtual int? CommandTimeout { get; set; }

Property Value

int?

ConnectionId

The unique identifier for this connection.

public virtual Guid ConnectionId { get; }

Property Value

Guid

ConnectionString

Gets or sets the connection string for the database.

public virtual string ConnectionString { get; set; }

Property Value

string

Context

The Microsoft.EntityFrameworkCore.DbContext currently in use, or null if not known.

public virtual DbContext Context { get; }

Property Value

DbContext

CurrentTransaction

Gets the current transaction.

public virtual IDbContextTransaction CurrentTransaction { get; protected set; }

Property Value

IDbContextTransaction

DbConnection

Gets or sets the underlying DbConnection used to connect to the database.

The connection can only be changed when the existing connection, if any, is not open.

Note that a connection set must be disposed by application code since it was not created by Entity Framework. 

public virtual DbConnection DbConnection { get; set; }

Property Value

DbConnection

Dependencies

Parameter object containing service dependencies.

protected virtual RelationalConnectionDependencies Dependencies { get; }

Property Value

RelationalConnectionDependencies

EnlistedTransaction

The currently enlisted transaction.

public virtual Transaction EnlistedTransaction { get; protected set; }

Property Value

Transaction

Semaphore

Gets a semaphore used to serialize access to this connection.

[Obsolete("EF Core no longer uses this semaphore. It will be removed in an upcoming release.")]
public virtual SemaphoreSlim Semaphore { get; }

Property Value

SemaphoreSlim

The semaphore used to serialize access to this connection.

SupportsAmbientTransactions

Indicates whether the store connection supports ambient transactions

protected virtual bool SupportsAmbientTransactions { get; }

Property Value

bool

Methods

BeginTransaction()

Begins a new transaction.

public virtual IDbContextTransaction BeginTransaction()

Returns

IDbContextTransaction

The newly created transaction.

BeginTransaction(IsolationLevel)

Begins a new transaction.

public virtual IDbContextTransaction BeginTransaction(IsolationLevel isolationLevel)

Parameters

isolationLevel IsolationLevel

The isolation level to use for the transaction.

Returns

IDbContextTransaction

The newly created transaction.

BeginTransactionAsync(IsolationLevel, CancellationToken)

Asynchronously begins a new transaction.

public virtual Task<IDbContextTransaction> BeginTransactionAsync(IsolationLevel isolationLevel, CancellationToken cancellationToken = default)

Parameters

isolationLevel IsolationLevel

The isolation level to use for the transaction.

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the task to complete.

Returns

Task<IDbContextTransaction>

A task that represents the asynchronous operation. The task result contains the newly created transaction.

BeginTransactionAsync(CancellationToken)

Asynchronously begins a new transaction.

public virtual Task<IDbContextTransaction> BeginTransactionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the task to complete.

Returns

Task<IDbContextTransaction>

A task that represents the asynchronous operation. The task result contains the newly created transaction.

Close()

Closes the connection to the database.

public virtual bool Close()

Returns

bool

true if the underlying connection was actually closed; false otherwise.

CloseAsync()

Closes the connection to the database.

public virtual Task<bool> CloseAsync()

Returns

Task<bool>

A task that represents the asynchronous operation, with a value of true if the connection was actually closed.

CommitTransaction()

Commits all changes made to the database in the current transaction.

public virtual void CommitTransaction()

CommitTransactionAsync(CancellationToken)

Commits all changes made to the database in the current transaction.

public virtual Task CommitTransactionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the task to complete.

Returns

Task

A Task representing the asynchronous operation.

CreateDbConnection()

Creates a DbConnection to the database.

protected abstract DbConnection CreateDbConnection()

Returns

DbConnection

The connection.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public virtual void Dispose()

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public virtual ValueTask DisposeAsync()

Returns

ValueTask

EnlistTransaction(Transaction)

Specifies an existing Transaction to be used for database operations.

public virtual void EnlistTransaction(Transaction transaction)

Parameters

transaction Transaction

The transaction to be used.

GetValidatedConnectionString()

Returns the configured connection string only if it has been set or a valid DbConnection exists.

protected virtual string GetValidatedConnectionString()

Returns

string

The connection string.

Exceptions

InvalidOperationException

when connection string cannot be obtained.

Open(bool)

Opens the connection to the database.

public virtual bool Open(bool errorsExpected = false)

Parameters

errorsExpected bool

Indicates if the connection errors are expected and should be logged as debug message.

Returns

bool

true if the underlying connection was actually opened; false otherwise.

OpenAsync(CancellationToken, bool)

Asynchronously opens the connection to the database.

public virtual Task<bool> OpenAsync(CancellationToken cancellationToken, bool errorsExpected = false)

Parameters

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the task to complete.

errorsExpected bool

Indicate if the connection errors are expected and should be logged as debug message.

Returns

Task<bool>

A task that represents the asynchronous operation, with a value of true if the connection was actually opened.

OpenDbConnection(bool)

Template method that by default calls Open() but can be overriden by providers to make a different call instead.

protected virtual void OpenDbConnection(bool errorsExpected)

Parameters

errorsExpected bool

Indicates if the connection errors are expected and should be logged as debug message.

OpenDbConnectionAsync(bool, CancellationToken)

Template method that by default calls OpenAsync() but can be overriden by providers to make a different call instead.

protected virtual Task OpenDbConnectionAsync(bool errorsExpected, CancellationToken cancellationToken)

Parameters

errorsExpected bool

Indicates if the connection errors are expected and should be logged as debug message.

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the task to complete.

Returns

Task

RollbackTransaction()

Discards all changes made to the database in the current transaction.

public virtual void RollbackTransaction()

RollbackTransactionAsync(CancellationToken)

Discards all changes made to the database in the current transaction.

public virtual Task RollbackTransactionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the task to complete.

Returns

Task

A Task representing the asynchronous operation.

UseTransaction(DbTransaction)

Specifies an existing DbTransaction to be used for database operations.

public virtual IDbContextTransaction UseTransaction(DbTransaction transaction)

Parameters

transaction DbTransaction

The transaction to be used.

Returns

IDbContextTransaction

An instance of IDbTransaction that wraps the provided transaction.

UseTransaction(DbTransaction, Guid)

Specifies an existing DbTransaction to be used for database operations.

public virtual IDbContextTransaction UseTransaction(DbTransaction transaction, Guid transactionId)

Parameters

transaction DbTransaction

The transaction to be used.

transactionId Guid

The unique identifier for the transaction.

Returns

IDbContextTransaction

An instance of IDbTransaction that wraps the provided transaction.

UseTransactionAsync(DbTransaction, Guid, CancellationToken)

Specifies an existing DbTransaction to be used for database operations.

public virtual Task<IDbContextTransaction> UseTransactionAsync(DbTransaction transaction, Guid transactionId, CancellationToken cancellationToken = default)

Parameters

transaction DbTransaction

The transaction to be used.

transactionId Guid

The unique identifier for the transaction.

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the task to complete.

Returns

Task<IDbContextTransaction>

An instance of IDbTransaction that wraps the provided transaction.

UseTransactionAsync(DbTransaction, CancellationToken)

Specifies an existing DbTransaction to be used for database operations.

public virtual Task<IDbContextTransaction> UseTransactionAsync(DbTransaction transaction, CancellationToken cancellationToken = default)

Parameters

transaction DbTransaction

The transaction to be used.

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the task to complete.

Returns

Task<IDbContextTransaction>

An instance of IDbTransaction that wraps the provided transaction.