Update Command
The EntityUpdateCommand<TKey, TUpdateModel, TReadModel> represents a command to update an entire entity identified by a specific key using the provided update model. Unlike patch operations that modify specific fields, update commands replace the complete entity data while preserving its identity.
Overview
This command is a fundamental part of the CQRS (Command Query Responsibility Segregation) pattern in the Arbiter framework. It provides a strongly-typed approach to entity updates with built-in support for audit tracking, cache invalidation, and security context preservation.
public record EntityUpdateCommand<TKey, TUpdateModel, TReadModel>
: EntityModelBase<TUpdateModel, TReadModel>, ICacheExpire
Key Features
- Complete Entity Replacement: Updates the entire entity with new data while maintaining its identity
- Automatic Upsert Logic: Creates new entities if they don't exist, updates existing ones (Version 2.0)
- Type Safety: Strongly-typed key, update model, and read model parameters
- Security Integration: Built-in
ClaimsPrincipalsupport for user context and authorization - Cache Management: Automatic cache invalidation through
ICacheExpireinterface - Audit Support: Seamless integration with audit tracking behaviors
- Cross-Database Support: Works with both Entity Framework Core and MongoDB implementations
- Validation Ready: Compatible with validation behaviors and pipeline processing
Type Parameters
| Parameter | Description |
|---|---|
TKey |
The type of the key used to identify the entity (e.g., int, Guid, string) |
TUpdateModel |
The type of the update model containing the complete data for replacement |
TReadModel |
The type of the read model returned as the result of the command |
Constructor Parameters
| Parameter | Type | Description |
|---|---|---|
principal |
ClaimsPrincipal? |
The user's security context. Used for audit tracking and authorization |
id |
TKey |
The identifier of the entity to update (must not be null) |
model |
TUpdateModel |
The update model containing the complete replacement data |
upsert |
bool |
A value indicating whether to insert the entity if it does not exist (default: false) |
Upsert Functionality
The EntityUpdateCommand supports upsert (update or insert) operations through the optional upsert parameter. When enabled, the command will automatically create a new entity if one with the specified ID doesn't exist, or update the existing entity if it does.
Automatic Metadata Tracking
When an entity implements tracking interfaces, the command automatically populates metadata:
ITrackCreated: SetsCreatedtimestamp andCreatedByuser identifier for new entities (upsert scenario)ITrackUpdated: SetsUpdatedtimestamp andUpdatedByuser identifier for all operations
Handler Implementations
The Arbiter framework provides built-in handlers for different data access patterns:
Entity Framework Handler
EntityUpdateCommandHandler<TContext, TEntity, TKey, TUpdateModel, TReadModel>
The Entity Framework handler applies registered entity modifiers before saving. It uses the Updated operation, or Created when an upsert inserts a new entity.
MongoDB Handler
EntityUpdateCommandHandler<TRepository, TEntity, TKey, TUpdateModel, TReadModel>
Service Registration
Register update command support using the provided extension methods:
Entity Framework
services.AddEntityCommands<MyDbContext, Product, int, ProductReadModel, ProductCreateModel, ProductUpdateModel>();
// Or register update command individually
services.AddEntityUpdateCommand<MyDbContext, Product, int, ProductUpdateModel, ProductReadModel>();
MongoDB
services.AddEntityCommands<IProductRepository, Product, int, ProductReadModel, ProductCreateModel, ProductUpdateModel>();
// Or register update command individually
services.AddEntityUpdateCommand<IProductRepository, Product, int, ProductUpdateModel, ProductReadModel>();
Model Mapping with IMapper
The update command relies on IMapper<TSource, TDestination> to convert between different model types during the entity update process. The framework uses two key mapping operations:
UpdateModel to Entity Mapping
The command handler uses IMapper<TUpdateModel, TEntity> to convert the incoming update model into an entity that can be persisted to the database:
Mapper.Map<TUpdateModel, TEntity>(request.Model, entity);
Entity to ReadModel Mapping
After the entity is updated and saved, IMapper<TEntity, TReadModel> converts the persisted entity into a read model for the response:
return Mapper.Map<TEntity, TReadModel>(entity);
Pipeline Behaviors
The update command automatically includes several pipeline behaviors that execute in the pipeline:
Tenant Security:
TenantDefaultCommandBehaviorandTenantAuthenticateCommandBehavior(if entity implementsIHaveTenant<TKey>)TenantDefaultCommandBehavior: Automatically sets the tenant ID from the current user's claims when not explicitly providedTenantAuthenticateCommandBehavior: Validates that the user has access to the specified tenant and ensures tenant isolation
Validation:
ValidateEntityModelCommandBehavior- Performs model validation using data annotations or FluentValidation rules defined on the update model
- Throws validation exceptions if the model is invalid, which are automatically converted to HTTP 400 responses in web applications
Notifications:
EntityChangeNotificationBehavior- Publishes domain events or notifications when entities are updated, allowing other parts of the system to react to changes
- Useful for implementing event-driven architectures and cross-cutting concerns like logging or cache invalidation
Usage Examples
Basic Usage
var updateModel = new ProductUpdateModel
{
Name = "Updated Product",
Description = "An updated description of the product",
Price = 29.99m
};
var principal = new ClaimsPrincipal(new ClaimsIdentity([new(ClaimTypes.Name, "JohnDoe")]));
var command = new EntityUpdateCommand<int, ProductUpdateModel, ProductReadModel>(principal, 123, updateModel);
var result = await mediator.Send(command);
Console.WriteLine($"Updated product: {result?.Name}");
In ASP.NET Core Controller
[HttpPut("{id}")]
public async Task<ProductReadModel?> UpdateProduct(int id, [FromBody] ProductUpdateModel updateModel)
{
var command = new EntityUpdateCommand<int, ProductUpdateModel, ProductReadModel>(User, id, updateModel);
return await mediator.Send(command);
}
In Minimal API Endpoint
app.MapPut("/products/{id:int}", async (
int id,
[FromServices] IMediator mediator,
[FromBody] ProductUpdateModel updateModel,
ClaimsPrincipal user) =>
{
var command = new EntityUpdateCommand<int, ProductUpdateModel, ProductReadModel>(user, id, updateModel);
var result = await mediator.Send(command);
return result != null ? Results.Ok(result) : Results.NotFound();
});
Return Values
- Success: Returns the
TReadModelrepresenting the updated entity - Entity Not Found: Returns
nullwhen the entity with the specified ID doesn't exist - Exception: Throws appropriate exceptions for validation or data access errors
Error Handling
The command handlers include built-in error handling and will throw appropriate exceptions:
ArgumentNullException: When the id or model parameters are nullDomainException: For business rule violations- Database exceptions: For data access errors
Best Practices
- Model Validation: Implement data annotations or FluentValidation on your update models
- Mapping Configuration: Configure Mapper for
TUpdateModeltoTEntitymapping - Security: Always pass the current user's
ClaimsPrincipalfor proper audit tracking - Null Handling: The command constructor validates that the id and model are not null
- Cache Tags: The framework automatically manages cache invalidation based on entity types
- Entity Existence: The command automatically checks if the entity exists before updating
- Authorization: Implement appropriate authorization checks in your application layer