Table of Contents

Class RequiredDateTimeOffset<TSelf>

Namespace
Trellis
Assembly
Trellis.Core.dll

Base class for creating strongly-typed DateTimeOffset value objects that prevent primitive obsession for instants on the wall clock with an offset from UTC. Rejects only null by default; MinValue rejection is opt-in via the NotDefaultAttribute attribute. Recommended for any DateTimeOffset type used as an EF-mapped property to preserve the database invariant guarantee enforced by TrellisScalarConverter on rehydration.

public abstract class RequiredDateTimeOffset<TSelf> : ScalarValueObject<TSelf, DateTimeOffset>, IComparable<ValueObject>, IComparable, IEquatable<ValueObject>, IConvertible, IFormattable where TSelf : RequiredDateTimeOffset<TSelf>, IScalarValue<TSelf, DateTimeOffset>

Type Parameters

TSelf
Inheritance
RequiredDateTimeOffset<TSelf>
Implements
Inherited Members
Extension Methods

Examples

Lenient default — only null is rejected:

public partial class EventTimestamp : RequiredDateTimeOffset<EventTimestamp> { }

var ok = EventTimestamp.TryCreate(DateTimeOffset.UtcNow);            // Success
var min = EventTimestamp.TryCreate(DateTimeOffset.MinValue);         // Success (lenient)
var nul = EventTimestamp.TryCreate((DateTimeOffset?)null);           // Failure

Strict opt-in — MinValue rejected:

[NotDefault]
public partial class SubmittedAt : RequiredDateTimeOffset<SubmittedAt> { }

var ok = SubmittedAt.TryCreate(DateTimeOffset.UtcNow);               // Success
var min = SubmittedAt.TryCreate(DateTimeOffset.MinValue);
// Failure: "Submitted At cannot be DateTimeOffset.MinValue."

Remarks

This class extends ScalarValueObject<TSelf, T> to provide a specialized base for DateTimeOffset-based value objects. When used with the partial keyword, the PrimitiveValueObjectGenerator source generator automatically creates:

  • IScalarValue<TSelf, DateTimeOffset> implementation for ASP.NET Core automatic validation
  • TryCreate(DateTimeOffset) - Factory method for DateTimeOffsets (required by IScalarValue)
  • TryCreate(DateTimeOffset?, string?) - Factory method with null validation and custom field name
  • TryCreate(string?, string?) - Factory method for parsing strings with validation
  • IParsable<T> implementation (Parse, TryParse)
  • JSON serialization support via ParsableJsonConverter<T>
  • Explicit cast operator from DateTimeOffset
  • OpenTelemetry activity tracing

Validation rules emitted by the source generator:

  • null is always rejected with the per-type "cannot be empty." message.
  • Apply NotDefaultAttribute to additionally reject MinValue with the per-type "cannot be DateTimeOffset.MinValue." message. Recommended for any DateTimeOffset used as an EF-mapped property to preserve the database invariant guarantee enforced by TrellisScalarConverter on rehydration.

Common use cases:

  • Audit timestamps (CreatedAt, ModifiedAt, DeletedAt) that need to retain the originating offset
  • Time-zone-aware event timestamps (SubmittedAt, ProcessedAt)
  • Any domain concept requiring a non-default DateTimeOffset

Prefer RequiredDateTimeOffset<TSelf> over RequiredDateTime<TSelf> when the originating UTC offset is part of the domain contract (cross-time-zone scheduling, audit-trail provenance). Use RequiredDateTime<TSelf> when the value is always stored and read in a single fixed time zone (typically UTC) and the offset is implicit.

Constructors

RequiredDateTimeOffset(DateTimeOffset)

Initializes a new instance of the RequiredDateTimeOffset<TSelf> class with the specified DateTimeOffset value.

protected RequiredDateTimeOffset(DateTimeOffset value)

Parameters

value DateTimeOffset

The DateTimeOffset value.

Methods

ToString()

Returns the DateTimeOffset in ISO 8601 round-trip format ("O") using invariant culture. This ensures JSON serialization via ParsableJsonConverter is deterministic, culture-independent, and preserves the originating UTC offset on round-trip.

public override string ToString()

Returns

string

See Also

ScalarValueObject<TSelf, T>
RequiredDateTime<TSelf>
Edit this page