Z.EntityFramework.Extensions.EFCore 3.103.3

Entity Framework Extensions (for EF Core)

EF Extensions is a library that adds high performances bulk extension methods such as BulkInsert, BulkUpdate, BulkDelete, BulkMerge, and more.

You don't believe us? Just try our live benchmark on .NET Fiddle: https://dotnetfiddle.net/vZQnZt

Using our library will not only allow you to perform bulk operations 5 to 20 times faster but also to consume only 20% of the memory that SaveChanges requires. See Memory & Performance Improvements

The best part of Entity Framework Extensions is how it is integrated so easily with EF Core by simply adding the library to your project. Allowing you to use the power of bulk operations with minimal code changes. It's designed with flexibility in mind, providing you with control over the behavior of operations to suit your specific needs.

Whether you're building a small application or an enterprise-grade system, EF Extensions can help make your data operations faster, more scalable, and more efficient.

With the trust and endorsement of over 5000 customers worldwide, Entity Framework Extensions continues to lead the way in efficient data management.

Resources:

• Official Website: Visit for comprehensive information, updates, tutorials, and more. Learn how EF Extensions can transform your application's data layer.
• Contact Us: Got a question or need help? Don't hesitate to reach out. We're here to help you get the most out of EF Extensions.
• GitHub Issues: Encountered an issue or have a feature request? Let us know on GitHub. Your feedback helps us make EF Extensions better.

Benefits

Adding Entity Framework Extensions in your projects can unlock multiple advantages:

• Optimize Application Performance: By enabling efficient bulk operations, our library can dramatically enhance your application's performance, making data-intensive tasks faster and more responsive.
• Unmatched Customization: With hundreds of customization options at your fingertips, you can customize Entity Framework Extensions to fit your precise needs. This flexibility allows you to handle data in the way that suits your application best.
• Minimize Memory Footprint: Entity Framework Extensions is designed with efficiency in mind. By reducing overhead, it helps lower your application's memory usage, contributing to overall system performance and stability.

Supported EF Core Versions

Entity Framework Extensions actively supports all versions of EF Core. To determine the correct version of our library for your needs, you simply match the major version of EF Core with the corresponding major version of EF Extensions.

Here's a quick guide:

• For EF Core 8.x, use the latest EF Extensions v8.x release.
• For EF Core 7.x, use the latest EF Extensions v7.x release.
• For EF Core 6.x, use the latest EF Extensions v6.x release.
• For EF Core 5.x, use the latest EF Extensions v5.x release.
• For EF Core 3.x, use the latest EF Extensions v3.x release.
• For EF Core 2.x, use the latest EF Extensions v2.x release.

Always ensure you're using the latest version of EF Extensions that corresponds to your EF Core version for the best performance.

Main Bulk Extensions Features

Entity Framework Extensions offers a robust set of bulk and batch operations that can significantly optimize your performance when saving or querying data:

• Bulk Extensions:: These EF Core Bulk Extensions methods are designed to handle large volumes of data efficiently:
  • BulkSaveChanges: Enhances the traditional SaveChanges method for improved performance with large data sets.
  • BulkInsert: Fastest way to insert thousands of entities.
  • BulkUpdate: Fastest way to update thousands of entities.
  • BulkDelete: Fastest way to delete thousands of entities.
  • BulkMerge (BulkUpsert): Combine insert and update operations into one efficient operation.
  • BulkSynchronize: Combines insert, update, and delete operations into one efficient operation.
• Batch Operations: These operations enable you to perform actions directly on the data source without loading data into your context:
  • InsertFromQuery: Insert data directly from a query.
  • UpdateFromQuery: Update data directly from a query. Similar to ExecuteUpdate in EF Core 7+.
  • DeleteFromQuery: Delete data directly from a query. Similar to ExecuteDelete in EF Core 7+.
• Query Operations: Enhance querying capabilities with bulk operations:
  • WhereBulkContains: Optimize your queries when searching for a large list of entities.
  • WhereBulkNotContains: Optimize queries when excluding a large list of entities.
  • BulkRead: Improve performance when needing to read a large amount of data.

Please refer to the documentation page for a more detailed explanation and examples of each operation.

Free Features

Additional features (all free) are released under the https://entityframework-plus.net/ library.

Which Include:

• Saving:
  • SingleInsert
  • SingleUpdate
  • SingleDelete
  • SingleMerge
  • DeleteByKey
  • DeleteRangeByKey
• Audit
• LINQ Dynamic
• Query:
  • Query Cache
  • Query Deferred
  • Query Filter
  • Query Future

Getting Started

One of the major advantages of Entity Framework Extensions is the simplicity and ease of use, especially for those already familiar with EF Core. For instance, if you need to insert thousands of customers into your database, a single line of code is all you need:

context.BulkInsert(customers);

This line use the BulkInsert method that extends your DbContext, offering you the power of bulk operations.

Additionally, if your task involves inserting only the customers that don't already exist in your database, you can achieve this with the InsertIfNotExists option, such as:

context.BulkInsert(customers, options => { options.InsertIfNotExists = true; });

This way, the operation becomes not only efficient but also intelligent, helping you maintain the integrity of your data.

To try various implementations with the library, visit our collection of examples that you can try online:

• EF Extensions - Online Examples

These examples are designed to provide practical understanding of Entity Framework Extensions, showcasing its powerful features and flexible options in different scenarios.

Advanced Usage

Bulk Insert

The EF Core Bulk Insert method is the optimal solution when you need to insert thousands of entities into your database efficiently.

Here are some of the common options available:

