Entity Framework Core 7 (EF7) Preview 7 has shipped with support for several new interceptors, as well as improvements to existing interceptors. This blog post will cover these changes, but Preview 7 also contains several additional enhancements, including:<\/p>\n
See the full list of EF7 Preview 7 changes<\/a> on GitHub.<\/p>\n EF Core interceptors enable interception, modification, and\/or suppression of EF Core operations. This includes low-level database operations such as executing a command, as well as higher-level operations, such as calls to Interceptors are registered when configuring a DbContext instance, either in Code for all the examples in this post is available on GitHub<\/a>.<\/p><\/blockquote>\n EF7 includes the following enhancements to interceptors:<\/p>\n In addition, EF7 includes new traditional .NET events for:<\/p>\n The following sections show some examples of using these new interception capabilities.<\/p>\n The new IMaterializationInterceptor<\/a> 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:<\/p>\n 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:<\/p>\n Using an interface is common with interceptors since it allows the same interceptor to work with many different entity types. For example:<\/p>\n Notice that the The interceptor must then implement the appropriate method from An instance of this interceptor is registered when configuring the \ud83d\udca1TIP<\/strong>\nThis interceptor is stateless, which is common, so a single instance is created and shared between all Now, whenever a Produces output:<\/p>\n EF Core makes use of .NET LINQ queries. 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:<\/p>\n \ud83d\udca1TIP<\/strong>\nThis query uses the 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 Uf there are multiple customers with the same 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, we can intercept the query expression tree and add the secondary ordering dynamically whenever an This interface is implemented by the entity types of interest:<\/p>\n We then need an interceptor that implements This probably looks pretty complicated–and it is! Working with expression trees is typically not easy. Let’s look at what’s happening:<\/p>\n This interceptor is registered in the same way as we did for the first example. Executing This will now always produce a stable ordering, even if there are multiple customers with the same 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 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.<\/p>\n 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.<\/p>\n For example, imagine if we instead changed our In this case the EF Core supports the optimistic concurrency pattern<\/a> 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.+<\/p>\n EF signals a violation of optimistic concurrency by throwing a 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:<\/p>\n There are several things worth noting about this interceptor:<\/p>\n EF Core 7.0 (EF7) adds several new interceptors and enhances the behavior of already existing interceptors. Interceptors allow application react to what EF is doing in a similar way to events. However, interceptors also allow the behavior of EF to be changed by suppressing or replacing the action that EF was going to perform, or by modifying or replacing the result of that action. Where appropriate, interceptors can perform async database access, allowing complete database commands to be changed by an interceptor.<\/p>\n For more information of EF Core interceptors, see Interceptors<\/em><\/a> in the EF Core documentation.<\/p>\n Also, the EF Team showed some additional in-depth interceptor examples in an episode of the .NET Data Community Standup–available to watch now on YouTube<\/a>.<\/p>\n Finally, don’t forget that all the code in this post is available on GitHub<\/a>.<\/p>\n EF7 is the successor to EF Core 6.0, not to be confused with EF6<\/a>. If you are considering upgrading from EF6, please read our guide to port from EF6 to EF Core<\/a>.<\/p>\n EF7 is distributed exclusively as a set of NuGet packages. For example, to add the SQL Server provider to your project, you can use the following command using the dotnet tool:<\/p>\n This following table links to the preview 7 versions of the EF Core packages and describes what they are used for.<\/p>\nInterceptors<\/h2>\n
SaveChanges<\/code>. Interceptors support async operations and the ability to modify or suppress operations, making them more powerful than traditional events, logging, and diagnostics.<\/p>\nOnConfiguring<\/code> or AddDbContext<\/code>. For example:<\/p>\npublic class ExampleContext : DbContext\r\n{\r\n protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)\r\n => optionsBuilder.AddInterceptors(new TaggedQueryCommandInterceptor());\r\n}<\/code><\/pre>\nNew and improved interceptors in EF7<\/h3>\n
\n
DbUpdateConcurrencyException<\/code>)<\/li>\nDbConnection<\/code> by EF Core<\/a><\/li>\nDbCommand<\/code> after it has been initialized<\/a><\/li>\n<\/ul>\n\n
DetectChanges<\/code> interception)<\/li>\n<\/ul>\nSimple actions on entity creation<\/h3>\n
\n
public interface IHasRetrieved\r\n{\r\n DateTime Retrieved { get; set; }\r\n}<\/code><\/pre>\npublic class Customer : IHasRetrieved\r\n{\r\n public int Id { get; set; }\r\n public string Name { get; set; } = null!;\r\n public string? PhoneNumber { get; set; }\r\n\r\n [NotMapped]\r\n public DateTime Retrieved { get; set; }\r\n}<\/code><\/pre>\n[NotMapped]<\/code> attribute is used to indicate that this property is used only while working with the entity, and should not be persisted to the database.<\/p>\nIMaterializationInterceptor<\/code> and set the time retrieved:<\/p>\npublic class SetRetrievedInterceptor : IMaterializationInterceptor\r\n{\r\n public object InitializedInstance(MaterializationInterceptionData materializationData, object instance)\r\n {\r\n if (instance is IHasRetrieved hasRetrieved)\r\n {\r\n hasRetrieved.Retrieved = DateTime.UtcNow;\r\n }\r\n\r\n return instance;\r\n }\r\n}<\/code><\/pre>\nDbContext<\/code>:<\/p>\n\r\npublic class CustomerContext : DbContext\r\n{\r\n private static readonly SetRetrievedInterceptor _setRetrievedInterceptor = new();\r\n\r\n public DbSet<Customer> Customers => Set<Customer>();\r\n\r\n protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) \r\n => optionsBuilder\r\n .AddInterceptors(_setRetrievedInterceptor)\r\n .UseSqlite(\"Data Source = customers.db\");\r\n}<\/code><\/pre>\nDbContext<\/code> instances.<\/p><\/blockquote>\nCustomer<\/code> is queried from the database, the Retrieved<\/code> property will be set automatically. For example:<\/p>\nusing (var context = new CustomerContext())\r\n{\r\n var customer = context.Customers.Single(e => e.Name == \"Alice\");\r\n Console.WriteLine($\"Customer '{customer.Name}' was retrieved at '{customer.Retrieved.ToLocalTime()}'\");\r\n}<\/code><\/pre>\nCustomer 'Alice' was retrieved at '8\/6\/2022 7:50:25 PM'<\/code><\/pre>\nLINQ expression tree interception<\/h3>\n
List<Customer> GetPageOfCustomers(string sortProperty, int page)\r\n{\r\n using var context = new CustomerContext();\r\n\r\n return context.Customers\r\n .OrderBy(e => EF.Property<object>(e, sortProperty))\r\n .Skip(page * 20).Take(20).ToList();\r\n}<\/code><\/pre>\nEF.Property<\/code><\/a> method to specify the property to sort by. This allows the application to dynamically pass in the property name, easily allowing sorting by any property of the entity type.<\/p><\/blockquote>\nCustomer.City<\/code>:<\/p>\nSELECT \"c\".\"Id\", \"c\".\"City\", \"c\".\"Name\", \"c\".\"PhoneNumber\"\r\nFROM \"Customers\" AS \"c\"\r\nORDER BY \"c\".\"City\"\r\nLIMIT @__p_1 OFFSET @__p_0<\/code><\/pre>\nCity<\/code>, then the ordering of this query is not stable. This could lead to missing or duplicate results as the user pages through the data.<\/p>\nOrderBy<\/code> is encountered. To facilitate this, we will again use an interface, this time for any entity that has an integer primary key:<\/p>\npublic interface IHasIntKey\r\n{\r\n int Id { get; }\r\n}<\/code><\/pre>\npublic class Customer : IHasIntKey\r\n{\r\n public int Id { get; set; }\r\n public string Name { get; set; } = null!;\r\n public string? City { get; set; }\r\n public string? PhoneNumber { get; set; }\r\n}<\/code><\/pre>\nIQueryExpressionInterceptor<\/code><\/a>:<\/p>\npublic class KeyOrderingExpressionInterceptor : IQueryExpressionInterceptor\r\n{\r\n public Expression ProcessingQuery(Expression queryExpression, QueryExpressionEventData eventData)\r\n => new KeyOrderingExpressionVisitor().Visit(queryExpression);\r\n\r\n private class KeyOrderingExpressionVisitor : ExpressionVisitor\r\n {\r\n private static readonly MethodInfo ThenByMethod\r\n = typeof(Queryable).GetMethods()\r\n .Single(m => m.Name == nameof(Queryable.ThenBy) && m.GetParameters().Length == 2);\r\n\r\n protected override Expression VisitMethodCall(MethodCallExpression? methodCallExpression)\r\n {\r\n var methodInfo = methodCallExpression!.Method;\r\n if (methodInfo.DeclaringType == typeof(Queryable)\r\n && methodInfo.Name == nameof(Queryable.OrderBy)\r\n && methodInfo.GetParameters().Length == 2)\r\n {\r\n var sourceType = methodCallExpression.Type.GetGenericArguments()[0];\r\n if (typeof(IHasIntKey).IsAssignableFrom(sourceType))\r\n {\r\n var lambdaExpression = (LambdaExpression)((UnaryExpression)methodCallExpression.Arguments[1]).Operand;\r\n var entityParameterExpression = lambdaExpression.Parameters[0];\r\n\r\n return Expression.Call(\r\n ThenByMethod.MakeGenericMethod(\r\n sourceType,\r\n typeof(int)),\r\n methodCallExpression,\r\n Expression.Lambda(\r\n typeof(Func<,>).MakeGenericType(entityParameterExpression.Type, typeof(int)),\r\n Expression.Property(entityParameterExpression, nameof(IHasIntKey.Id)),\r\n entityParameterExpression));\r\n }\r\n }\r\n\r\n return base.VisitMethodCall(methodCallExpression);\r\n }\r\n }\r\n}<\/code><\/pre>\n\n
ExpressionVisitor<\/code><\/a>. The visitor overrides VisitMethodCall<\/code>, which will be called whenever there is a call to a method in the query expression tree.<\/li>\nQueryable.OrderBy<\/code><\/a> method we are interested in.<\/li>\nIHasIntKey<\/code> interface.<\/li>\nOrderBy(e => ...)<\/code>. We extract the lambda expression from this call and get the parameter used in that expression–that is, the e<\/code>.<\/li>\nMethodCallExpression<\/code> using the Expression.Call<\/code><\/a> builder method. In this case, the method being called is ThenBy(e => e.Id)<\/code>. We build this using the parameter extracted above and a property access to the Id<\/code> property of the IHasIntKey<\/code> interface.<\/li>\nOrderBy(e => ...)<\/code>, and so the end result is an expression for OrderBy(e => ...).ThenBy(e => e.Id)<\/code>.<\/li>\nThenBy<\/code> call.<\/li>\nGetPageOfCustomers<\/code> now generates the following SQL:<\/p>\nSELECT \"c\".\"Id\", \"c\".\"City\", \"c\".\"Name\", \"c\".\"PhoneNumber\"\r\nFROM \"Customers\" AS \"c\"\r\nORDER BY \"c\".\"City\", \"c\".\"Id\"\r\nLIMIT @__p_1 OFFSET @__p_0<\/code><\/pre>\nCity<\/code>.<\/p>\nGetPageOfCustomers<\/code> method like so:<\/p>\nList<Customer> GetPageOfCustomers2(string sortProperty, int page)\r\n{\r\n using var context = new CustomerContext();\r\n\r\n return context.Customers\r\n .OrderBy(e => EF.Property<object>(e, sortProperty))\r\n .ThenBy(e => e.Id)\r\n .Skip(page * 20).Take(20).ToList();\r\n}<\/code><\/pre>\nThenBy<\/code> 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.<\/p>\nOptimistic concurrency interception<\/h3>\n
DbUpdateConcurrencyException<\/code><\/a>. In EF7 ISaveChangesInterceptor<\/code><\/a> has new methods ThrowingConcurrencyException<\/code> and ThrowingConcurrencyExceptionAsync<\/code> that are called before the DbUpdateConcurrencyException<\/code> is thrown. These interception points allow the exception to be suppressed, possibly coupled with async database changes to resolve the violation.<\/p>\npublic class SuppressDeleteConcurrencyInterceptor : ISaveChangesInterceptor\r\n{\r\n public InterceptionResult ThrowingConcurrencyException(\r\n ConcurrencyExceptionEventData eventData,\r\n InterceptionResult result)\r\n {\r\n if (eventData.Entries.All(e => e.State == EntityState.Deleted))\r\n {\r\n Console.WriteLine(\"Suppressing Concurrency violation for command:\");\r\n Console.WriteLine(((RelationalConcurrencyExceptionEventData) eventData).Command.CommandText);\r\n\r\n return InterceptionResult.Suppress();\r\n }\r\n\r\n return result;\r\n }\r\n\r\n public ValueTask<InterceptionResult> ThrowingConcurrencyExceptionAsync(\r\n ConcurrencyExceptionEventData eventData,\r\n InterceptionResult result,\r\n CancellationToken cancellationToken = default)\r\n => new(ThrowingConcurrencyException(eventData, result));\r\n}<\/code><\/pre>\n\n
SaveChanges<\/code> or SaveChangesAsync<\/code>. However, if all application code is async, then only ThrowingConcurrencyExceptionAsync<\/code> needs to be implemented. Likewise, if the application never uses synchronous database methods, then only ThrowingConcurrencyException<\/code> 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.)<\/li>\nEntityEntry<\/code><\/a> 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.<\/li>\nConcurrencyExceptionEventData<\/code><\/a> object can be cast to a RelationalConcurrencyExceptionEventData<\/code><\/a> object. This provides additional, relational-specific information about the database operation being performed. In this case, the relation command text is printed to the console.<\/li>\nInterceptionResult.Suppress()<\/code> tells EF Core to suppress the action it was about to take–in this case, throwing the DbUpdateConcurrencyException<\/code>. This is one of the most powerful features of interceptors to change the behavior if EF Core<\/em>, rather than just observing what EF Core is doing.<\/li>\n<\/ul>\nSummary<\/h3>\n
EF7 Prerequisites<\/h2>\n
\n
How to get EF7 previews<\/h2>\n
dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 7.0.0-preview.7.22376.2<\/code><\/pre>\n