Class ConcurrencyException
Exception thrown when an optimistic concurrency conflict occurs.
public class ConcurrencyException : ConflictException, ISerializable
- Inheritance
-
ConcurrencyException
- Implements
- Inherited Members
Examples
if (entity.Version != expectedVersion)
{
throw new ConcurrencyException("Order", orderId.ToString(), expectedVersion, entity.Version);
}
Remarks
This exception indicates that an update operation failed because the resource was modified by another process since it was last read. It maps to HTTP status code 409 (Conflict).
This is a specialized form of ConflictException for optimistic locking scenarios where version or ETag checking is used.
Contract. This is the canonical, typed signal for an optimistic-concurrency conflict across the framework. A store or repository that detects a lost update (a version, ETag, or timestamp mismatch) MUST surface this exception type — never a raw provider exception (for example a SQL error) and never a silent boolean failure — and MUST populate the version/ETag metadata (ExpectedVersion/ActualVersion or their string equivalents) so a caller can distinguish a conflict from other failures and decide whether to reload and retry. Because it derives from ConflictException (an application exception mapping to HTTP 409), framework data-execution paths propagate it to the caller unchanged rather than rewrapping it as a generic failure.
Use this exception when:
- The expected version doesn't match the actual version
- An ETag comparison fails
- A timestamp-based optimistic lock is violated
Constructors
ConcurrencyException()
Initializes a new instance of the ConcurrencyException class.
public ConcurrencyException()
ConcurrencyException(string)
Initializes a new instance of the ConcurrencyException class with a specified error message.
public ConcurrencyException(string message)
Parameters
messagestringThe error message that explains the reason for the exception.
ConcurrencyException(string, Exception?)
Initializes a new instance of the ConcurrencyException class with a message and inner exception.
public ConcurrencyException(string message, Exception? innerException)
Parameters
messagestringThe error message that explains the reason for the exception.
innerExceptionExceptionThe exception that is the cause of the current exception.
ConcurrencyException(string, string?, long, long)
Initializes a new instance of the ConcurrencyException class with version information.
public ConcurrencyException(string resource, string? resourceId, long expectedVersion, long actualVersion)
Parameters
resourcestringThe type or name of the resource.
resourceIdstringThe identifier of the resource.
expectedVersionlongThe version that was expected.
actualVersionlongThe actual current version.
ConcurrencyException(string, string?, string, string)
Initializes a new instance of the ConcurrencyException class with string version information.
public ConcurrencyException(string resource, string? resourceId, string expectedVersion, string actualVersion)
Parameters
resourcestringThe type or name of the resource.
resourceIdstringThe identifier of the resource.
expectedVersionstringThe version or ETag that was expected.
actualVersionstringThe actual current version or ETag.
Properties
ActualVersion
Gets the actual current version of the resource.
public long? ActualVersion { get; }
Property Value
ActualVersionString
Gets the actual version as a string (for ETag or non-numeric versions).
public string? ActualVersionString { get; }
Property Value
ExpectedVersion
Gets the version that was expected when the operation was attempted.
public long? ExpectedVersion { get; }
Property Value
ExpectedVersionString
Gets the expected version as a string (for ETag or non-numeric versions).
public string? ExpectedVersionString { get; }
Property Value
Methods
ETagMismatch(string, string, string, string)
Creates a ConcurrencyException for an ETag mismatch.
public static ConcurrencyException ETagMismatch(string resource, string resourceId, string expectedETag, string actualETag)
Parameters
resourcestringThe type or name of the resource.
resourceIdstringThe resource identifier.
expectedETagstringThe expected ETag value.
actualETagstringThe actual ETag value.
Returns
- ConcurrencyException
A new ConcurrencyException instance.
ForAggregate<TAggregate>(object, long, long)
Creates a ConcurrencyException for an aggregate version mismatch.
public static ConcurrencyException ForAggregate<TAggregate>(object aggregateId, long expectedVersion, long actualVersion)
Parameters
aggregateIdobjectThe aggregate identifier.
expectedVersionlongThe expected version.
actualVersionlongThe actual version.
Returns
- ConcurrencyException
A new ConcurrencyException instance.
Type Parameters
TAggregateThe type of the aggregate.
GetProblemDetailsExtensions()
Gets additional extension data to include in problem details.
protected override IDictionary<string, object?>? GetProblemDetailsExtensions()
Returns
- IDictionary<string, object>
A dictionary of extension data to include in the problem details response, or null if no extensions should be added.
Remarks
Derived types can override this method to add type-specific data to the
problem details response. For example, a ValidationException might
include a dictionary of field-level validation errors.
The returned dictionary keys will be added to the problem details Extensions collection.