Class ValueObjectAttribute<TValue>

Namespace: AdCodicem.ValueObjects.Annotations
Assembly: AdCodicem.ValueObjects.Abstractions.dll

Marks a readonly partial struct as a single-value value object and drives code generation for it.

[AttributeUsage(AttributeTargets.Struct, AllowMultiple = false, Inherited = false)]
public sealed class ValueObjectAttribute<TValue> : Attribute

Type Parameters

TValue

Underlying value type. Supported types are , , , , every built-in integer type, , , , , , , and .

Inheritance

object ← Attribute ← ValueObjectAttribute<TValue>

Inherited Members

Attribute.Equals(object?), Attribute.GetCustomAttribute(Assembly, Type), Attribute.GetCustomAttribute(Assembly, Type, bool), Attribute.GetCustomAttribute(MemberInfo, Type), Attribute.GetCustomAttribute(MemberInfo, Type, bool), Attribute.GetCustomAttribute(Module, Type), Attribute.GetCustomAttribute(Module, Type, bool), Attribute.GetCustomAttribute(ParameterInfo, Type), Attribute.GetCustomAttribute(ParameterInfo, Type, bool), Attribute.GetCustomAttributes(Assembly), Attribute.GetCustomAttributes(Assembly, bool), Attribute.GetCustomAttributes(Assembly, Type), Attribute.GetCustomAttributes(Assembly, Type, bool), Attribute.GetCustomAttributes(MemberInfo), Attribute.GetCustomAttributes(MemberInfo, bool), Attribute.GetCustomAttributes(MemberInfo, Type), Attribute.GetCustomAttributes(MemberInfo, Type, bool), Attribute.GetCustomAttributes(Module), Attribute.GetCustomAttributes(Module, bool), Attribute.GetCustomAttributes(Module, Type), Attribute.GetCustomAttributes(Module, Type, bool), Attribute.GetCustomAttributes(ParameterInfo), Attribute.GetCustomAttributes(ParameterInfo, bool), Attribute.GetCustomAttributes(ParameterInfo, Type), Attribute.GetCustomAttributes(ParameterInfo, Type, bool), Attribute.GetHashCode(), Attribute.IsDefaultAttribute(), Attribute.IsDefined(Assembly, Type), Attribute.IsDefined(Assembly, Type, bool), Attribute.IsDefined(MemberInfo, Type), Attribute.IsDefined(MemberInfo, Type, bool), Attribute.IsDefined(Module, Type), Attribute.IsDefined(Module, Type, bool), Attribute.IsDefined(ParameterInfo, Type), Attribute.IsDefined(ParameterInfo, Type, bool), Attribute.Match(object?), Attribute.TypeId, object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()

Remarks

The declaring type opts into a rule by implementing the interface that declares it, so the compiler checks its signature: , , , , , , and . All are optional, and a rule written without its interface is reported as VO0011 rather than silently ignored.

Declarative constraints set on this attribute (, ), like the pattern of and the bounds of and , are checked before runs, and also feed the generated OpenAPI schema, so a rule is stated once and enforced everywhere.

Properties

AllowDefault

Gets or sets a value indicating whether the analyzer tolerates default and parameterless construction.

public bool AllowDefault { get; set; }

Property Value

bool

Remarks

Those expressions produce an instance that never went through validation. They are reported as errors by the analyzers shipped with AdCodicem.ValueObjects unless this is set, which is occasionally needed for a value object whose default state is meaningful, such as a sequence number starting at zero. They are reported where default or new is written: a parameter defaulting to default on its declaration, not at each call that leaves the argument out.

AllowEmpty

Gets or sets a value indicating whether an empty string is accepted.

public bool AllowEmpty { get; set; }

Property Value

bool

Remarks

Only meaningful for . A null value is always rejected: a value object that may be absent is expressed as a nullable value object, never as one wrapping null.

Arithmetic

Gets or sets a value indicating whether arithmetic operators and are generated.

public bool Arithmetic { get; set; }

Property Value

bool

Remarks

Requires a numeric underlying type. Every result is re-validated.

Comparison

Gets or sets how two values are compared for equality, ordering and hashing.

public StringComparison Comparison { get; set; }

Property Value

StringComparison

Remarks

Only meaningful when the underlying type is . Defaults to : culture-independent, the fastest option, and the only one an EF Core provider can translate faithfully. Choose when the value is not case-normalized, and make sure the database collation agrees.

Description

Gets or sets the description surfaced in the OpenAPI schema.

