DatabaseFacade Class

Definition

Provides access to database related information and operations for a context. Instances of this class are typically obtained from Database and it is not designed to be directly constructed in your application code.

public class DatabaseFacade : Microsoft.EntityFrameworkCore.Infrastructure.IInfrastructure<IServiceProvider>, Microsoft.EntityFrameworkCore.Internal.IDatabaseFacadeDependenciesAccessor
type DatabaseFacade = class
    interface IInfrastructure<IServiceProvider>
    interface IDatabaseFacadeDependenciesAccessor
Public Class DatabaseFacade
Implements IDatabaseFacadeDependenciesAccessor, IInfrastructure(Of IServiceProvider)
Inheritance
DatabaseFacade
Implements
IInfrastructure<IServiceProvider> Microsoft.EntityFrameworkCore.Internal.IDatabaseFacadeDependenciesAccessor

Constructors

DatabaseFacade(DbContext)

Initializes a new instance of the DatabaseFacade class. Instances of this class are typically obtained from Database and it is not designed to be directly constructed in your application code.

Properties

AutoTransactionsEnabled

Gets or sets a value indicating whether or not a transaction will be created automatically by SaveChanges() if none of the 'BeginTransaction' or 'UseTransaction' methods have been called.

Setting this value to false will also disable the IExecutionStrategy for SaveChanges()

The default value is true, meaning that SaveChanges will always use a transaction when saving changes.

Setting this value to false should only be done with caution since the database could be left in a corrupted state if SaveChanges fails.

CurrentTransaction

Gets the current IDbContextTransaction being used by the context, or null if no transaction is in use.

This property will be null unless one of the 'BeginTransaction' or 'UseTransaction' methods has been called, some of which are available as extension methods installed by EF providers. No attempt is made to obtain a transaction from the current DbConnection or similar.

For relational databases, the underlying DbTransaction can be obtained using the 'Microsoft.EntityFrameworkCore.Storage.GetDbTransaction' extension method on the returned IDbContextTransaction.

ProviderName

Returns the name of the database provider currently in use. The name is typically the name of the provider assembly. It is usually easier to use a sugar method such as 'IsSqlServer()' instead of calling this method directly.

This method can only be used after the DbContext has been configured because it is only then that the provider is known. This means that this method cannot be used in OnConfiguring(DbContextOptionsBuilder) because this is where application code sets the provider to use as part of configuring the context.

Methods

BeginTransaction()

Starts a new transaction.

BeginTransactionAsync(CancellationToken)

Asynchronously starts a new transaction.

CanConnect()

Determines whether or not the database is available and can be connected to.

Note that being able to connect to the database does not mean that it is up-to-date with regard to schema creation, etc.

CanConnectAsync(CancellationToken)

Determines whether or not the database is available and can be connected to.

Note that being able to connect to the database does not mean that it is up-to-date with regard to schema creation, etc.

CommitTransaction()

Applies the outstanding operations in the current transaction to the database.

CreateExecutionStrategy()

Creates an instance of the configured IExecutionStrategy.

EnsureCreated()

Ensures that the database for the context exists. If it exists, no action is taken. If it does not exist then the database and all its schema are created. If the database exists, then no effort is made to ensure it is compatible with the model for this context.

Note that this API does not use migrations to create the database. In addition, the database that is created cannot be later updated using migrations. If you are targeting a relational database and using migrations, you can use the DbContext.Database.Migrate() method to ensure the database is created and all migrations are applied.

EnsureCreatedAsync(CancellationToken)

Asynchronously ensures that the database for the context exists. If it exists, no action is taken. If it does not exist then the database and all its schema are created. If the database exists, then no effort is made to ensure it is compatible with the model for this context.

Note that this API does not use migrations to create the database. In addition, the database that is created cannot be later updated using migrations. If you are targeting a relational database and using migrations, you can use the DbContext.Database.Migrate() method to ensure the database is created and all migrations are applied.

EnsureDeleted()

Ensures that the database for the context does not exist. If it does not exist, no action is taken. If it does exist then the database is deleted.

Warning: The entire database is deleted, and no effort is made to remove just the database objects that are used by the model for this context.

EnsureDeletedAsync(CancellationToken)

Asynchronously ensures that the database for the context does not exist. If it does not exist, no action is taken. If it does exist then the database is deleted.

Warning: The entire database is deleted, and no effort is made to remove just the database objects that are used by the model for this context.

Equals(Object)

Determines whether the specified object is equal to the current object.

GetHashCode()

Serves as the default hash function.

RollbackTransaction()

Discards the outstanding operations in the current transaction.

ToString()

Returns a string that represents the current object.

Explicit Interface Implementations

