From 2be33b19ed17ad92331d2833c63c7a15955fc14a Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Sat, 28 Feb 2026 08:44:49 +0100 Subject: [PATCH] Add missing documentation for interceptors (#5279) Closes #4417 Closes #4726 --- .../interceptors.md | 604 +++++++++++++++++- .../core/what-is-new/ef-core-6.0/whatsnew.md | 9 +- .../core/what-is-new/ef-core-7.0/whatsnew.md | 535 ++-------------- .../NewInEFCore6/CommandSourceSample.cs | 71 -- .../Miscellaneous/NewInEFCore6/Program.cs | 1 - .../NewInEFCore7/InjectLoggerSample.cs | 113 ---- .../LazyConnectionStringSample.cs | 119 ---- ...OptimisticConcurrencyInterceptionSample.cs | 90 --- .../Miscellaneous/NewInEFCore7/Program.cs | 10 - .../NewInEFCore7/QueryInterceptionSample.cs | 138 ---- .../QueryStatisticsLoggerSample.cs | 135 ---- 11 files changed, 664 insertions(+), 1161 deletions(-) delete mode 100644 samples/core/Miscellaneous/NewInEFCore6/CommandSourceSample.cs delete mode 100644 samples/core/Miscellaneous/NewInEFCore7/InjectLoggerSample.cs delete mode 100644 samples/core/Miscellaneous/NewInEFCore7/LazyConnectionStringSample.cs delete mode 100644 samples/core/Miscellaneous/NewInEFCore7/OptimisticConcurrencyInterceptionSample.cs delete mode 100644 samples/core/Miscellaneous/NewInEFCore7/QueryInterceptionSample.cs delete mode 100644 samples/core/Miscellaneous/NewInEFCore7/QueryStatisticsLoggerSample.cs diff --git a/entity-framework/core/logging-events-diagnostics/interceptors.md b/entity-framework/core/logging-events-diagnostics/interceptors.md index cd50d052bf..46bc091a44 100644 --- a/entity-framework/core/logging-events-diagnostics/interceptors.md +++ b/entity-framework/core/logging-events-diagnostics/interceptors.md @@ -2,7 +2,7 @@ title: Interceptors - EF Core description: Interception for database operations and other events author: SamMonoRT -ms.date: 11/15/2021 +ms.date: 02/26/2026 uid: core/logging-events-diagnostics/interceptors ms.custom: sfi-ropc-nochange --- @@ -15,6 +15,20 @@ Interceptors are different from logging and diagnostics in that they allow modif Interceptors are registered per DbContext instance when the context is configured. Use a [diagnostic listener](xref:core/logging-events-diagnostics/diagnostic-listeners) to get the same information but for all DbContext instances in the process. +## Available interceptors + +The following table shows the available interceptor interfaces: + +| Interceptor | Operations intercepted | [Singleton](#singleton-interceptors) | +|:--------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------:| +| | Creating commands
Executing commands
Command failures
Disposing the command's DbDataReader | No | +| | Opening and closing connections
Creating connections
Connection failures | No | +| | Creating transactions
Using existing transactions
Committing transactions
Rolling back transactions
Creating and using savepoints
Transaction failures | No | +| | SavingChanges/SavedChanges
SaveChangesFailed
Optimistic concurrency handling | No | +| | Creating, initializing, and finalizing entity instances from query results | Yes | +| | Modifying the LINQ expression tree before a query is compiled | Yes | +| | Resolving identity conflicts when tracking entities | Yes | + ## Registering interceptors Interceptors are registered using when [configuring a DbContext instance](xref:core/dbcontext-configuration/index). This is commonly done in an override of . For example: @@ -49,6 +63,48 @@ public class TaggedQueryCommandInterceptorContext : BlogsContext Every interceptor instance must implement one or more interface derived from . Each instance should only be registered once even if it implements multiple interception interfaces; EF Core will route events for each interface as appropriate. +### Singleton interceptors + +Some interceptors implement (see table above); these interceptors are registered as singleton services in EF Core's internal service provider, meaning a single instance is shared across all `DbContext` instances that use the same service provider. + +Because singleton interceptors become part of EF Core's internal service configuration, each distinct interceptor instance causes a new internal service provider to be built. Passing a **new instance** of a singleton interceptor each time a `DbContext` is configured--for example, in `AddDbContext`--will eventually trigger a `ManyServiceProvidersCreatedWarning` and degrade performance. + +> [!WARNING] +> Always reuse the same singleton interceptor instance for all `DbContext` instances. Do not create a new instance each time the context is configured. + +For example, the following is **incorrect** because a new interceptor instance is created for each context configuration: + +```csharp +// Don't do this! A new instance each time causes a new internal service provider to be built. +services.AddDbContext( + b => b.UseSqlServer(connectionString) + .AddInterceptors(new MyMaterializationInterceptor())); +``` + +Instead, reuse the same instance: + +```csharp +// Correct: reuse a single interceptor instance +var interceptor = new MyMaterializationInterceptor(); +services.AddDbContext( + b => b.UseSqlServer(connectionString) + .AddInterceptors(interceptor)); +``` + +Or use a static field: + +```csharp +public class CustomerContext : DbContext +{ + private static readonly MyMaterializationInterceptor _interceptor = new(); + + protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) + => optionsBuilder.AddInterceptors(_interceptor); +} +``` + +Because these interceptors are singletons, they must be thread-safe. They should generally not hold mutable state. If you need to access scoped services (such as the current `DbContext`), use the or similar properties on the event data passed to each interceptor method. + ## Database interception > [!NOTE] @@ -59,7 +115,7 @@ Low-level database interception is split into the three interfaces shown in the | Interceptor | Database operations intercepted |:-----------------------------------------------------------------------|------------------------------------------------- | | Creating commands
Executing commands
Command failures
Disposing the command's DbDataReader -| | Opening and closing connections
Connection failures +| | Opening and closing connections
Creating connections
Connection failures | | Creating transactions
Using existing transactions
Committing transactions
Rolling back transactions
Creating and using savepoints
Transaction failures The base classes , , and contain no-op implementations for each method in the corresponding interface. Use the base classes to avoid the need to implement unused interception methods. @@ -185,6 +241,91 @@ public class AadAuthenticationInterceptor : DbConnectionInterceptor > [!WARNING] > in some situations the access token may not be cached automatically the Azure Token Provider. Depending on the kind of token requested, you may need to implement your own caching here. +### Example: Lazy initialization of a connection string + +Connection strings are often static assets read from a configuration file. These can easily be passed to `UseSqlServer` or similar when configuring a `DbContext`. However, sometimes the connection string can change for each context instance. For example, each tenant in a multi-tenant system may have a different connection string. + +An can be used to handle dynamic connections and connection strings. This starts with the ability to configure the `DbContext` without any connection string. For example: + +```csharp +services.AddDbContext( + b => b.UseSqlServer()); +``` + +One of the `IDbConnectionInterceptor` methods can then be implemented to configure the connection before it is used. `ConnectionOpeningAsync` is a good choice, since it can perform an async operation to obtain the connection string, find an access token, and so on. For example, imagine a service scoped to the current request that understands the current tenant: + +```csharp +services.AddScoped(); +``` + +> [!WARNING] +> Performing an asynchronous lookup for a connection string, access token, or similar every time it is needed can be very slow. Consider caching these things and only refreshing the cached string or token periodically. For example, access tokens can often be used for a significant period of time before needing to be refreshed. + +This can be injected into each `DbContext` instance using constructor injection: + +```csharp +public class CustomerContext : DbContext +{ + private readonly ITenantConnectionStringFactory _connectionStringFactory; + + public CustomerContext( + DbContextOptions options, + ITenantConnectionStringFactory connectionStringFactory) + : base(options) + { + _connectionStringFactory = connectionStringFactory; + } + + // ... +} +``` + +This service is then used when constructing the interceptor implementation for the context: + +```csharp +protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) + => optionsBuilder.AddInterceptors( + new ConnectionStringInitializationInterceptor(_connectionStringFactory)); +``` + +Finally, the interceptor uses this service to obtain the connection string asynchronously and set it the first time that the connection is used: + +```csharp +public class ConnectionStringInitializationInterceptor : DbConnectionInterceptor +{ + private readonly ITenantConnectionStringFactory _connectionStringFactory; + + public ConnectionStringInitializationInterceptor(ITenantConnectionStringFactory connectionStringFactory) + { + _connectionStringFactory = connectionStringFactory; + } + + public override InterceptionResult ConnectionOpening( + DbConnection connection, + ConnectionEventData eventData, + InterceptionResult result) + => throw new NotSupportedException("Synchronous connections not supported."); + + public override async ValueTask ConnectionOpeningAsync( + DbConnection connection, ConnectionEventData eventData, InterceptionResult result, + CancellationToken cancellationToken = new()) + { + if (string.IsNullOrEmpty(connection.ConnectionString)) + { + connection.ConnectionString = (await _connectionStringFactory.GetConnectionStringAsync(cancellationToken)); + } + + return result; + } +} +``` + +> [!NOTE] +> The connection string is only obtained the first time that a connection is used. After that, the connection string stored on the `DbConnection` will be used without looking up a new connection string. + +> [!TIP] +> This interceptor overrides the non-async `ConnectionOpening` method to throw since the service to get the connection string must be called from an async code path. + ### Example: Advanced command interception for caching > [!TIP] @@ -388,6 +529,78 @@ Free beer for unicorns Notice from the log output that the application continues to use the cached message until the timeout expires, at which point the database is queried again for any new message. +### Example: Logging SQL Server query statistics + +This example shows two interceptors that work together to send SQL Server query statistics to the application log. To generate the statistics, we need an to do two things. + +First, the interceptor will prefix commands with `SET STATISTICS IO ON`, which tells SQL Server to send statistics to the client after a result set has been consumed: + +```csharp +public override ValueTask> ReaderExecutingAsync( + DbCommand command, + CommandEventData eventData, + InterceptionResult result, + CancellationToken cancellationToken = default) +{ + command.CommandText = "SET STATISTICS IO ON;" + Environment.NewLine + command.CommandText; + + return new(result); +} +``` + +Second, the interceptor will implement the `DataReaderClosingAsync` method, which is called after the has finished consuming results, but _before_ it has been closed. When SQL Server is sending statistics, it puts them in a second result on the reader, so at this point the interceptor reads that result by calling `NextResultAsync` which populates statistics onto the connection. + +```csharp +public override async ValueTask DataReaderClosingAsync( + DbCommand command, + DataReaderClosingEventData eventData, + InterceptionResult result) +{ + await eventData.DataReader.NextResultAsync(); + + return result; +} +``` + +The second interceptor is needed to obtain the statistics from the connection and write them out to the application's logger. For this, we'll use an , implementing the `ConnectionCreated` method. `ConnectionCreated` is called immediately after EF Core has created a connection, and so can be used to perform additional configuration of that connection. In this case, the interceptor obtains an `ILogger` and then hooks into the event to log the messages. + +```csharp +public override DbConnection ConnectionCreated(ConnectionCreatedEventData eventData, DbConnection result) +{ + var logger = eventData.Context!.GetService().CreateLogger("InfoMessageLogger"); + ((SqlConnection)eventData.Connection).InfoMessage += (_, args) => + { + logger.LogInformation(1, args.Message); + }; + return result; +} +``` + +> [!IMPORTANT] +> The `ConnectionCreating` and `ConnectionCreated` methods are only called when EF Core creates a `DbConnection`. They will not be called if the application creates the `DbConnection` and passes it to EF Core. + +### Filtering by command source + +The supplied to diagnostics sources and interceptors contains a property indicating which part of EF was responsible for creating the command. This can be used as a filter in the interceptor. For example, we may want an interceptor that only applies to commands that come from `SaveChanges`: + +```csharp +public class CommandSourceInterceptor : DbCommandInterceptor +{ + public override InterceptionResult ReaderExecuting( + DbCommand command, CommandEventData eventData, InterceptionResult result) + { + if (eventData.CommandSource == CommandSource.SaveChanges) + { + Console.WriteLine($"Saving changes for {eventData.Context!.GetType().Name}:"); + Console.WriteLine(); + Console.WriteLine(command.CommandText); + } + + return result; + } +} +``` + ## SaveChanges interception > [!TIP] @@ -750,3 +963,390 @@ Audit 201fef4d-66a7-43ad-b9b6-b57e9d3f37b3 from 10/14/2020 9:10:17 PM to 10/14/2 Inserting Post with Id: '3' BlogId: '' Title: 'EF Core 3.1!' Error: SQLite Error 19: 'UNIQUE constraint failed: Post.Id'. ``` + +### Example: Optimistic concurrency interception + +EF Core supports the [optimistic concurrency pattern](xref:core/saving/concurrency) by checking that the number of rows actually affected by an update or delete is the same as the number of rows expected to be affected. This is often coupled with a concurrency token; that is, a column value that will only match its expected value if the row has not been updated since the expected value was read. + +EF signals a violation of optimistic concurrency by throwing a . has methods `ThrowingConcurrencyException` and `ThrowingConcurrencyExceptionAsync` that are called before the `DbUpdateConcurrencyException` is thrown. These interception points allow the exception to be suppressed, possibly coupled with async database changes to resolve the violation. + +For example, if two requests attempt to delete the same entity at almost the same time, then the second delete may fail because the row in the database no longer exists. This may be fine--the end result is that the entity has been deleted anyway. The following interceptor demonstrates how this can be done: + +```csharp +public class SuppressDeleteConcurrencyInterceptor : ISaveChangesInterceptor +{ + public InterceptionResult ThrowingConcurrencyException( + ConcurrencyExceptionEventData eventData, + InterceptionResult result) + { + if (eventData.Entries.All(e => e.State == EntityState.Deleted)) + { + Console.WriteLine("Suppressing Concurrency violation for command:"); + Console.WriteLine(((RelationalConcurrencyExceptionEventData)eventData).Command.CommandText); + + return InterceptionResult.Suppress(); + } + + return result; + } + + public ValueTask ThrowingConcurrencyExceptionAsync( + ConcurrencyExceptionEventData eventData, + InterceptionResult result, + CancellationToken cancellationToken = default) + => new(ThrowingConcurrencyException(eventData, result)); +} +``` + +There are several things worth noting about this interceptor: + +* Both the synchronous and asynchronous interception methods are implemented. This is important if the application may call either `SaveChanges` or `SaveChangesAsync`. However, if all application code is async, then only `ThrowingConcurrencyExceptionAsync` needs to be implemented. Likewise, if the application never uses asynchronous database methods, then only `ThrowingConcurrencyException` needs to be implemented. This is generally true for all interceptors with sync and async methods. +* The interceptor has access to objects for the entities being saved. In this case, this is used to check whether or not the concurrency violation is happening for a delete operation. +* If the application is using a relational database provider, then the object can be cast to a object. This provides additional, relational-specific information about the database operation being performed. In this case, the relational command text is printed to the console. +* Returning `InterceptionResult.Suppress()` tells EF Core to suppress the action it was about to take--in this case, throwing the `DbUpdateConcurrencyException`. This ability to _change the behavior of EF Core_, rather than just observing what EF Core is doing, is one of the most powerful features of interceptors. + +## Materialization interception + + supports interception before and after an entity instance is created, and before and after properties of that instance are initialized. The interceptor can change or replace the entity instance at each point. This allows: + +* Setting unmapped properties or calling methods needed for validation, computed values, or flags. +* Using a factory to create instances. +* Creating a different entity instance than EF would normally create, such as an instance from a cache, or of a proxy type. +* Injecting services into an entity instance. + +> [!NOTE] +> `IMaterializationInterceptor` is a singleton interceptor, meaning a single instance is shared between all `DbContext` instances. + +### Example: Simple actions on entity creation + +Imagine that we want to keep track of the time that an entity was retrieved from the database, perhaps so it can be displayed to a user editing the data. To accomplish this, we first define an interface: + +```csharp +public interface IHasRetrieved +{ + DateTime Retrieved { get; set; } +} +``` + +Using an interface is common with interceptors since it allows the same interceptor to work with many different entity types. For example: + +```csharp +public class Customer : IHasRetrieved +{ + public int Id { get; set; } + public string Name { get; set; } = null!; + public string? PhoneNumber { get; set; } + + [NotMapped] + public DateTime Retrieved { get; set; } +} +``` + +Notice that the `[NotMapped]` attribute is used to indicate that this property is used only while working with the entity, and should not be persisted to the database. + +The interceptor must then implement the appropriate method from `IMaterializationInterceptor` and set the time retrieved: + +```csharp +public class SetRetrievedInterceptor : IMaterializationInterceptor +{ + public object InitializedInstance(MaterializationInterceptionData materializationData, object instance) + { + if (instance is IHasRetrieved hasRetrieved) + { + hasRetrieved.Retrieved = DateTime.UtcNow; + } + + return instance; + } +} +``` + +An instance of this interceptor is registered when configuring the `DbContext`: + +```csharp +public class CustomerContext : DbContext +{ + private static readonly SetRetrievedInterceptor _setRetrievedInterceptor = new(); + + public DbSet Customers => Set(); + + protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) + => optionsBuilder + .AddInterceptors(_setRetrievedInterceptor) + .UseSqlite("Data Source = customers.db"); +} +``` + +> [!TIP] +> This interceptor is stateless, which is common, so a single instance is created and shared between all `DbContext` instances. + +Now, whenever a `Customer` is queried from the database, the `Retrieved` property will be set automatically. For example: + +```csharp +await using (var context = new CustomerContext()) +{ + var customer = await context.Customers.SingleAsync(e => e.Name == "Alice"); + Console.WriteLine($"Customer '{customer.Name}' was retrieved at '{customer.Retrieved.ToLocalTime()}'"); +} +``` + +Produces output: + +```output +Customer 'Alice' was retrieved at '9/22/2022 5:25:54 PM' +``` + +### Example: Injecting services into entities + +EF Core already has built-in support for injecting some special services into context instances; for example, see [Lazy loading without proxies](xref:core/querying/related-data/lazy#lazy-loading-without-proxies), which works by injecting the `ILazyLoader` service. + +An `IMaterializationInterceptor` can be used to generalize this to any service. The following example shows how to inject an into entities such that they can perform their own logging. + +> [!NOTE] +> Injecting services into entities couples those entity types to the injected services, which some people consider to be an anti-pattern. + +As before, an interface is used to define what can be done. + +```csharp +public interface IHasLogger +{ + ILogger? Logger { get; set; } +} +``` + +And entity types that will log must implement this interface. For example: + +```csharp +public class Customer : IHasLogger +{ + private string? _phoneNumber; + + public int Id { get; set; } + public string Name { get; set; } = null!; + + public string? PhoneNumber + { + get => _phoneNumber; + set + { + Logger?.LogInformation(1, $"Updating phone number for '{Name}' from '{_phoneNumber}' to '{value}'."); + + _phoneNumber = value; + } + } + + [NotMapped] + public ILogger? Logger { get; set; } +} +``` + +This time, the interceptor must implement `IMaterializationInterceptor.InitializedInstance`, which is called after every entity instance has been created and its property values have been initialized. The interceptor obtains an `ILogger` from the context and initializes `IHasLogger.Logger` with it: + +```csharp +public class LoggerInjectionInterceptor : IMaterializationInterceptor +{ + private ILogger? _logger; + + public object InitializedInstance(MaterializationInterceptionData materializationData, object instance) + { + if (instance is IHasLogger hasLogger) + { + _logger ??= materializationData.Context.GetService().CreateLogger("CustomersLogger"); + hasLogger.Logger = _logger; + } + + return instance; + } +} +``` + +This time a new instance of the interceptor is used for each `DbContext` instance, since the `ILogger` obtained can change per `DbContext` instance, and the `ILogger` is cached on the interceptor: + +```csharp +protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) + => optionsBuilder.AddInterceptors(new LoggerInjectionInterceptor()); +``` + +Now, whenever the `Customer.PhoneNumber` is changed, this change will be logged to the application's log. For example: + +```output +info: CustomersLogger[1] + Updating phone number for 'Alice' from '+1 515 555 0123' to '+1 515 555 0125'. +``` + +## Query expression interception + + allows interception of the [LINQ expression tree](xref:core/querying/how-query-works) for a query before it is compiled. This can be used to dynamically modify queries in ways that apply across the application. + +> [!NOTE] +> `IQueryExpressionInterceptor` is a singleton interceptor, meaning a single instance is typically shared between all `DbContext` instances. + +> [!WARNING] +> Interceptors are powerful, but it's easy to get things wrong when working with expression trees. Always consider if there is an easier way of achieving what you want, such as modifying the query directly. + +### Example: Inject ordering into queries for stable sorting + +Consider a method that returns a page of customers: + +```csharp +Task> GetPageOfCustomers(string sortProperty, int page) +{ + using var context = new CustomerContext(); + + return context.Customers + .OrderBy(e => EF.Property(e, sortProperty)) + .Skip(page * 20).Take(20).ToListAsync(); +} +``` + +> [!TIP] +> This query uses the method to specify the property to sort by. This allows the application to dynamically pass in the property name, allowing sorting by any property of the entity type. Be aware that sorting by non-indexed columns can be slow. + +This will work fine as long as the property used for sorting always returns a stable ordering. But this may not always be the case. For example, the LINQ query above generates the following on SQLite when ordering by `Customer.City`: + +```sql +SELECT "c"."Id", "c"."City", "c"."Name", "c"."PhoneNumber" +FROM "Customers" AS "c" +ORDER BY "c"."City" +LIMIT @__p_1 OFFSET @__p_0 +``` + +If there are multiple customers with the same `City`, then the ordering of this query is not stable. This could lead to missing or duplicate results as the user pages through the data. + +A common way to fix this problem is to perform a secondary sorting by primary key. However, rather than manually adding this to every query, an interceptor can add the secondary ordering dynamically. To facilitate this, we define an interface for any entity that has an integer primary key: + +```csharp +public interface IHasIntKey +{ + int Id { get; } +} +``` + +This interface is implemented by the entity types of interest: + +```csharp +public class Customer : IHasIntKey +{ + public int Id { get; set; } + public string Name { get; set; } = null!; + public string? City { get; set; } + public string? PhoneNumber { get; set; } +} +``` + +We then need an interceptor that implements : + +```csharp +public class KeyOrderingExpressionInterceptor : IQueryExpressionInterceptor +{ + public Expression QueryCompilationStarting(Expression queryExpression, QueryExpressionEventData eventData) + => new KeyOrderingExpressionVisitor().Visit(queryExpression); + + private class KeyOrderingExpressionVisitor : ExpressionVisitor + { + private static readonly MethodInfo ThenByMethod + = typeof(Queryable).GetMethods() + .Single(m => m.Name == nameof(Queryable.ThenBy) && m.GetParameters().Length == 2); + + protected override Expression VisitMethodCall(MethodCallExpression? methodCallExpression) + { + var methodInfo = methodCallExpression!.Method; + if (methodInfo.DeclaringType == typeof(Queryable) + && methodInfo.Name == nameof(Queryable.OrderBy) + && methodInfo.GetParameters().Length == 2) + { + var sourceType = methodCallExpression.Type.GetGenericArguments()[0]; + if (typeof(IHasIntKey).IsAssignableFrom(sourceType)) + { + var lambdaExpression = (LambdaExpression)((UnaryExpression)methodCallExpression.Arguments[1]).Operand; + var entityParameterExpression = lambdaExpression.Parameters[0]; + + return Expression.Call( + ThenByMethod.MakeGenericMethod( + sourceType, + typeof(int)), + methodCallExpression, + Expression.Lambda( + typeof(Func<,>).MakeGenericType(entityParameterExpression.Type, typeof(int)), + Expression.Property(entityParameterExpression, nameof(IHasIntKey.Id)), + entityParameterExpression)); + } + } + + return base.VisitMethodCall(methodCallExpression); + } + } +} +``` + +This probably looks pretty complicated--and it is! Working with expression trees is typically not easy. Let's look at what's happening: + +* Fundamentally, the interceptor encapsulates an . The visitor overrides , which will be called whenever there is a call to a method in the query expression tree. + +* The visitor checks whether or not this is a call to the method we are interested in. +* If it is, then the visitor further checks if the generic method call is for a type that implements our `IHasIntKey` interface. +* At this point we know that the method call is of the form `OrderBy(e => ...)`. We extract the lambda expression from this call and get the parameter used in that expression--that is, the `e`. +* We now build a new using the builder method. In this case, the method being called is `ThenBy(e => e.Id)`. We build this using the parameter extracted above and a property access to the `Id` property of the `IHasIntKey` interface. +* The input into this call is the original `OrderBy(e => ...)`, and so the end result is an expression for `OrderBy(e => ...).ThenBy(e => e.Id)`. +* This modified expression is returned from the visitor, which means the LINQ query has now been appropriately modified to include a `ThenBy` call. +* EF Core continues and compiles this query expression into the appropriate SQL for the database being used. + +Registering this interceptor and executing `GetPageOfCustomers` now generates the following SQL: + +```sql +SELECT "c"."Id", "c"."City", "c"."Name", "c"."PhoneNumber" +FROM "Customers" AS "c" +ORDER BY "c"."City", "c"."Id" +LIMIT @__p_1 OFFSET @__p_0 +``` + +This will now always produce a stable ordering, even if there are multiple customers with the same `City`. + +In many cases, the same thing can be achieved more simply by modifying the query directly. For example: + +```csharp +Task> GetPageOfCustomers2(string sortProperty, int page) +{ + using var context = new CustomerContext(); + + return context.Customers + .OrderBy(e => EF.Property(e, sortProperty)) + .ThenBy(e => e.Id) + .Skip(page * 20).Take(20).ToListAsync(); +} +``` + +In this case the `ThenBy` is simply added to the query. Yes, it may need to be done separately to every query, but it's simple, easy to understand, and will always work. + +## Identity resolution interception + + allows interception of identity resolution conflicts when the starts tracking new entity instances. + +> [!NOTE] +> This interceptor is currently only called when `DbContext.Update`, `DbContext.Attach`, and similar methods are used to track entities that are already being tracked with the same key. It is not called for entities returned from queries. This may change in a future release; [see this issue](https://github.com/dotnet/efcore/issues/37574). + +A `DbContext` can only track one entity instance with any given primary key value. This means multiple instances of an entity with the same key value must be resolved to a single instance. An interceptor of this type is called with the existing tracked instance and the new instance and must apply any property values and relationship changes from the new instance into the existing instance. The new instance is then discarded. + +EF Core provides a built-in implementation, , which updates the existing tracked entity with values from the new instance. This can be registered when configuring the context: + +```csharp +protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) + => optionsBuilder + .AddInterceptors(new UpdatingIdentityResolutionInterceptor()); +``` + +To implement custom identity resolution logic, create a class that implements `IIdentityResolutionInterceptor` and override the `UpdateTrackedInstance` method: + +```csharp +public class CustomIdentityResolutionInterceptor : IIdentityResolutionInterceptor +{ + public void UpdateTrackedInstance( + IdentityResolutionInterceptionData interceptionData, + EntityEntry existingEntry, + object newEntity) + { + // Custom logic to merge property values from newEntity into the existing tracked entity + existingEntry.CurrentValues.SetValues(newEntity); + } +} +``` diff --git a/entity-framework/core/what-is-new/ef-core-6.0/whatsnew.md b/entity-framework/core/what-is-new/ef-core-6.0/whatsnew.md index 9fd95244cd..b33f1dbe0e 100644 --- a/entity-framework/core/what-is-new/ef-core-6.0/whatsnew.md +++ b/entity-framework/core/what-is-new/ef-core-6.0/whatsnew.md @@ -3428,9 +3428,9 @@ This validation can be disabled if necessary. For example: GitHub Issue: [#23719](https://github.com/dotnet/efcore/issues/23719). This feature was contributed by [@Giorgi](https://github.com/Giorgi). Many thanks! -The `CommandEventData` supplied to diagnostics sources and interceptors now contains an enum value indicating which part of EF was responsible for creating the command. This can be used as a filter in the diagnostics or interceptor. For example, we may want an interceptor that only applies to commands that come from `SaveChanges`: +The supplied to diagnostics sources and interceptors now contains a enum value indicating which part of EF was responsible for creating the command. This can be used to filter interceptor behavior, for example to only intercept commands originating from `SaveChanges`: - -[!code-csharp[Interceptor](../../../../samples/core/Miscellaneous/NewInEFCore6/CommandSourceSample.cs?name=Interceptor)] +``` This filters the interceptor to only `SaveChanges` events when used in an application which also generates migrations and queries. For example: @@ -3462,6 +3461,8 @@ FROM [Customers] WHERE @@ROWCOUNT = 1 AND [Id] = scope_identity(); ``` +For more information, see [Filtering by command source](xref:core/logging-events-diagnostics/interceptors#filtering-by-command-source). + ### Better temporary values handling GitHub Issue: [#24245](https://github.com/dotnet/efcore/issues/24245). diff --git a/entity-framework/core/what-is-new/ef-core-7.0/whatsnew.md b/entity-framework/core/what-is-new/ef-core-7.0/whatsnew.md index b8934f010a..2a9cda3770 100644 --- a/entity-framework/core/what-is-new/ef-core-7.0/whatsnew.md +++ b/entity-framework/core/what-is-new/ef-core-7.0/whatsnew.md @@ -2320,48 +2320,13 @@ In addition, EF7 includes new traditional .NET events for: - When an [entity is about to be tracked or change state](https://github.com/dotnet/efcore/issues/27093), but before it is actually tracked or change state - Before and after EF Core [detects changes to entities and properties](https://github.com/dotnet/efcore/issues/26506) (aka `DetectChanges` interception) -The following sections show some examples of using these new interception capabilities. +The following sections provide brief summaries of these new interception capabilities. For detailed documentation and complete code samples, see [Interceptors](xref:core/logging-events-diagnostics/interceptors). -### Simple actions on entity creation +### Materialization interception -> [!TIP] -> The code shown here comes from [SimpleMaterializationSample.cs](https://github.com/dotnet/EntityFramework.Docs/tree/main/samples/core/Miscellaneous/NewInEFCore7/SimpleMaterializationSample.cs). - -The new supports interception before and after an entity instance is created, and before and after properties of that instance are initialized. The interceptor can change or replace the entity instance at each point. This allows: +The new supports interception before and after an entity instance is created, and before and after properties of that instance are initialized. The interceptor can change or replace the entity instance at each point. This allows setting unmapped properties, using a factory to create instances, injecting services into entities, and more. -- Setting unmapped properties or calling methods needed for validation, computed values, or flags. -- Using a factory to create instances. -- Creating a different entity instance than EF would normally create, such as an instance from a cache, or of a proxy type. -- Injecting services into an entity instance. - -For example, imagine that we want to keep track of the time that an entity was retrieved from the database, perhaps so it can be displayed to a user editing the data. To accomplish this, we first define an interface: - - -[!code-csharp[IHasRetrieved](../../../../samples/core/Miscellaneous/NewInEFCore7/SimpleMaterializationSample.cs?name=IHasRetrieved)] - -Using an interface is common with interceptors since it allows the same interceptor to work with many different entity types. For example: - - -[!code-csharp[Customer](../../../../samples/core/Miscellaneous/NewInEFCore7/SimpleMaterializationSample.cs?name=Customer)] - -Notice that the `[NotMapped]` attribute is used to indicate that this property is used only while working with the entity, and should not be persisted to the database. - -The interceptor must then implement the appropriate method from `IMaterializationInterceptor` and set the time retrieved: +For example, an interceptor can set a `Retrieved` timestamp on entities as they are loaded from the database: [!code-csharp[SetRetrievedInterceptor](../../../../samples/core/Miscellaneous/NewInEFCore7/SimpleMaterializationSample.cs?name=SetRetrievedInterceptor)] -An instance of this interceptor is registered when configuring the `DbContext`: - - -[!code-csharp[CustomerContext](../../../../samples/core/Miscellaneous/NewInEFCore7/SimpleMaterializationSample.cs?name=CustomerContext)] - -> [!TIP] -> This interceptor is stateless, which is common, so a single instance is created and shared between all `DbContext` instances. - -Now, whenever a `Customer` is queried from the database, the `Retrieved` property will be set automatically. For example: - - -[!code-csharp[QueryCustomer](../../../../samples/core/Miscellaneous/NewInEFCore7/SimpleMaterializationSample.cs?name=QueryCustomer)] - -Produces output: - -```output -Customer 'Alice' was retrieved at '9/22/2022 5:25:54 PM' -``` - -### Injecting services into entities - -> [!TIP] -> The code shown here comes from [InjectLoggerSample.cs](https://github.com/dotnet/EntityFramework.Docs/tree/main/samples/core/Miscellaneous/NewInEFCore7/InjectLoggerSample.cs). - -EF Core already has built-in support for injecting some special services into context instances; for example, see [Lazy loading without proxies](xref:core/querying/related-data/lazy#lazy-loading-without-proxies), which works by injecting the `ILazyLoader` service. - -An `IMaterializationInterceptor` can be used to generalize this to any service. The following example shows how to inject an into entities such that they can perform their own logging. - -> [!NOTE] -> Injecting services into entities couples those entity types to the injected services, which some people consider to be an anti-pattern. - -As before, an interface is used to define what can be done. - - -[!code-csharp[IHasLogger](../../../../samples/core/Miscellaneous/NewInEFCore7/InjectLoggerSample.cs?name=IHasLogger)] - -And entity types that will log must implement this interface. For example: - - -[!code-csharp[CustomerIHasLogger](../../../../samples/core/Miscellaneous/NewInEFCore7/InjectLoggerSample.cs?name=CustomerIHasLogger)] - -This time, the interceptor must implement `IMaterializationInterceptor.InitializedInstance`, which is called after every entity instance has been created and its property values have been initialized. The interceptor obtains an `ILogger` from the context and initializes `IHasLogger.Logger` with it: - - -[!code-csharp[LoggerInjectionInterceptor](../../../../samples/core/Miscellaneous/NewInEFCore7/InjectLoggerSample.cs?name=LoggerInjectionInterceptor)] - -This time a new instance of the interceptor is used for each `DbContext` instance, since the `ILogger` obtained can change per `DbContext` instance, and the `ILogger` is cached on the interceptor: - - -[!code-csharp[OnConfiguring](../../../../samples/core/Miscellaneous/NewInEFCore7/InjectLoggerSample.cs?name=OnConfiguring)] - -Now, whenever the `Customer.PhoneNumber` is changed, this change will be logged to the application's log. For example: - -```output -info: CustomersLogger[1] - Updating phone number for 'Alice' from '+1 515 555 0123' to '+1 515 555 0125'. -``` +For more information and examples, including injecting services into entities, see [Materialization interception](xref:core/logging-events-diagnostics/interceptors#materialization-interception). ### LINQ expression tree interception -> [!TIP] -> The code shown here comes from [QueryInterceptionSample.cs](https://github.com/dotnet/EntityFramework.Docs/tree/main/samples/core/Miscellaneous/NewInEFCore7/QueryInterceptionSample.cs). - -EF Core makes use of [.NET LINQ queries](xref:core/querying/how-query-works). This typically involves using the C#, VB, or F# compiler to build an expression tree which is then translated by EF Core into the appropriate SQL. For example, consider a method that returns a page of customers: - - -[!code-csharp[GetPageOfCustomers](../../../../samples/core/Miscellaneous/NewInEFCore7/QueryInterceptionSample.cs?name=GetPageOfCustomers)] - -> [!TIP] -> This query uses the method to specify the property to sort by. This allows the application to dynamically pass in the property name, allowing sorting by any property of the entity type. Be aware that sorting by non-indexed columns can be slow. - -This will work fine as long as the property used for sorting always returns a stable ordering. But this may not always be the case. For example, the LINQ query above generates the following on SQLite when ordering by `Customer.City`: - -```sql -SELECT "c"."Id", "c"."City", "c"."Name", "c"."PhoneNumber" -FROM "Customers" AS "c" -ORDER BY "c"."City" -LIMIT @__p_1 OFFSET @__p_0 -``` - -If there are multiple customers with the same `City`, then the ordering of this query is not stable. This could lead to missing or duplicate results as the user pages through the data. - -A common way to fix this problem is to perform a secondary sorting by primary key. However, rather than manually adding this to every query, EF7 allows interception of the query expression tree where the secondary ordering can be added dynamically. To facilitate this, we will again use an interface, this time for any entity that has an integer primary key: - - -[!code-csharp[IHasIntKey](../../../../samples/core/Miscellaneous/NewInEFCore7/QueryInterceptionSample.cs?name=IHasIntKey)] - -This interface is implemented by the entity types of interest: - - -[!code-csharp[CustomerIHasIntKey](../../../../samples/core/Miscellaneous/NewInEFCore7/QueryInterceptionSample.cs?name=CustomerIHasIntKey)] - -We then need an interceptor that implements - - -[!code-csharp[KeyOrderingExpressionInterceptor](../../../../samples/core/Miscellaneous/NewInEFCore7/QueryInterceptionSample.cs?name=KeyOrderingExpressionInterceptor)] - -This probably looks pretty complicated--and it is! Working with expression trees is typically not easy. Let's look at what's happening: - -- Fundamentally, the interceptor encapsulates an . The visitor overrides , which will be called whenever there is a call to a method in the query expression tree. - -- The visitor checks whether or not this is a call to the method we are interested in. -- If it is, then the visitor further checks if the generic method call is for a type that implements our `IHasIntKey` interface. -- At this point we know that the method call is of the form `OrderBy(e => ...)`. We extract the lambda expression from this call and get the parameter used in that expression--that is, the `e`. -- We now build a new using the builder method. In this case, the method being called is `ThenBy(e => e.Id)`. We build this using the parameter extracted above and a property access to the `Id` property of the `IHasIntKey` interface. -- The input into this call is the original `OrderBy(e => ...)`, and so the end result is an expression for `OrderBy(e => ...).ThenBy(e => e.Id)`. -- This modified expression is returned from the visitor, which means the LINQ query has now been appropriately modified to include a `ThenBy` call. -- EF Core continues and compiles this query expression into the appropriate SQL for the database being used. - -This interceptor is registered in the same way as we did for the first example. Executing `GetPageOfCustomers` now generates the following SQL: +```csharp +public class KeyOrderingExpressionInterceptor : IQueryExpressionInterceptor +{ + public Expression QueryCompilationStarting(Expression queryExpression, QueryExpressionEventData eventData) + => new KeyOrderingExpressionVisitor().Visit(queryExpression); -```sql -SELECT "c"."Id", "c"."City", "c"."Name", "c"."PhoneNumber" -FROM "Customers" AS "c" -ORDER BY "c"."City", "c"."Id" -LIMIT @__p_1 OFFSET @__p_0 + // ExpressionVisitor that modifies the tree... +} ``` -This will now always produce a stable ordering, even if there are multiple customers with the same `City`. - -Phew! That's a lot of code to make a simple change to a query. And even worse, it might not even work for all queries. It is notoriously difficult to write an expression visitor that recognizes all the query shapes it should, and none of the ones it should not. For example, this will likely not work if the ordering is done in a subquery. - -This brings us to a critical point about interceptors--always ask yourself if there is an easier way of doing what you want. Interceptors are powerful, but it's easy to get things wrong. They are, as the saying goes, an easy way to shoot yourself in the foot. - -For example, imagine if we instead changed our `GetPageOfCustomers` method like so: - - -[!code-csharp[GetPageOfCustomers2](../../../../samples/core/Miscellaneous/NewInEFCore7/QueryInterceptionSample.cs?name=GetPageOfCustomers2)] - -In this case the `ThenBy` is simply added to the query. Yes, it may need to be done separately to every query, but it's simple, easy to understand, and will always work. +For more information and examples, see [Query expression interception](xref:core/logging-events-diagnostics/interceptors#query-expression-interception). ### Optimistic concurrency interception -> [!TIP] -> The code shown here comes from [OptimisticConcurrencyInterceptionSample.cs](https://github.com/dotnet/EntityFramework.Docs/tree/main/samples/core/Miscellaneous/NewInEFCore7/OptimisticConcurrencyInterceptionSample.cs). - -EF Core supports the [optimistic concurrency pattern](xref:core/saving/concurrency) by checking that the number of rows actually affected by an update or delete is the same as the number of rows expected to be affected. This is often coupled with a concurrency token; that is, a column value that will only match its expected value if the row has not been updated since the expected value was read. + now has `ThrowingConcurrencyException` and `ThrowingConcurrencyExceptionAsync` methods that are called before a is thrown. These interception points allow the exception to be suppressed, possibly coupled with async database changes to resolve the violation. -EF signals a violation of optimistic concurrency by throwing a . In EF7, has new methods `ThrowingConcurrencyException` and `ThrowingConcurrencyExceptionAsync` that are called before the `DbUpdateConcurrencyException` is thrown. These interception points allow the exception to be suppressed, possibly coupled with async database changes to resolve the violation. +For example, if two requests try to delete the same entity, the second delete fails because the row no longer exists. An interceptor can suppress this, since the end result is the same: -For example, if two requests attempt to delete the same entity at almost the same time, then the second delete may fail because the row in the database no longer exists. This may be fine--the end result is that the entity has been deleted anyway. The following interceptor demonstrates how this can be done: - - -[!code-csharp[SuppressDeleteConcurrencyInterceptor](../../../../samples/core/Miscellaneous/NewInEFCore7/OptimisticConcurrencyInterceptionSample.cs?name=SuppressDeleteConcurrencyInterceptor)] - -There are several things worth noting about this interceptor: +} +``` -- Both the synchronous and asynchronous interception methods are implemented. This is important if the application may call either `SaveChanges` or `SaveChangesAsync`. However, if all application code is async, then only `ThrowingConcurrencyExceptionAsync` needs to be implemented. Likewise, if the application never uses asynchronous database methods, then only `ThrowingConcurrencyException` needs to be implemented. This is generally true for all interceptors with sync and async methods. (It might be worthwhile implementing the method your application does not use to throw, just in case some sync/async code creeps in.) -- The interceptor has access to objects for the entities being saved. In this case, this is used to check whether or not the concurrency violation is happening for a delete operation. -- If the application is using a relational database provider, then the object can be cast to a object. This provides additional, relational-specific information about the database operation being performed. In this case, the relational command text is printed to the console. -- Returning `InterceptionResult.Suppress()` tells EF Core to suppress the action it was about to take--in this case, throwing the `DbUpdateConcurrencyException`. This ability to _change the behavior of EF Core_, rather than just observing what EF Core is doing, is one of the most powerful features of interceptors. +For more information and examples, see [Optimistic concurrency interception](xref:core/logging-events-diagnostics/interceptors#example-optimistic-concurrency-interception). ### Lazy initialization of a connection string -> [!TIP] -> The code shown here comes from [LazyConnectionStringSample.cs](https://github.com/dotnet/EntityFramework.Docs/tree/main/samples/core/Miscellaneous/NewInEFCore7/LazyConnectionStringSample.cs). - -Connection strings are often static assets read from a configuration file. These can easily be passed to `UseSqlServer` or similar when configuring a `DbContext`. However, sometimes the connection string can change for each context instance. For example, each tenant in a multi-tenant system may have a different connection string. - -EF7 makes it easier to handle dynamic connections and connection strings through improvements to the . This starts with the ability to configure the `DbContext` without any connection string. For example: - -```csharp -services.AddDbContext( - b => b.UseSqlServer()); -``` + can be used to dynamically configure connection strings at the time the connection is first used, for example to support per-tenant connection strings in a multi-tenant system. The `ConnectionOpeningAsync` method can perform an async operation to obtain the connection string, find an access token, and so on. -One of the `IDbConnectionInterceptor` methods can then be implemented to configure the connection before it is used. `ConnectionOpeningAsync` is a good choice, since it can perform an async operation to obtain the connection string, find an access token, and so on. For example, imagine a service scoped to the current request that understands the current tenant: +For example, the following interceptor sets the connection string the first time the connection is opened: ```csharp -services.AddScoped(); -``` - -> [!WARNING] -> Performing an asynchronous lookup for a connection string, access token, or similar every time it is needed can be very slow. Consider caching these things and only refreshing the cached string or token periodically. For example, access tokens can often be used for a significant period of time before needing to be refreshed. - -This can be injected into each `DbContext` instance using constructor injection: - -```csharp -public class CustomerContext : DbContext +public class ConnectionStringInitializationInterceptor : DbConnectionInterceptor { private readonly ITenantConnectionStringFactory _connectionStringFactory; - public CustomerContext( - DbContextOptions options, - ITenantConnectionStringFactory connectionStringFactory) - : base(options) + public ConnectionStringInitializationInterceptor(ITenantConnectionStringFactory connectionStringFactory) { _connectionStringFactory = connectionStringFactory; } - // ... -} -``` - -This service is then used when constructing the interceptor implementation for the context: - -```csharp -protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) - => optionsBuilder.AddInterceptors( - new ConnectionStringInitializationInterceptor(_connectionStringFactory)); -``` - -Finally, the interceptor uses this service to obtain the connection string asynchronously and set it the first time that the connection is used: - - -[!code-csharp[ConnectionStringInitializationInterceptor](../../../../samples/core/Miscellaneous/NewInEFCore7/LazyConnectionStringSample.cs?name=ConnectionStringInitializationInterceptor)] - -> [!NOTE] -> The connection string is only obtained the first time that a connection is used. After that, the connection string stored on the `DbConnection` will be used without looking up a new connection string. +} +``` -> [!TIP] -> This interceptor overrides the non-async `ConnectionOpening` method to throw since the service to get the connection string must be called from an async code path. +For more information and examples, see [Lazy initialization of a connection string](xref:core/logging-events-diagnostics/interceptors#example-lazy-initialization-of-a-connection-string). ### Logging SQL Server query statistics -> [!TIP] -> The code shown here comes from [QueryStatisticsLoggerSample.cs](https://github.com/dotnet/EntityFramework.Docs/tree/main/samples/core/Miscellaneous/NewInEFCore7/QueryStatisticsLoggerSample.cs). - -Finally, let's create two interceptors that work together to send SQL Server query statistics to the application log. To generate the statistics, we need an to do two things. +Two interceptors can work together to send SQL Server query statistics to the application log. An prefixes commands with `SET STATISTICS IO ON` and uses the new `DataReaderClosingAsync` method to read statistics results. An uses the new `ConnectionCreated` method to hook into the event. -First, the interceptor will prefix commands with `SET STATISTICS IO ON`, which tells SQL Server to send statistics to the client after a result set has been consumed: - - -[!code-csharp[ReaderExecutingAsync](../../../../samples/core/Miscellaneous/NewInEFCore7/QueryStatisticsLoggerSample.cs?name=ReaderExecutingAsync)] - -Second, the interceptor will implement the new `DataReaderClosingAsync` method, which is called after the has finished consuming results, but _before_ it has been closed. When SQL Server is sending statistics, it puts them in a second result on the reader, so at this point the interceptor reads that result by calling `NextResultAsync` which populates statistics onto the connection. - - -[!code-csharp[DataReaderClosingAsync](../../../../samples/core/Miscellaneous/NewInEFCore7/QueryStatisticsLoggerSample.cs?name=DataReaderClosingAsync)] - -The second interceptor is needed to obtain the statistics from the connection and write them out to the application's logger. For this, we'll use an , implementing the new `ConnectionCreated` method. `ConnectionCreated` is called immediately after EF Core has created a connection, and so can be used to perform additional configuration of that connection. In this case, the interceptor obtains an `ILogger` and then hooks into the event to log the messages. - - -[!code-csharp[InfoMessageInterceptor](../../../../samples/core/Miscellaneous/NewInEFCore7/QueryStatisticsLoggerSample.cs?name=InfoMessageInterceptor)] - -> [!IMPORTANT] -> The `ConnectionCreating` and `ConnectionCreated` methods are only called when EF Core creates a `DbConnection`. They will not be called if the application creates the `DbConnection` and passes it to EF Core. - -Running some code that uses these interceptors show SQL Server query statistics in the log: +```csharp +public override ValueTask> ReaderExecutingAsync( + DbCommand command, + CommandEventData eventData, + InterceptionResult result, + CancellationToken cancellationToken = default) +{ + command.CommandText = "SET STATISTICS IO ON;" + Environment.NewLine + command.CommandText; -```output -info: Microsoft.EntityFrameworkCore.Database.Command[20101] - Executed DbCommand (4ms) [Parameters=[@p0='?' (Size = 4000), @p1='?' (Size = 4000), @p2='?' (Size = 4000), @p3='?' (Size = 4000)], CommandType='Text', CommandTimeout='30'] - SET STATISTICS IO ON; - SET IMPLICIT_TRANSACTIONS OFF; - SET NOCOUNT ON; - MERGE [Customers] USING ( - VALUES (@p0, @p1, 0), - (@p2, @p3, 1)) AS i ([Name], [PhoneNumber], _Position) ON 1=0 - WHEN NOT MATCHED THEN - INSERT ([Name], [PhoneNumber]) - VALUES (i.[Name], i.[PhoneNumber]) - OUTPUT INSERTED.[Id], i._Position; -info: InfoMessageLogger[1] - Table 'Customers'. Scan count 0, logical reads 5, physical reads 0, page server reads 0, read-ahead reads 0, page server read-ahead reads 0, lob logical reads 0, lob physical reads 0, lob page server reads 0, lob read-ahead reads 0, lob page server read-ahead reads 0. -info: Microsoft.EntityFrameworkCore.Database.Command[20101] - Executed DbCommand (2ms) [Parameters=[], CommandType='Text', CommandTimeout='30'] - SET STATISTICS IO ON; - SELECT TOP(2) [c].[Id], [c].[Name], [c].[PhoneNumber] - FROM [Customers] AS [c] - WHERE [c].[Name] = N'Alice' -info: InfoMessageLogger[1] - Table 'Customers'. Scan count 1, logical reads 2, physical reads 0, page server reads 0, read-ahead reads 0, page server read-ahead reads 0, lob logical reads 0, lob physical reads 0, lob page server reads 0, lob read-ahead reads 0, lob page server read-ahead reads 0. + return new(result); +} ``` +For more information and examples, see [Logging SQL Server query statistics](xref:core/logging-events-diagnostics/interceptors#example-logging-sql-server-query-statistics). + ## Query enhancements EF7 contains many improvements in the translation of LINQ queries. diff --git a/samples/core/Miscellaneous/NewInEFCore6/CommandSourceSample.cs b/samples/core/Miscellaneous/NewInEFCore6/CommandSourceSample.cs deleted file mode 100644 index bbc7b304a5..0000000000 --- a/samples/core/Miscellaneous/NewInEFCore6/CommandSourceSample.cs +++ /dev/null @@ -1,71 +0,0 @@ -using System; -using System.Data.Common; -using System.Linq; -using System.Threading.Tasks; -using Microsoft.EntityFrameworkCore; -using Microsoft.EntityFrameworkCore.Diagnostics; - -public static class CommandSourceSample -{ - public static async Task Interceptors_get_the_source_of_the_command() - { - Console.WriteLine($">>>> Sample: {nameof(Interceptors_get_the_source_of_the_command)}"); - Console.WriteLine(); - - using var context = new CustomersContext(); - - await context.Database.EnsureDeletedAsync(); - await context.Database.EnsureCreatedAsync(); - - context.Add( - new Customer - { - Name = "Sam Vimes" - }); - - await context.SaveChangesAsync(); - - context.ChangeTracker.Clear(); - - var customers = await context.Customers.ToListAsync(); - - Console.WriteLine(); - } - - #region Interceptor - public class CommandSourceInterceptor : DbCommandInterceptor - { - public override InterceptionResult ReaderExecuting( - DbCommand command, CommandEventData eventData, InterceptionResult result) - { - if (eventData.CommandSource == CommandSource.SaveChanges) - { - Console.WriteLine($"Saving changes for {eventData.Context!.GetType().Name}:"); - Console.WriteLine(); - Console.WriteLine(command.CommandText); - } - - return result; - } - } - #endregion - - public class Customer - { - public int Id { get; set; } - public string Name { get; set; } - } - - public class CustomersContext : DbContext - { - public DbSet Customers { get; set; } - - protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) - { - optionsBuilder - .EnableSensitiveDataLogging() - .AddInterceptors(new CommandSourceInterceptor()) - .UseSqlServer(@"Server=(localdb)\mssqllocaldb;Database=EFCoreSample;ConnectRetryCount=0"); - } - } -} diff --git a/samples/core/Miscellaneous/NewInEFCore6/Program.cs b/samples/core/Miscellaneous/NewInEFCore6/Program.cs index baed816a8e..826dc646c6 100644 --- a/samples/core/Miscellaneous/NewInEFCore6/Program.cs +++ b/samples/core/Miscellaneous/NewInEFCore6/Program.cs @@ -40,7 +40,6 @@ public static async Task Main() await HasConversionSample.Can_set_value_converter_type_using_generic_method(); MinimalApiSample.Add_a_DbContext_and_provider(); await ToInMemoryQuerySample.Can_query_keyless_types_from_in_memory_database(); - await CommandSourceSample.Interceptors_get_the_source_of_the_command(); await ScaffoldingSample.Reverse_engineer_from_database(); await ManyToManyConfigurationSample.Many_to_many_relationships_may_need_less_configuration(); await ConvertNullsSample.Value_converters_can_convert_nulls(); diff --git a/samples/core/Miscellaneous/NewInEFCore7/InjectLoggerSample.cs b/samples/core/Miscellaneous/NewInEFCore7/InjectLoggerSample.cs deleted file mode 100644 index 8c98e118b7..0000000000 --- a/samples/core/Miscellaneous/NewInEFCore7/InjectLoggerSample.cs +++ /dev/null @@ -1,113 +0,0 @@ -using Microsoft.EntityFrameworkCore.Diagnostics; -using Microsoft.EntityFrameworkCore.Infrastructure; - -namespace NewInEfCore7; - -public static class InjectLoggerSample -{ - public static async Task Injecting_services_into_entities() - { - PrintSampleName(); - - var loggerFactory = LoggerFactory.Create(builder => { builder.AddConsole(); }); - - var serviceProvider = new ServiceCollection() - .AddDbContext( - b => b.UseLoggerFactory(loggerFactory) - .UseSqlite("Data Source = customers.db")) - .BuildServiceProvider(); - - using (var scope = serviceProvider.CreateScope()) - { - var context = scope.ServiceProvider.GetRequiredService(); - - await context.Database.EnsureDeletedAsync(); - await context.Database.EnsureCreatedAsync(); - - await context.AddRangeAsync( - new Customer { Name = "Alice", PhoneNumber = "+1 515 555 0123" }, - new Customer { Name = "Mac", PhoneNumber = "+1 515 555 0124" }); - - await context.SaveChangesAsync(); - } - - using (var scope = serviceProvider.CreateScope()) - { - var context = scope.ServiceProvider.GetRequiredService(); - - var customer = await context.Customers.SingleAsync(e => e.Name == "Alice"); - customer.PhoneNumber = "+1 515 555 0125"; - } - } - - private static void PrintSampleName([CallerMemberName] string? methodName = null) - { - Console.WriteLine($">>>> Sample: {methodName}"); - Console.WriteLine(); - } - - public class CustomerContext : DbContext - { - public CustomerContext(DbContextOptions options) - : base(options) - { - } - - public DbSet Customers - => Set(); - - #region OnConfiguring - protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) - => optionsBuilder.AddInterceptors(new LoggerInjectionInterceptor()); - #endregion - } - - #region LoggerInjectionInterceptor - public class LoggerInjectionInterceptor : IMaterializationInterceptor - { - private ILogger? _logger; - - public object InitializedInstance(MaterializationInterceptionData materializationData, object instance) - { - if (instance is IHasLogger hasLogger) - { - _logger ??= materializationData.Context.GetService().CreateLogger("CustomersLogger"); - hasLogger.Logger = _logger; - } - - return instance; - } - } - #endregion - - #region IHasLogger - public interface IHasLogger - { - ILogger? Logger { get; set; } - } - #endregion - - #region CustomerIHasLogger - public class Customer : IHasLogger - { - private string? _phoneNumber; - - public int Id { get; set; } - public string Name { get; set; } = null!; - - public string? PhoneNumber - { - get => _phoneNumber; - set - { - Logger?.LogInformation(1, $"Updating phone number for '{Name}' from '{_phoneNumber}' to '{value}'."); - - _phoneNumber = value; - } - } - - [NotMapped] - public ILogger? Logger { get; set; } - } - #endregion -} diff --git a/samples/core/Miscellaneous/NewInEFCore7/LazyConnectionStringSample.cs b/samples/core/Miscellaneous/NewInEFCore7/LazyConnectionStringSample.cs deleted file mode 100644 index e2a8d2dd95..0000000000 --- a/samples/core/Miscellaneous/NewInEFCore7/LazyConnectionStringSample.cs +++ /dev/null @@ -1,119 +0,0 @@ -using Microsoft.EntityFrameworkCore.Diagnostics; - -namespace NewInEfCore7; - -public static class LazyConnectionStringSample -{ - public static async Task Lazy_initialization_of_a_connection_string() - { - PrintSampleName(); - - var services = new ServiceCollection(); - - services.AddScoped(); - - services.AddDbContext( - b => b.UseSqlServer() - .LogTo(Console.WriteLine, LogLevel.Information) - .EnableSensitiveDataLogging()); - - var serviceProvider = services.BuildServiceProvider(); - - using (var scope = serviceProvider.CreateScope()) - { - var context = scope.ServiceProvider.GetRequiredService(); - - await context.Database.EnsureDeletedAsync(); - await context.Database.EnsureCreatedAsync(); - - await context.AddRangeAsync( - new Customer { Name = "Alice" }, - new Customer { Name = "Mac" }); - - await context.SaveChangesAsync(); - - var customer = await context.Customers.SingleAsync(e => e.Name == "Alice"); - Console.WriteLine(); - Console.WriteLine($"Loaded {customer.Name}"); - Console.WriteLine(); - } - } - - private static void PrintSampleName([CallerMemberName] string? methodName = null) - { - Console.WriteLine($">>>> Sample: {methodName}"); - Console.WriteLine(); - } - - public class CustomerContext : DbContext - { - private readonly IClientConnectionStringFactory _connectionStringFactory; - - public CustomerContext( - DbContextOptions options, - IClientConnectionStringFactory connectionStringFactory) - : base(options) - { - _connectionStringFactory = connectionStringFactory; - } - - public DbSet Customers - => Set(); - - protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) - => optionsBuilder.AddInterceptors( - new ConnectionStringInitializationInterceptor(_connectionStringFactory)); - } - - public interface IClientConnectionStringFactory - { - Task GetConnectionStringAsync(CancellationToken cancellationToken); - } - - public class TestClientConnectionStringFactory : IClientConnectionStringFactory - { - public Task GetConnectionStringAsync(CancellationToken cancellationToken) - { - Console.WriteLine(); - Console.WriteLine(">>> Getting connection string..."); - Console.WriteLine(); - return Task.FromResult(@"Server=(localdb)\mssqllocaldb;Database=LazyConnectionStringSample"); - } - } - - #region ConnectionStringInitializationInterceptor - public class ConnectionStringInitializationInterceptor : DbConnectionInterceptor - { - private readonly IClientConnectionStringFactory _connectionStringFactory; - - public ConnectionStringInitializationInterceptor(IClientConnectionStringFactory connectionStringFactory) - { - _connectionStringFactory = connectionStringFactory; - } - - public override InterceptionResult ConnectionOpening( - DbConnection connection, - ConnectionEventData eventData, - InterceptionResult result) - => throw new NotSupportedException("Synchronous connections not supported."); - - public override async ValueTask ConnectionOpeningAsync( - DbConnection connection, ConnectionEventData eventData, InterceptionResult result, - CancellationToken cancellationToken = new()) - { - if (string.IsNullOrEmpty(connection.ConnectionString)) - { - connection.ConnectionString = (await _connectionStringFactory.GetConnectionStringAsync(cancellationToken)); - } - - return result; - } - } - #endregion - - public class Customer - { - public int Id { get; set; } - public string Name { get; set; } = null!; - } -} diff --git a/samples/core/Miscellaneous/NewInEFCore7/OptimisticConcurrencyInterceptionSample.cs b/samples/core/Miscellaneous/NewInEFCore7/OptimisticConcurrencyInterceptionSample.cs deleted file mode 100644 index 901e54ad69..0000000000 --- a/samples/core/Miscellaneous/NewInEFCore7/OptimisticConcurrencyInterceptionSample.cs +++ /dev/null @@ -1,90 +0,0 @@ -using Microsoft.EntityFrameworkCore.Diagnostics; - -namespace NewInEfCore7; - -public static class OptimisticConcurrencyInterceptionSample -{ - public static async Task Optimistic_concurrency_interception() - { - PrintSampleName(); - - await using (var context = new CustomerContext()) - { - await context.Database.EnsureDeletedAsync(); - await context.Database.EnsureCreatedAsync(); - - await context.AddRangeAsync( - new Customer { Name = "Bill" }, - new Customer { Name = "Bob" }); - - await context.SaveChangesAsync(); - } - - await using (var context1 = new CustomerContext()) - { - var customer1 = await context1.Customers.SingleAsync(e => e.Name == "Bill"); - - await using (var context2 = new CustomerContext()) - { - var customer2 = await context1.Customers.SingleAsync(e => e.Name == "Bill"); - context2.Entry(customer2).State = EntityState.Deleted; - await context2.SaveChangesAsync(); - } - - context1.Entry(customer1).State = EntityState.Deleted; - await context1.SaveChangesAsync(); - } - } - - private static void PrintSampleName([CallerMemberName] string? methodName = null) - { - Console.WriteLine($">>>> Sample: {methodName}"); - Console.WriteLine(); - } - - public class CustomerContext : DbContext - { - private static readonly SuppressDeleteConcurrencyInterceptor _concurrencyInterceptor = new(); - - public DbSet Customers - => Set(); - - protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) - => optionsBuilder - .AddInterceptors(_concurrencyInterceptor) - .UseSqlite("Data Source = customers.db") - .LogTo(Console.WriteLine, LogLevel.Information); - } - - #region SuppressDeleteConcurrencyInterceptor - public class SuppressDeleteConcurrencyInterceptor : ISaveChangesInterceptor - { - public InterceptionResult ThrowingConcurrencyException( - ConcurrencyExceptionEventData eventData, - InterceptionResult result) - { - if (eventData.Entries.All(e => e.State == EntityState.Deleted)) - { - Console.WriteLine("Suppressing Concurrency violation for command:"); - Console.WriteLine(((RelationalConcurrencyExceptionEventData)eventData).Command.CommandText); - - return InterceptionResult.Suppress(); - } - - return result; - } - - public ValueTask ThrowingConcurrencyExceptionAsync( - ConcurrencyExceptionEventData eventData, - InterceptionResult result, - CancellationToken cancellationToken = default) - => new(ThrowingConcurrencyException(eventData, result)); - } - #endregion - - public class Customer - { - public int Id { get; set; } - public string Name { get; set; } = null!; - } -} diff --git a/samples/core/Miscellaneous/NewInEFCore7/Program.cs b/samples/core/Miscellaneous/NewInEFCore7/Program.cs index d7c07a4960..ec587c479f 100644 --- a/samples/core/Miscellaneous/NewInEFCore7/Program.cs +++ b/samples/core/Miscellaneous/NewInEFCore7/Program.cs @@ -35,16 +35,6 @@ public static async Task Main() await SimpleMaterializationSample.Simple_actions_on_entity_creation(); - await QueryInterceptionSample.LINQ_expression_tree_interception(); - - await OptimisticConcurrencyInterceptionSample.Optimistic_concurrency_interception(); - - await InjectLoggerSample.Injecting_services_into_entities(); - - await LazyConnectionStringSample.Lazy_initialization_of_a_connection_string(); - - await QueryStatisticsLoggerSample.Executing_commands_after_consuming_a_result_set(); - await UngroupedColumnsQuerySample.Subqueries_dont_reference_ungrouped_columns_from_outer_query_SqlServer(); await GroupByEntityTypeSample.GroupBy_entity_type_Sqlite(); diff --git a/samples/core/Miscellaneous/NewInEFCore7/QueryInterceptionSample.cs b/samples/core/Miscellaneous/NewInEFCore7/QueryInterceptionSample.cs deleted file mode 100644 index 77e202bcd6..0000000000 --- a/samples/core/Miscellaneous/NewInEFCore7/QueryInterceptionSample.cs +++ /dev/null @@ -1,138 +0,0 @@ -using Microsoft.EntityFrameworkCore.Diagnostics; - -namespace NewInEfCore7; - -public static class QueryInterceptionSample -{ - public static async Task LINQ_expression_tree_interception() - { - PrintSampleName(); - - await using (var context = new CustomerContext()) - { - await context.Database.EnsureDeletedAsync(); - await context.Database.EnsureCreatedAsync(); - - await context.AddRangeAsync( - new Customer { Name = "Alice", PhoneNumber = "+1 515 555 0123", City = "Ames" }, - new Customer { Name = "Mac", PhoneNumber = "+1 515 555 0124", City = "Ames" }, - new Customer { Name = "Toast" }, - new Customer { Name = "Baxter" }); - - await context.SaveChangesAsync(); - } - - foreach (var customer in await GetPageOfCustomers("City", 0)) - { - Console.WriteLine($"{customer.Name}"); - } - - #region GetPageOfCustomers - Task> GetPageOfCustomers(string sortProperty, int page) - { - using var context = new CustomerContext(); - - return context.Customers - .OrderBy(e => EF.Property(e, sortProperty)) - .Skip(page * 20).Take(20).ToListAsync(); - } - #endregion - - foreach (var customer in await GetPageOfCustomers2("City", 0)) - { - Console.WriteLine($"{customer.Name}"); - } - - #region GetPageOfCustomers2 - Task> GetPageOfCustomers2(string sortProperty, int page) - { - using var context = new CustomerContext(); - - return context.Customers - .OrderBy(e => EF.Property(e, sortProperty)) - .ThenBy(e => e.Id) - .Skip(page * 20).Take(20).ToListAsync(); - } - #endregion - } - - private static void PrintSampleName([CallerMemberName] string? methodName = null) - { - Console.WriteLine($">>>> Sample: {methodName}"); - Console.WriteLine(); - } - - public class CustomerContext : DbContext - { - private static readonly KeyOrderingExpressionInterceptor _keyOrderingExpressionInterceptor = new(); - - public DbSet Customers - => Set(); - - protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) - => optionsBuilder - .AddInterceptors(_keyOrderingExpressionInterceptor) - .UseSqlite("Data Source = customers.db") - .LogTo(Console.WriteLine, LogLevel.Information); - } - - #region KeyOrderingExpressionInterceptor - public class KeyOrderingExpressionInterceptor : IQueryExpressionInterceptor - { - public Expression QueryCompilationStarting(Expression queryExpression, QueryExpressionEventData eventData) - => new KeyOrderingExpressionVisitor().Visit(queryExpression); - - private class KeyOrderingExpressionVisitor : ExpressionVisitor - { - private static readonly MethodInfo ThenByMethod - = typeof(Queryable).GetMethods() - .Single(m => m.Name == nameof(Queryable.ThenBy) && m.GetParameters().Length == 2); - - protected override Expression VisitMethodCall(MethodCallExpression? methodCallExpression) - { - var methodInfo = methodCallExpression!.Method; - if (methodInfo.DeclaringType == typeof(Queryable) - && methodInfo.Name == nameof(Queryable.OrderBy) - && methodInfo.GetParameters().Length == 2) - { - var sourceType = methodCallExpression.Type.GetGenericArguments()[0]; - if (typeof(IHasIntKey).IsAssignableFrom(sourceType)) - { - var lambdaExpression = (LambdaExpression)((UnaryExpression)methodCallExpression.Arguments[1]).Operand; - var entityParameterExpression = lambdaExpression.Parameters[0]; - - return Expression.Call( - ThenByMethod.MakeGenericMethod( - sourceType, - typeof(int)), - base.VisitMethodCall(methodCallExpression), - Expression.Lambda( - typeof(Func<,>).MakeGenericType(entityParameterExpression.Type, typeof(int)), - Expression.Property(entityParameterExpression, nameof(IHasIntKey.Id)), - entityParameterExpression)); - } - } - - return base.VisitMethodCall(methodCallExpression); - } - } - } - #endregion - - #region IHasIntKey - public interface IHasIntKey - { - int Id { get; } - } - #endregion - - #region CustomerIHasIntKey - public class Customer : IHasIntKey - { - public int Id { get; set; } - public string Name { get; set; } = null!; - public string? City { get; set; } - public string? PhoneNumber { get; set; } - } - #endregion -} diff --git a/samples/core/Miscellaneous/NewInEFCore7/QueryStatisticsLoggerSample.cs b/samples/core/Miscellaneous/NewInEFCore7/QueryStatisticsLoggerSample.cs deleted file mode 100644 index d01287061a..0000000000 --- a/samples/core/Miscellaneous/NewInEFCore7/QueryStatisticsLoggerSample.cs +++ /dev/null @@ -1,135 +0,0 @@ -using Microsoft.Data.SqlClient; -using Microsoft.EntityFrameworkCore.Diagnostics; -using Microsoft.EntityFrameworkCore.Infrastructure; - -namespace NewInEfCore7; - -public static class QueryStatisticsLoggerSample -{ - public static async Task Executing_commands_after_consuming_a_result_set() - { - PrintSampleName(); - - var loggerFactory = LoggerFactory.Create(builder => { builder.AddConsole(); }); - - var serviceProvider = new ServiceCollection() - .AddDbContext( - b => b.UseLoggerFactory(loggerFactory) - .UseSqlServer(@"Server=(localdb)\mssqllocaldb;Database=ConsumedDataReaderSample;ConnectRetryCount=0")) - .BuildServiceProvider(); - - using (var scope = serviceProvider.CreateScope()) - { - var context = scope.ServiceProvider.GetRequiredService(); - - await context.Database.EnsureDeletedAsync(); - await context.Database.EnsureCreatedAsync(); - - await context.AddRangeAsync( - new Customer { Name = "Alice", PhoneNumber = "+1 515 555 0123" }, - new Customer { Name = "Mac", PhoneNumber = "+1 515 555 0124" }); - - await context.SaveChangesAsync(); - } - - using (var scope = serviceProvider.CreateScope()) - { - var context = scope.ServiceProvider.GetRequiredService(); - - _ = await context.Customers.SingleAsync(e => e.Name == "Alice"); - } - } - - private static void PrintSampleName([CallerMemberName] string? methodName = null) - { - Console.WriteLine($">>>> Sample: {methodName}"); - Console.WriteLine(); - } - - public class CustomerContext : DbContext - { - private static readonly StatisticsCommandInterceptor _statisticsCommandInterceptor = new(); - private static readonly InfoMessageInterceptor _infoMessageInterceptor = new(); - - public CustomerContext(DbContextOptions options) - : base(options) - { - } - - public DbSet Customers - => Set(); - - protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) - => optionsBuilder.AddInterceptors(_statisticsCommandInterceptor, _infoMessageInterceptor); - } - - public class InfoMessageInterceptor : DbConnectionInterceptor - { - #region InfoMessageInterceptor - public override DbConnection ConnectionCreated(ConnectionCreatedEventData eventData, DbConnection result) - { - var logger = eventData.Context!.GetService().CreateLogger("InfoMessageLogger"); - ((SqlConnection)eventData.Connection).InfoMessage += (_, args) => - { - logger.LogInformation(1, args.Message); - }; - return result; - } - #endregion - } - - public class StatisticsCommandInterceptor : DbCommandInterceptor - { - public override InterceptionResult ReaderExecuting( - DbCommand command, - CommandEventData eventData, - InterceptionResult result) - { - command.CommandText = "SET STATISTICS IO ON;" + Environment.NewLine + command.CommandText; - - return result; - } - - #region ReaderExecutingAsync - public override ValueTask> ReaderExecutingAsync( - DbCommand command, - CommandEventData eventData, - InterceptionResult result, - CancellationToken cancellationToken = default) - { - command.CommandText = "SET STATISTICS IO ON;" + Environment.NewLine + command.CommandText; - - return new(result); - } - #endregion - - public override InterceptionResult DataReaderClosing( - DbCommand command, - DataReaderClosingEventData eventData, - InterceptionResult result) - { - eventData.DataReader.NextResult(); - - return result; - } - - #region DataReaderClosingAsync - public override async ValueTask DataReaderClosingAsync( - DbCommand command, - DataReaderClosingEventData eventData, - InterceptionResult result) - { - await eventData.DataReader.NextResultAsync(); - - return result; - } - #endregion - } - - public class Customer - { - public int Id { get; set; } - public string Name { get; set; } = null!; - public string? PhoneNumber { get; set; } - } -}