public string? Description { get; set; }

Property Value

string?

Remarks

Defaults to the XML documentation summary of the declaring type when it is available.

Example

Gets or sets an example value surfaced in the OpenAPI schema.

public string? Example { get; set; }

Property Value

string?

ExplicitConversionFromValue

Gets or sets a value indicating whether an explicit conversion from the underlying value is generated.

public bool ExplicitConversionFromValue { get; set; }

Property Value

bool

Remarks

The conversion validates, and throws on a rejected value.

ImplicitConversionToValue

Gets or sets a value indicating whether an implicit conversion to the underlying value is generated.

public bool ImplicitConversionToValue { get; set; }

Property Value

bool

Remarks

Reading stays terse (string s = iban;) while construction remains explicit and validated.

MaxLength

Gets or sets the maximum accepted length. A negative value means unconstrained.

public int MaxLength { get; set; }

Property Value

int

Remarks

Only meaningful for . Emitted as the maxLength OpenAPI keyword and used by the EF Core integration to size the column, so the value object maps to a bounded column rather than an unbounded one.

Maximum

Gets or sets the inclusive upper bound, written as text in the one form of the underlying type.

[Obsolete("Implement IValueObjectMaximum<T> with a static Maximum property of the underlying type instead. A bound written as text is read under one grammar per type the compiler cannot check, and will be removed in the next major version.", DiagnosticId = "VO0028")]
public string? Maximum { get; set; }

Property Value

string?

Remarks

Read as is. declares the bound as a value of the underlying type, which the compiler checks. Setting both is VO0029. This option is reported as VO0028 and will be removed in the next major version.

MinLength

Gets or sets the minimum accepted length. A negative value means unconstrained.

public int MinLength { get; set; }

Property Value

int

Remarks

Only meaningful for . Also emitted as the minLength OpenAPI keyword.

Minimum

Gets or sets the inclusive lower bound, written as text in the one form of the underlying type.

[Obsolete("Implement IValueObjectMinimum<T> with a static Minimum property of the underlying type instead. A bound written as text is read under one grammar per type the compiler cannot check, and will be removed in the next major version.", DiagnosticId = "VO0028")]
public string? Minimum { get; set; }

Property Value

string?

Remarks

Expressed as text so that , or bounds keep full precision; attribute arguments cannot carry those types. Each type reads one form, with no white space around it and nothing taken from the culture or the time zone of the build machine: digits, with - in front of a negative integer; a with an optional fraction after .; a or a with an optional exponent as well, finite, and zero only when written as zero; one character; yyyy-MM-dd; HH:mm, HH:mm:ss or HH:mm:ss.fffffff; a as a date, or a date and a time after T, without an offset; a as a date and a time after T, always followed by Z, +HH:mm or -HH:mm; and a as [-][d.]hh:mm:ss[.fffffff].

Only meaningful for numbers, characters, dates, times and durations: a , a or a takes no bound. Parsed at compile time, and reported as a diagnostic when written in any other form, outside the type, or on a type that takes none. Also emitted as the minimum OpenAPI keyword.

declares the bound as a value of the underlying type, which the compiler checks. Setting both is VO0029. This option is reported as VO0028 and will be removed in the next major version.

Pattern

Gets or sets a regular expression the normalized value must match. Deprecated: implement instead.

[Obsolete("Implement IValueObjectPatternValidator with a [GeneratedRegex] partial property instead. Pattern compiles its regular expression at run time, which native AOT interprets, and will be removed in the next major version.", DiagnosticId = "VO0021")]
[StringSyntax("Regex")]
public string? Pattern { get; set; }

Property Value

string?

Remarks

Compiled once into a static Regex with RegexOptions.Compiled: one source generator cannot see another's output, so [GeneratedRegex] is not reachable from emitted code. Native AOT cannot compile a regular expression at run time and interprets it, about twice as slowly. Also emitted as the pattern keyword of the OpenAPI schema.

takes a [GeneratedRegex] the author writes, which the regex generator compiles. Setting both is VO0022. This option is reported as VO0021 and will be removed in the next major version.

SchemaFormat

Gets or sets the value of the OpenAPI format keyword for the generated schema.

public string? SchemaFormat { get; set; }

Property Value

string?

Remarks

Defaults to the natural format of the underlying type, such as uuid, date or int64.

ValueSet

Gets or sets whether the type accepts any valid value or only the declared ones.

public ValueSetKind ValueSet { get; set; }

Property Value

ValueSetKind