IDatabaseFacadeDependenciesAccessor.Context

This is an internal API that supports the Entity Framework Core infrastructure and not subject to the same compatibility standards as public APIs. It may be changed or removed without notice in any release. You should only use it directly in your code with extreme caution and knowing that doing so can result in application failures when updating to a new Entity Framework Core release.

IDatabaseFacadeDependenciesAccessor.Dependencies

This is an internal API that supports the Entity Framework Core infrastructure and not subject to the same compatibility standards as public APIs. It may be changed or removed without notice in any release. You should only use it directly in your code with extreme caution and knowing that doing so can result in application failures when updating to a new Entity Framework Core release.

IInfrastructure<IServiceProvider>.Instance

Gets the scoped IServiceProvider being used to resolve services.

This property is intended for use by extension methods that need to make use of services not directly exposed in the public API surface.

Extension Methods

GetCosmosClient(DatabaseFacade)

Gets the underlying CosmosClient for this DbContext.

IsCosmos(DatabaseFacade)

Returns true if the database provider currently in use is the Cosmos provider.

This method can only be used after the DbContext has been configured because it is only then that the provider is known. This means that this method cannot be used in OnConfiguring(DbContextOptionsBuilder) because this is where application code sets the provider to use as part of configuring the context.

GetInfrastructure<T>(IInfrastructure<T>)

Gets the value from a property that is being hidden using IInfrastructure<T>.

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

IInfrastructure<T> is used to hide properties that are not intended to be used in application code but can be used in extension methods written by database providers etc.

IsInMemory(DatabaseFacade)

Returns true if the database provider currently in use is the in-memory provider.

This method can only be used after the DbContext has been configured because it is only then that the provider is known. This means that this method cannot be used in OnConfiguring(DbContextOptionsBuilder) because this is where application code sets the provider to use as part of configuring the context.

BeginTransaction(DatabaseFacade, IsolationLevel)

Starts a new transaction with a given IsolationLevel.

BeginTransactionAsync(DatabaseFacade, IsolationLevel, CancellationToken)

Asynchronously starts a new transaction with a given IsolationLevel.

CloseConnection(DatabaseFacade)

Closes the underlying DbConnection.

CloseConnectionAsync(DatabaseFacade)

Closes the underlying DbConnection.

ExecuteSqlCommand(DatabaseFacade, RawSqlString, IEnumerable<Object>)

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter. You can also consider using ExecuteSqlInterpolated to use interpolated string syntax to create parameters.

ExecuteSqlCommand(DatabaseFacade, RawSqlString, Object[])

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter -

