diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index 90df3e0d75..ef72434d62 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -7,6 +7,11 @@ "build_output_subfolder": "ef", "locale": "en-us", "open_to_public_contributors": true, + "xref_query_tags": [ + "/dotnet", + "/ef", + "/aspnet" + ], "type_mapping": { "Conceptual": "Content", "ManagedReference": "Content", diff --git a/entity-framework/core/miscellaneous/context-pooling.md b/entity-framework/core/miscellaneous/context-pooling.md new file mode 100644 index 0000000000..3d47e3dda9 --- /dev/null +++ b/entity-framework/core/miscellaneous/context-pooling.md @@ -0,0 +1,40 @@ +--- +title: DbContext Pooling +description: DbContext pooling in Entity Framework Core +author: rick-anderson +ms.author: riande +ms.date: 9/19/2020 +uid: core/miscellaneous/dbcontextpool +--- +# DbContext pooling + +`AddDbContextPool` enables pooling of `DbContext` instances. Context pooling can increase throughput in high-scale scenarios such as web servers by reusing context instances, rather than creating new instances for each request. + +The typical pattern in an ASP.NET Core app using EF Core involves registering a custom type into the [dependency injection](/aspnet/core/fundamentals/dependency-injection) container and obtaining instances of that type through constructor parameters in controllers or Razor Pages. Using constructor injection, a new context instance is created for each request. + + enables a pool of reusable context instances. To use context pooling, use the `AddDbContextPool` method instead of `AddDbContext` during service registration: + +``` csharp +services.AddDbContextPool( + options => options.UseSqlServer(connectionString)); +``` + +When `AddDbContextPool` is used, at the time a context instance is requested, EF first checks if there is an instance available in the pool. Once the request processing finalizes, any state on the instance is reset and the instance is itself returned to the pool. + +This is conceptually similar to how connection pooling operates in ADO.NET providers and has the advantage of saving some of the cost of initialization of the context instance. + +The `poolSize` parameter of sets the maximum number of instances retained by the pool. Once `poolSize` is exceeded, new context instances are not cached and EF falls back to the non-pooling behavior of creating instances on demand. + +## Limitations + +Apps should be profiled and tested to show that context initialization is a significant cost. + +`AddDbContextPool` has a few limitations on what can be done in the `OnConfiguring` method of the context. + +> [!WARNING] +> Avoid using context pooling in apps that maintain state. For example, private fields in the context that shouldn't be shared across requests. EF Core only resets the state that it is aware of before adding a context instance to the pool. + +Context pooling works by reusing the same context instance across requests. This means that it's effectively registered as a [Singleton](/aspnet/core/fundamentals/dependency-injection#service-lifetimes) in terms of the instance itself so that it's able to persist. + + +Context pooling is intended for scenarios where the context configuration, which includes services resolved, is fixed between requests. For cases where [Scoped](/aspnet/core/fundamentals/dependency-injection#service-lifetimes) services are required, or configuration needs to be changed, don't use pooling. The performance gain from pooling is usually negligible except in highly optimized scenarios. diff --git a/entity-framework/toc.yml b/entity-framework/toc.yml index 7de1e394b5..e29c8579e9 100644 --- a/entity-framework/toc.yml +++ b/entity-framework/toc.yml @@ -78,6 +78,8 @@ href: core/miscellaneous/async.md - name: Logging href: core/miscellaneous/logging.md + - name: Connection pooling + href: core/miscellaneous/context-pooling.md - name: Connection resiliency href: core/miscellaneous/connection-resiliency.md - name: Testing