CodeSync.Tools.EFExtensions 1.0.0

CodeSync.Tools.EFExtensions

Lightweight Entity Framework Core helpers for updating detached entities safely and predictably.

This package currently provides DbContextUpdateExtensions.AttachOrMerge, a focused extension that:

• Attaches a detached entity to a DbContext and marks it for update (full overwrite), or
• Merges values into an already-tracked instance with the same primary key, or
• Allows partial updates by marking only selected properties as modified.

It intentionally does not traverse or update related entities/collections to avoid unexpected graph changes.

Requirements

• .NET9
• Entity Framework Core9.x (package references Microsoft.EntityFrameworkCore)

Installation

• .NET CLI: dotnet add package CodeSync.Tools.EFExtensions
• Package Manager: Install-Package CodeSync.Tools.EFExtensions

Quick start

using CodeSync.Tools.EFExtensions;
using Microsoft.EntityFrameworkCore;

// Full overwrite of all mapped scalar properties on the root entity
await using var db = new AppDbContext();
var detachedOrder = new Order { Id =123, Status = "Shipped", Notes = "Left at door" };

db.AttachOrMerge(detachedOrder); // fullOverwrite = true by default
await db.SaveChangesAsync();

API

public static class DbContextUpdateExtensions
{
 // If entity with same PK is tracked: copy scalar values onto it.
 // Else attach incoming instance. You can:
 // - Set fullOverwrite = true (default) to update all mapped scalar columns on the root.
 // - Set fullOverwrite = false and specify a whitelist of properties to mark as modified.
 public static void AttachOrMerge<TEntity>(this DbContext db,
 TEntity incoming,
 bool fullOverwrite = true,
 params Expression<Func<TEntity, object>>[] modifiedProps)
 where TEntity : class;
}

Behavior summary

• Tracked instance exists (same primary key):
• CurrentValues.SetValues(incoming) is applied to the tracked entity (scalar properties only).
• Not tracked:
• Entity is attached as Unchanged.
• If fullOverwrite = true, the entity state is set to Modified (all mapped scalar columns on the root will be updated).
• If fullOverwrite = false and modifiedProps provided, only those properties are marked as modified.
• No navigation/collection traversal is performed.

Examples

###1) Full overwrite of root scalar properties

var product = new Product { Id =10, Name = "Widget X", Price =19.99m };
db.AttachOrMerge(product); // marks entire root as Modified (scalar columns)
await db.SaveChangesAsync();

###2) Partial update (selected properties only)

var customer = new Customer { Id =42, Email = "new@example.com", IsActive = true };

db.AttachOrMerge(customer,
 fullOverwrite: false,
 c => c.Email,
 c => c.IsActive);
await db.SaveChangesAsync();

###3) Merge into an already-tracked entity

// Suppose the context is already tracking a Customer with Id =42 (e.g., loaded earlier)
var incoming = new Customer { Id =42, Name = "Updated Name" };

db.AttachOrMerge(incoming); // copies scalar values onto the tracked instance
await db.SaveChangesAsync();

Notes and guidance

• Primary key must be set on the incoming entity so the tracked instance can be found.
• Only root entity scalar properties are updated; navigations/collections are ignored by design.
• Suitable for HTTP PATCH/PUT patterns where you want predictable root updates without graph changes.
• If you need graph updates, handle related entities explicitly per your domain rules.

License

MIT