Table of Contents

Class ConcurrencyException

Namespace
Excalibur.Data
Assembly
Excalibur.Data.Abstractions.dll

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

message string

The 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

message string

The error message that explains the reason for the exception.

innerException Exception

The 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

resource string

The type or name of the resource.

resourceId string

The identifier of the resource.

expectedVersion long

The version that was expected.

actualVersion long

The 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

resource string

The type or name of the resource.

resourceId string

The identifier of the resource.

expectedVersion string

The version or ETag that was expected.

actualVersion string

The actual current version or ETag.

Properties

ActualVersion

Gets the actual current version of the resource.

public long? ActualVersion { get; }

Property Value

long?

The actual version, or null if not using numeric versions.

ActualVersionString

Gets the actual version as a string (for ETag or non-numeric versions).

public string? ActualVersionString { get; }

Property Value

string

The actual version string, or null if not specified.

ExpectedVersion

Gets the version that was expected when the operation was attempted.

public long? ExpectedVersion { get; }

Property Value

long?

The expected version, or null if not using numeric versions.

ExpectedVersionString

Gets the expected version as a string (for ETag or non-numeric versions).

public string? ExpectedVersionString { get; }

Property Value

string

The expected version string, or null if not specified.

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

resource string

The type or name of the resource.

resourceId string

The resource identifier.

expectedETag string

The expected ETag value.

actualETag string

The 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

aggregateId object

The aggregate identifier.

expectedVersion long

The expected version.

actualVersion long

The actual version.

Returns

ConcurrencyException

A new ConcurrencyException instance.

Type Parameters

TAggregate

The 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.