context.Database.ExecuteSqlCommand("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)
. You can also consider using ExecuteSqlInterpolated to use interpolated string syntax to create parameters.

ExecuteSqlCommand(DatabaseFacade, FormattableString)

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter -

context.Database.ExecuteSqlCommand($"SELECT * FROM [dbo].[SearchBlogs]({userSuppliedSearchTerm})")
.

ExecuteSqlCommand(DatabaseFacade, String, Object[])
ExecuteSqlCommandAsync(DatabaseFacade, RawSqlString, IEnumerable<Object>, CancellationToken)

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter. You can also consider using ExecuteSqlInterpolated to use interpolated string syntax to create parameters.

ExecuteSqlCommandAsync(DatabaseFacade, RawSqlString, Object[])

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter -

context.Database.ExecuteSqlCommandAsync("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)
. You can also consider using ExecuteSqlInterpolated to use interpolated string syntax to create parameters.

ExecuteSqlCommandAsync(DatabaseFacade, RawSqlString, CancellationToken)

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter -

context.Database.ExecuteSqlCommandAsync("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)
.

ExecuteSqlCommandAsync(DatabaseFacade, FormattableString, CancellationToken)

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter -

context.Database.ExecuteSqlCommandAsync($"SELECT * FROM [dbo].[SearchBlogs]({userSuppliedSearchTerm})")
.

ExecuteSqlCommandAsync(DatabaseFacade, String, CancellationToken, Object[])
ExecuteSqlInterpolated(DatabaseFacade, FormattableString)

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter -

context.Database.ExecuteSqlInterpolated($"SELECT * FROM [dbo].[SearchBlogs]({userSuppliedSearchTerm})")
.

ExecuteSqlInterpolatedAsync(DatabaseFacade, FormattableString, CancellationToken)

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter -

context.Database.ExecuteSqlInterpolatedAsync($"SELECT * FROM [dbo].[SearchBlogs]({userSuppliedSearchTerm})")
.

ExecuteSqlRaw(DatabaseFacade, String, IEnumerable<Object>)

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter. You can also consider using ExecuteSqlInterpolated to use interpolated string syntax to create parameters.

ExecuteSqlRaw(DatabaseFacade, String, Object[])

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter -

context.Database.ExecuteSqlRaw("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)
. You can also consider using ExecuteSqlInterpolated to use interpolated string syntax to create parameters.

ExecuteSqlRawAsync(DatabaseFacade, String, IEnumerable<Object>, CancellationToken)

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter. You can also consider using ExecuteSqlInterpolated to use interpolated string syntax to create parameters.

ExecuteSqlRawAsync(DatabaseFacade, String, Object[])

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter -

context.Database.ExecuteSqlRawAsync("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)
. You can also consider using ExecuteSqlInterpolated to use interpolated string syntax to create parameters.

ExecuteSqlRawAsync(DatabaseFacade, String, CancellationToken)

Executes the given SQL against the database and returns the number of rows affected.

Note that this method does not start a transaction. To use this method with a transaction, first call BeginTransaction(DatabaseFacade, IsolationLevel) or UseTransaction(DatabaseFacade, DbTransaction).

Note that the current ExecutionStrategy is not used by this method since the SQL may not be idempotent and does not run in a transaction. An ExecutionStrategy can be used explicitly, making sure to also use a transaction if the SQL is not idempotent.

GenerateCreateScript(DatabaseFacade)

Generates a script to create all tables for the current model.

GetAppliedMigrations(DatabaseFacade)

Gets all migrations that have been applied to the target database.

GetAppliedMigrationsAsync(DatabaseFacade, CancellationToken)

Asynchronously gets all migrations that have been applied to the target database.

GetCommandTimeout(DatabaseFacade)

Returns the timeout (in seconds) set for commands executed with this DbContext.

Note that the command timeout is distinct from the connection timeout, which is commonly set on the database connection string.

GetDbConnection(DatabaseFacade)

Gets the underlying ADO.NET DbConnection for this DbContext.

GetMigrations(DatabaseFacade)

Gets all the migrations that are defined in the configured migrations assembly.

GetPendingMigrations(DatabaseFacade)

Gets all migrations that are defined in the assembly but haven't been applied to the target database.

GetPendingMigrationsAsync(DatabaseFacade, CancellationToken)

Asynchronously gets all migrations that are defined in the assembly but haven't been applied to the target database.

Migrate(DatabaseFacade)

Applies any pending migrations for the context to the database. Will create the database if it does not already exist.

Note that this API is mutually exclusive with DbContext.Database.EnsureCreated(). EnsureCreated does not use migrations to create the database and therefore the database that is created cannot be later updated using migrations.

MigrateAsync(DatabaseFacade, CancellationToken)

Asynchronously applies any pending migrations for the context to the database. Will create the database if it does not already exist.

Note that this API is mutually exclusive with DbContext.Database.EnsureCreated(). EnsureCreated does not use migrations to create the database and therefore the database that is created cannot be later updated using migrations.

OpenConnection(DatabaseFacade)

Opens the underlying DbConnection.

OpenConnectionAsync(DatabaseFacade, CancellationToken)

Opens the underlying DbConnection.

SetCommandTimeout(DatabaseFacade, Nullable<Int32>)

Sets the timeout (in seconds) to use for commands executed with this DbContext.

Note that the command timeout is distinct from the connection timeout, which is commonly set on the database connection string.

SetCommandTimeout(DatabaseFacade, TimeSpan)

Sets the timeout to use for commands executed with this DbContext.

Note that the command timeout is distinct from the connection timeout, which is commonly set on the database connection string.

UseTransaction(DatabaseFacade, DbTransaction)

Sets the DbTransaction to be used by database operations on the DbContext.

UseTransactionAsync(DatabaseFacade, DbTransaction, CancellationToken)

Sets the DbTransaction to be used by database operations on the DbContext.

IsSqlite(DatabaseFacade)

Returns true if the database provider currently in use is the SQLite provider.

This method can only be used after the DbContext has been configured because it is only then that the provider is known. This means that this method cannot be used in OnConfiguring(DbContextOptionsBuilder) because this is where application code sets the provider to use as part of configuring the context.

IsSqlServer(DatabaseFacade)

Returns true if the database provider currently in use is the SQL Server provider.

This method can only be used after the DbContext has been configured because it is only then that the provider is known. This means that this method cannot be used in OnConfiguring(DbContextOptionsBuilder) because this is where application code sets the provider to use as part of configuring the context.

EnlistTransaction(DatabaseFacade, Transaction)

Specifies an existing Transaction to be used for database operations.

GetEnlistedTransaction(DatabaseFacade)

Returns the currently enlisted transaction.

Applies to