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. 

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

Remarks

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.

See Implementation of database providers and extensions for more information and examples.

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.

public virtual DbContext Context { get; }

Property Value

DbContext

CurrentAmbientTransaction

The current ambient transaction. Defaults to Current.

public virtual Transaction? CurrentAmbientTransaction { get; }

Property Value

Transaction

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.

public virtual DbConnection DbConnection { get; set; }

Property Value

DbConnection

Remarks

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.

Dependencies

Relational provider-specific dependencies for this service.

protected virtual RelationalConnectionDependencies Dependencies { get; }

Property Value

RelationalConnectionDependencies

EnlistedTransaction

The currently enlisted transaction.

public virtual Transaction? EnlistedTransaction { get; protected set; }

Property Value

Transaction

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.

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

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.

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

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.

CloseDbConnection()

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

protected virtual void CloseDbConnection()

CloseDbConnectionAsync()

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

protected virtual Task CloseDbConnectionAsync()

Returns

Task

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.

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

ConnectionBeginTransaction(IsolationLevel)

Template method that by default calls BeginDbTransaction(IsolationLevel) but can be overridden by providers to make a different call instead.

protected virtual DbTransaction ConnectionBeginTransaction(IsolationLevel isolationLevel)

Parameters

isolationLevel IsolationLevel

The isolation level to use for the transaction.

Returns

DbTransaction

The newly created transaction.

ConnectionBeginTransactionAsync(IsolationLevel, CancellationToken)

Template method that by default calls BeginDbTransactionAsync(IsolationLevel, CancellationToken) but can be overridden by providers to make a different call instead.

protected virtual ValueTask<DbTransaction> ConnectionBeginTransactionAsync(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

ValueTask<DbTransaction>

The newly created transaction.

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

ConnectionEnlistTransaction(Transaction?)

Template method that by default calls EnlistTransaction(Transaction) but can be overridden by providers to make a different call instead.

protected virtual void ConnectionEnlistTransaction(Transaction? transaction)

Parameters

transaction Transaction

The transaction to be used.

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

DisposeDbConnection()

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

protected virtual void DisposeDbConnection()

DisposeDbConnectionAsync()

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

protected virtual ValueTask DisposeDbConnectionAsync()

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.

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

OpenDbConnection(bool)

Template method that by default calls Open() but can be overridden 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 but can be overridden 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

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

RentCommand()

Rents a relational command that can be executed with this connection.

public virtual IRelationalCommand RentCommand()

Returns

IRelationalCommand

A relational command that can be executed with this connection.

ResetState(bool)

Resets the connection state. Called by Dispose() and Microsoft.EntityFrameworkCore.Infrastructure.IResettableService.ResetState.

protected virtual void ResetState(bool disposeDbConnection)

Parameters

disposeDbConnection bool

Whether the underlying DbConnection should be disposed, assuming it is owned by this RelationalConnection. If false, the existing DbConnection may get reused.

ResetStateAsync(bool)

Resets the connection state. Called by DisposeAsync() and Microsoft.EntityFrameworkCore.Infrastructure.IResettableService.ResetStateAsync(System.Threading.CancellationToken).

protected virtual ValueTask ResetStateAsync(bool disposeDbConnection)

Parameters

disposeDbConnection bool

Whether the underlying DbConnection should be disposed, assuming it is owned by this RelationalConnection. If false, the existing DbConnection may get reused.

Returns

ValueTask

ReturnCommand(IRelationalCommand)

Returns a relational command to this connection, so that it can be reused in the future.

public virtual void ReturnCommand(IRelationalCommand command)

Parameters

command IRelationalCommand

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.

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

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 Microsoft.EntityFrameworkCore.Storage.IDbContextTransaction that wraps the provided transaction, or null if transaction is null.

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.

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

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.

Exceptions

OperationCanceledException

If the CancellationToken is canceled.