• AutoMapOutputDirection: This option allows to optimize performance by not returning outputting values such as identity values.
• InsertIfNotExists: This option ensures only new entities that don't already exist in the database are inserted.
• InsertKeepIdentity: This option allows insertion of specific values into an identity column from your entities.
• IncludeGraph: This option enables insertion of entities along with all related entities found in the entity graph, maintaining the relationships.

Here is an example demonstrating the use of AutoMapOutputDirection and InsertIfNotExists options with the BulkInsert method:

context.BulkInsert(customers, options => {
	options.AutoMapOutputDirection = false;
	options.InsertIfNotExists = true;
});

These options offer extensive control over your bulk insert operations, making Entity Framework Extensions a powerful tool for managing large-scale data operations.

Bulk Update

When dealing with large-scale updates, the EF Core Bulk Update method of Entity Framework Extensions offers various configuration options to optimize and tailor your operations:

• ColumnPrimaryKeyExpression: This option allows you to use a custom key to check for pre-existing entities.
• ColumnInputExpression: This option enables you to specify a subset of columns to update by using an expression.
• ColumnInputNames: This option allows you to specify a subset of columns to update by providing their names.
• IncludeGraph: This option allow updating entities along with all related entities found in the entity graph, maintaining the data relationships.

The following examples illustrate the difference between ColumnInputExpression and ColumnInputNames when setting column names to update:

context.BulkUpdate(customers, options => {
	options.ColumnInputExpression = x => new { x.FirstName, x.LastName };
});

context.BulkUpdate(customers, options => {
	options.ColumnInputNames = new List<string>() { "FirstName", "LastName" };
});

These examples indicate the flexibility in specifying column to update, either by expression or directly by column names, showcasing the versatility of Entity Framework Extensions in catering to different operational requirements.

Bulk Delete

The EF Core Bulk Delete method offers several options for configuration, allowing you to fine-tune your delete operations to suit different scenarios:

• ColumnPrimaryKeyExpression: This option allows the usage of a custom key to verify the existence of entities.
• DeleteMatchedAndConditionExpression: This option enables you to perform or skip the deletion action based on whether all values from the source and destination are equal for the specified properties.
• DeleteMatchedAndOneNotConditionExpression: This option allows you to perform or skip the deletion action if at least one value from the source differs from the destination for the specified properties.
• DeleteMatchedAndFormula: This option lets you perform or skip the deletion action based on a predefined SQL condition.

In the following example, we demonstrate how to use the DeleteMatchedAndFormula option to delete a list of customers who were created more than two years ago:

context.BulkDelete(customers, options => {
	options.DeleteMatchedAndFormula = "DestinationTable.CreatedDate < DATEADD(YEAR, -2, GETDATE())";
});

By using these options, Entity Framework Extensions allows you to implement complex conditions and custom logic within your bulk delete operations, granting you the ability to handle large-scale data deletions in a highly controlled and efficient manner.

Bulk Merge

The EF Core BulkMerge method performs an "upsert" operation: it updates existing entities and inserts non-existing ones.

Here are the common options available for configuration:

• ColumnPrimaryKeyExpression: This option allows for the use of a custom key to verify the existence of entities.
• IgnoreOnMergeInsertExpression: This option enables you to ignore certain columns only for the insert phase of the merge operation.
• IgnoreOnMergeUpdateExpression: This option allows you to ignore specific columns only during the update phase of the merge operation.
• IncludeGraph: This option ensures updating of entities along with all related entities found in the entity graph, preserving data relationships.

In the following example, we demonstrate the use of a custom key to update a list of customers using the ColumnPrimaryKeyExpression option. We also selectively ignore audit columns during the insert or update phase using the IgnoreOnMergeInsertExpression and IgnoreOnMergeUpdateExpression options respectively:

context.BulkMerge(customers, options => {
	options.ColumnPrimaryKeyExpression = x => new { x.Code };
	options.IgnoreOnMergeInsertExpression = x => new { x.UpdatedDate, x.UpdatedBy };
	options.IgnoreOnMergeUpdateExpression = x => new { x.CreatedDate, x.CreatedBy };
});

By effectively utilizing these options, the Entity Framework Extensions allow for robust and flexible upsert operations, enabling complex data manipulation with relative ease and efficiency.

WhereBulkContains

The EF Core WhereBulkContains method is an enhanced version of the Where LINQ method, specifically tailored for cases involving thousands of entities and custom keys. It can be used with practically any type of data source such as:

• Basic types like List<int> and List<Guid>
• Entity Types like List<Customer>
• Anonymous Types
• Lists of Expando Objects

Moreover, you can specify one or more columns to use for the key using either an expression or a string:

// The JOIN clause will use the default entity key (CustomerID) if none is specified
var customers = context.Customers.WhereBulkContains(deserializedCustomers);

// You can specify a custom JOIN clause with one or more properties using a Lambda Expression
var customers = context.Customers.WhereBulkContains(deserializedCustomers, x => x.Code);

// You can specify a custom JOIN clause with one or more properties using a List<string>
var customers = context.Customers.WhereBulkContains(deserializedCustomers, new List<string> { "Code" });

// You can specify a custom JOIN clause with one or more properties using a params string[]
var customers = context.Customers.WhereBulkContains(deserializedCustomers, "Code");

By using that method, Entity Framework Extensions enable you to perform complex queries involving large amounts of data, while maintaining high performance and flexible querying capabilities.

Release Notes

For a comprehensive list of enhancements, fixes, and improvements in each version of the Entity Framework Extensions, refer to the official Release Notes on the GitHub repository.

This documentation provides important details about each version, including new features, resolved issues, and breaking changes (if any). Please ensure you review the release notes before upgrading to newer versions to make the best use of the features and avoid any potential issues.

License

Entity Framework Extensions operates under a paid licensing model. To purchase a license, please visit the official Pricing Page on the Entity Framework Extensions website.