Class KnownValueAttribute

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

Marks a static member of a value object as one of its known values.

[AttributeUsage(AttributeTargets.Struct|AttributeTargets.Property|AttributeTargets.Field, AllowMultiple = true, Inherited = false)]
public sealed class KnownValueAttribute : Attribute

Inheritance

object ← Attribute ← KnownValueAttribute

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 member is the author's own: a static readonly field, or a static get-only auto-property, of the value object's type, initialized through Known, a factory the generator writes on every value object. [KnownValue] public static readonly CountryCode France = Known("FR"); adds the value to CountryCode.KnownValues and surfaces it in the OpenAPI schema. Combined with the declared values also become the validation rule of the type. The compiler checks the name of the member and the type of its value, which any expression of the underlying type can give: Known(new DateOnly(1970, 1, 1)).

Known normalizes the value and applies every rule of the type but membership, which the value satisfies by declaration. A value the rules refuse throws as the type initializes: it is reported at compile time when the argument of Known is a constant the generator can evaluate, and would otherwise stop the application before it starts. Known may be called nowhere else (VO0037), and a member that is not static, can be written, is of another type or is not initialized through Known is VO0036.

The schema keeps the name of the member and the description beside the value (), and the OpenAPI integration publishes them beside the enum of a closed set, so that a client generated from the document names the member of its enumeration France rather than FR. The name is therefore part of that client's contract: renaming a known value renames its member in every client generated afterwards.

Constructors

KnownValueAttribute()

Initializes a new instance of the class, for the member it is applied to.

public KnownValueAttribute()

KnownValueAttribute(string, object)

Declared a known value on the type, by name and value. Removed: declare the member instead.

[Obsolete("Declare the known value as a member of the value object, [KnownValue] public static readonly TSelf Name = Known(value), which a code fix writes. Any minor version may remove this constructor before 1.0.0.", true, DiagnosticId = "VO0034")]
public KnownValueAttribute(string name, object value)

Parameters

name string

The name the generated property took.

value object

The underlying value, written as text for a type an attribute argument cannot carry.

Remarks

The name was an identifier the generator created and the value a constant or text it read under a grammar of its own. A member the author declares is checked by the compiler instead. [KnownValue("France", "FR")] on the type becomes [KnownValue] public static readonly CountryCode France = Known("FR"); in it, which a code fix writes. Any minor version may remove this constructor before 1.0.0.

Properties

Description

Gets or sets the description of the known value.

public string? Description { get; set; }

Property Value

string?

Remarks

Kept in , unless it is blank, and published with the value in the OpenAPI document, where client generators turn it into the documentation of the member. Without it, the <summary> of the member describes the value, as the summary of a value object describes it.