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. Its known values are static members it declares, marked .

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. , which states how the text is stored rather than what the type accepts, is read by the Entity Framework Core conventions and the Dapper handler alone.

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. The same holds in the code another source generator writes, such as a Riok.Mapperly mapping, where they are VO0032 rather than VO0010.

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

Was an example value surfaced in the OpenAPI schema, written as text. Removed: implement instead.

[Obsolete("Implement IValueObjectExample<TSelf> with a static Example property of the value object's type instead. Example is no longer read, and any minor version may remove it before 1.0.0.", true, DiagnosticId = "VO0035")]
public string? Example { get; set; }

Property Value

string?

Remarks

The text was parsed at compile time and again at run time. Setting it is VO0035, a compile error, and nothing reads it: declares the example as an instance of the value object. Any minor version may remove it before 1.0.0.

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

Was the inclusive upper bound, written as text. Removed: implement instead.

[Obsolete("Implement IValueObjectMaximum<T> with a static Maximum property of the underlying type instead. Maximum is no longer read, and any minor version may remove it before 1.0.0.", true, DiagnosticId = "VO0028")]
public string? Maximum { get; set; }

Property Value

string?

Remarks

Setting it is VO0028, a compile error, and nothing reads it, as for . Any minor version may remove it before 1.0.0.

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

Was the inclusive lower bound, written as text. Removed: implement instead.

[Obsolete("Implement IValueObjectMinimum<T> with a static Minimum property of the underlying type instead. Minimum is no longer read, and any minor version may remove it before 1.0.0.", true, DiagnosticId = "VO0028")]
public string? Minimum { get; set; }

Property Value

string?

Remarks

The text was read under a grammar of one form per underlying type, which the compiler could not check. Setting it is VO0028, a compile error, and nothing reads it: declares the bound as a value of the underlying type. Any minor version may remove it before 1.0.0.

Pattern

Was a regular expression the normalized value had to match. Removed: implement instead.

[Obsolete("Implement IValueObjectPatternValidator with a [GeneratedRegex] partial property instead. Pattern is no longer read, and any minor version may remove it before 1.0.0.", true, DiagnosticId = "VO0021")]
[StringSyntax("Regex")]
public string? Pattern { get; set; }

Property Value

string?

Remarks

The option compiled its regular expression at run time, which native AOT interprets. Setting it is VO0021, a compile error, and nothing reads it: takes a [GeneratedRegex] the author writes, which the regex generator compiles. Any minor version may remove it before 1.0.0.

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, date-time for a , or int64. Three types have none, and are documented with the pattern of the form they are written in instead. A is written in the invariant constant form [-][d.]hh:mm:ss[.fffffff], not the ISO 8601 form the duration format names. A and a are written without the offset RFC 3339 requires of the time and date-time formats: a time of day never has one, and a of is written without one.

Set it to date-time on a value object over whose normalizer guarantees a kind, such as , which is written with its offset.

Unicode

Gets or sets whether the text is stored as Unicode text; false stores and sends it as non-Unicode text, varchar on SQL Server.

public bool Unicode { get; set; }

Property Value

bool

Remarks

Only meaningful for (VO0008 otherwise). Defaults to true. Read by the Entity Framework Core conventions, which map the value object to non-Unicode text, and by the Dapper handler, which declares its parameters non-Unicode; nothing else stores text that way. It states how the text is stored, not what the type accepts: SQL Server replaces a character the column's code page lacks with a look-alike or ?, silently, so declare it for ASCII text and hold the rules to ASCII, as VO0047 asks. Declared on a type already mapped, it alters its columns at the next migration.

ValueSet

Gets or sets whether the type accepts any valid value or only the members it marks .

public ValueSetKind ValueSet { get; set; }

Property Value

ValueSetKind