Table of Contents

Class PropertyBuilder

Namespace
Microsoft.EntityFrameworkCore.Metadata.Builders
Assembly
Microsoft.EntityFrameworkCore.dll

Provides a simple API for configuring a IMutableProperty.

public class PropertyBuilder : IInfrastructure<IConventionPropertyBuilder>
Inheritance
PropertyBuilder
Implements
Derived
Inherited Members
Extension Methods

Remarks

Instances of this class are returned from methods when using the ModelBuilder API and it is not designed to be directly constructed in your application code.

See Modeling entity types and relationships for more information and examples.

Constructors

PropertyBuilder(IMutableProperty)

This is an internal API that supports the Entity Framework Core infrastructure and not subject to the same compatibility standards as public APIs. It may be changed or removed without notice in any release. You should only use it directly in your code with extreme caution and knowing that doing so can result in application failures when updating to a new Entity Framework Core release.

[EntityFrameworkInternal]
public PropertyBuilder(IMutableProperty property)

Parameters

property IMutableProperty

Properties

Metadata

The property being configured.

public virtual IMutableProperty Metadata { get; }

Property Value

IMutableProperty

Methods

HasAnnotation(string, object?)

Adds or updates an annotation on the property. If an annotation with the key specified in annotation already exists its value will be updated.

public virtual PropertyBuilder HasAnnotation(string annotation, object? value)

Parameters

annotation string

The key of the annotation to be added or updated.

value object

The value to be stored in the annotation.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasConversion(ValueConverter?)

Configures the property so that the property value is converted to and from the database using the given ValueConverter.

public virtual PropertyBuilder HasConversion(ValueConverter? converter)

Parameters

converter ValueConverter

The converter to use.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasConversion(ValueConverter?, ValueComparer?)

Configures the property so that the property value is converted to and from the database using the given ValueConverter.

public virtual PropertyBuilder HasConversion(ValueConverter? converter, ValueComparer? valueComparer)

Parameters

converter ValueConverter

The converter to use.

valueComparer ValueComparer

The comparer to use for values before conversion.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasConversion(ValueConverter?, ValueComparer?, ValueComparer?)

Configures the property so that the property value is converted to and from the database using the given ValueConverter.

public virtual PropertyBuilder HasConversion(ValueConverter? converter, ValueComparer? valueComparer, ValueComparer? providerComparer)

Parameters

converter ValueConverter

The converter to use.

valueComparer ValueComparer

The comparer to use for values before conversion.

providerComparer ValueComparer

The comparer to use for the provider values.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasConversion(Type?)

Configures the property so that the property value is converted before writing to the database and converted back when reading from the database.

public virtual PropertyBuilder HasConversion(Type? conversionType)

Parameters

conversionType Type

The type to convert to and from or a type that inherits from ValueConverter.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasConversion(Type, ValueComparer?)

Configures the property so that the property value is converted before writing to the database and converted back when reading from the database.

public virtual PropertyBuilder HasConversion(Type conversionType, ValueComparer? valueComparer)

Parameters

conversionType Type

The type to convert to and from or a type that inherits from ValueConverter.

valueComparer ValueComparer

The comparer to use for values before conversion.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasConversion(Type, ValueComparer?, ValueComparer?)

Configures the property so that the property value is converted before writing to the database and converted back when reading from the database.

public virtual PropertyBuilder HasConversion(Type conversionType, ValueComparer? valueComparer, ValueComparer? providerComparer)

Parameters

conversionType Type

The type to convert to and from or a type that inherits from ValueConverter.

valueComparer ValueComparer

The comparer to use for values before conversion.

providerComparer ValueComparer

The comparer to use for the provider values.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasConversion(Type, Type?)

Configures the property so that the property value is converted before writing to the database and converted back when reading from the database.

public virtual PropertyBuilder HasConversion(Type conversionType, Type? comparerType)

Parameters

conversionType Type

The type to convert to and from or a type that inherits from ValueConverter.

comparerType Type

A type that inherits from ValueComparer.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasConversion(Type, Type?, Type?)

Configures the property so that the property value is converted before writing to the database and converted back when reading from the database.

public virtual PropertyBuilder HasConversion(Type conversionType, Type? comparerType, Type? providerComparerType)

Parameters

conversionType Type

The type to convert to and from or a type that inherits from ValueConverter.

comparerType Type

A type that inherits from ValueComparer.

providerComparerType Type

A type that inherits from ValueComparer to use for the provider values.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasConversion<TConversion>()

Configures the property so that the property value is converted before writing to the database and converted back when reading from the database.

public virtual PropertyBuilder HasConversion<TConversion>()

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Type Parameters

TConversion

The type to convert to and from or a type that inherits from ValueConverter.

HasConversion<TConversion>(ValueComparer?)

Configures the property so that the property value is converted before writing to the database and converted back when reading from the database.

public virtual PropertyBuilder HasConversion<TConversion>(ValueComparer? valueComparer)

Parameters

valueComparer ValueComparer

The comparer to use for values before conversion.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Type Parameters

TConversion

The type to convert to and from or a type that inherits from ValueConverter.

HasConversion<TConversion>(ValueComparer?, ValueComparer?)

Configures the property so that the property value is converted before writing to the database and converted back when reading from the database.

public virtual PropertyBuilder HasConversion<TConversion>(ValueComparer? valueComparer, ValueComparer? providerComparer)

Parameters

valueComparer ValueComparer

The comparer to use for values before conversion.

providerComparer ValueComparer

The comparer to use for the provider values.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Type Parameters

TConversion

The type to convert to and from or a type that inherits from ValueConverter.

HasConversion<TConversion, TComparer>()

Configures the property so that the property value is converted before writing to the database and converted back when reading from the database.

public virtual PropertyBuilder HasConversion<TConversion, TComparer>() where TComparer : ValueComparer

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Type Parameters

TConversion

The type to convert to and from or a type that inherits from ValueConverter.

TComparer

A type that inherits from ValueComparer.

HasConversion<TConversion, TComparer, TProviderComparer>()

Configures the property so that the property value is converted before writing to the database and converted back when reading from the database.

public virtual PropertyBuilder HasConversion<TConversion, TComparer, TProviderComparer>() where TComparer : ValueComparer where TProviderComparer : ValueComparer

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Type Parameters

TConversion

The type to convert to and from or a type that inherits from ValueConverter.

TComparer

A type that inherits from ValueComparer.

TProviderComparer

A type that inherits from ValueComparer to use for the provider values.

HasField(string)

Sets the backing field to use for this property.

public virtual PropertyBuilder HasField(string fieldName)

Parameters

fieldName string

The field name.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Remarks

Backing fields are normally found by convention. This method is useful for setting backing fields explicitly in cases where the correct field is not found by convention.

By default, the backing field, if one is found or has been specified, is used when new objects are constructed, typically when entities are queried from the database. Properties are used for all other accesses. This can be changed by calling UsePropertyAccessMode(PropertyAccessMode).

See Backing fields for more information and examples.

HasMaxLength(int)

Configures the maximum length of data that can be stored in this property. Maximum length can only be set on array properties (including string properties).

public virtual PropertyBuilder HasMaxLength(int maxLength)

Parameters

maxLength int

The maximum length of data allowed in the property. A value of -1 indicates that the property has no maximum length.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasPrecision(int)

Configures the precision of the property.

public virtual PropertyBuilder HasPrecision(int precision)

Parameters

precision int

The precision of the property.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasPrecision(int, int)

Configures the precision and scale of the property.

public virtual PropertyBuilder HasPrecision(int precision, int scale)

Parameters

precision int

The precision of the property.

scale int

The scale of the property.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

HasSentinel(object?)

Configures the value that will be used to determine if the property has been set or not. If the property is set to the sentinel value, then it is considered not set. By default, the sentinel value is the CLR default value for the type of the property.

public virtual PropertyBuilder HasSentinel(object? sentinel)

Parameters

sentinel object

The sentinel value.

Returns

PropertyBuilder

The same builder instance if the configuration was applied, null otherwise.

HasValueGenerator(Func<IProperty, ITypeBase, ValueGenerator>)

Configures a factory for creating a ValueGenerator to use to generate values for this property.

public virtual PropertyBuilder HasValueGenerator(Func<IProperty, ITypeBase, ValueGenerator> factory)

Parameters

factory Func<IProperty, ITypeBase, ValueGenerator>

A delegate that will be used to create value generator instances.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Remarks

Values are generated when the entity is added to the context using, for example, Add<TEntity>(TEntity). Values are generated only when the property is assigned the CLR default value (null for string, 0 for int, Guid.Empty for Guid, etc.).

This factory will be invoked once to create a single instance of the value generator, and this will be used to generate values for this property in all instances of the entity type.

This method is intended for use with custom value generation. Value generation for common cases is usually handled automatically by the database provider.

HasValueGenerator(Type?)

Configures the ValueGenerator that will generate values for this property.

public virtual PropertyBuilder HasValueGenerator(Type? valueGeneratorType)

Parameters

valueGeneratorType Type

A type that inherits from ValueGenerator.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Remarks

Values are generated when the entity is added to the context using, for example, Add<TEntity>(TEntity). Values are generated only when the property is assigned the CLR default value (null for string, 0 for int, Guid.Empty for Guid, etc.).

A single instance of this type will be created and used to generate values for this property in all instances of the entity type. The type must be instantiable and have a parameterless constructor.

This method is intended for use with custom value generation. Value generation for common cases is usually handled automatically by the database provider.

Setting null does not disable value generation for this property, it just clears any generator explicitly configured for this property. The database provider may still have a value generator for the property type.

HasValueGeneratorFactory(Type?)

Configures the ValueGeneratorFactory for creating a ValueGenerator to use to generate values for this property.

public virtual PropertyBuilder HasValueGeneratorFactory(Type? valueGeneratorFactoryType)

Parameters

valueGeneratorFactoryType Type

A type that inherits from ValueGeneratorFactory.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Remarks

Values are generated when the entity is added to the context using, for example, Add<TEntity>(TEntity). Values are generated only when the property is assigned the CLR default value (null for string, 0 for int, Guid.Empty for Guid, etc.).

A single instance of this type will be created and used to generate values for this property in all instances of the entity type. The type must be instantiable and have a parameterless constructor.

This method is intended for use with custom value generation. Value generation for common cases is usually handled automatically by the database provider.

Setting null does not disable value generation for this property, it just clears any generator explicitly configured for this property. The database provider may still have a value generator for the property type.

HasValueGeneratorFactory<TFactory>()

Configures the ValueGeneratorFactory for creating a ValueGenerator to use to generate values for this property.

public virtual PropertyBuilder HasValueGeneratorFactory<TFactory>() where TFactory : ValueGeneratorFactory

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Type Parameters

TFactory

A type that inherits from ValueGeneratorFactory.

Remarks

Values are generated when the entity is added to the context using, for example, Add<TEntity>(TEntity). Values are generated only when the property is assigned the CLR default value (null for string, 0 for int, Guid.Empty for Guid, etc.).

A single instance of this type will be created and used to generate values for this property in all instances of the entity type. The type must be instantiable and have a parameterless constructor.

This method is intended for use with custom value generation. Value generation for common cases is usually handled automatically by the database provider.

Setting null does not disable value generation for this property, it just clears any generator explicitly configured for this property. The database provider may still have a value generator for the property type.

HasValueGenerator<TGenerator>()

Configures the ValueGenerator that will generate values for this property.

public virtual PropertyBuilder HasValueGenerator<TGenerator>() where TGenerator : ValueGenerator

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Type Parameters

TGenerator

A type that inherits from ValueGenerator.

Remarks

Values are generated when the entity is added to the context using, for example, Add<TEntity>(TEntity). Values are generated only when the property is assigned the CLR default value (null for string, 0 for int, Guid.Empty for Guid, etc.).

A single instance of this type will be created and used to generate values for this property in all instances of the entity type. The type must be instantiable and have a parameterless constructor.

This method is intended for use with custom value generation. Value generation for common cases is usually handled automatically by the database provider.

IsConcurrencyToken(bool)

Configures whether this property should be used as a concurrency token. When a property is configured as a concurrency token the value in the database will be checked when an instance of this entity type is updated or deleted during SaveChanges() to ensure it has not changed since the instance was retrieved from the database. If it has changed, an exception will be thrown and the changes will not be applied to the database.

public virtual PropertyBuilder IsConcurrencyToken(bool concurrencyToken = true)

Parameters

concurrencyToken bool

A value indicating whether this property is a concurrency token.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

IsRequired(bool)

Configures whether this property must have a value assigned or null is a valid value. A property can only be configured as non-required if it is based on a CLR type that can be assigned null.

public virtual PropertyBuilder IsRequired(bool required = true)

Parameters

required bool

A value indicating whether the property is required.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

IsRowVersion()

Configures the property as ValueGeneratedOnAddOrUpdate() and IsConcurrencyToken(bool).

public virtual PropertyBuilder IsRowVersion()

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Remarks

Database providers can choose to interpret this in different way, but it is commonly used to indicate some form of automatic row-versioning as used for optimistic concurrency detection.

IsUnicode(bool)

Configures whether the property as capable of persisting unicode characters. Can only be set on string properties.

public virtual PropertyBuilder IsUnicode(bool unicode = true)

Parameters

unicode bool

A value indicating whether the property can contain unicode characters.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

UsePropertyAccessMode(PropertyAccessMode)

Sets the PropertyAccessMode to use for this property.

public virtual PropertyBuilder UsePropertyAccessMode(PropertyAccessMode propertyAccessMode)

Parameters

propertyAccessMode PropertyAccessMode

The PropertyAccessMode to use for this property.

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Remarks

By default, the backing field, if one is found by convention or has been specified, is used when new objects are constructed, typically when entities are queried from the database. Properties are used for all other accesses. Calling this method will change that behavior for this property as described in the PropertyAccessMode enum.

Calling this method overrides for this property any access mode that was set on the entity type or model.

ValueGeneratedNever()

Configures a property to never have a value generated by the database when an instance of this entity type is saved.

public virtual PropertyBuilder ValueGeneratedNever()

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

Remarks

Note that values may still be generated by a client-side value generator, if one is set explicitly or by a convention.

ValueGeneratedOnAdd()

Configures a property to have a value generated only when saving a new entity, unless a non-null, non-temporary value has been set, in which case the set value will be saved instead. The value may be generated by a client-side value generator or may be generated by the database as part of saving the entity.

public virtual PropertyBuilder ValueGeneratedOnAdd()

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

ValueGeneratedOnAddOrUpdate()

Configures a property to have a value generated when saving a new or existing entity.

public virtual PropertyBuilder ValueGeneratedOnAddOrUpdate()

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

ValueGeneratedOnUpdate()

Configures a property to have a value generated when saving an existing entity.

public virtual PropertyBuilder ValueGeneratedOnUpdate()

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.

ValueGeneratedOnUpdateSometimes()

Configures a property to have a value generated under certain conditions when saving an existing entity.

public virtual PropertyBuilder ValueGeneratedOnUpdateSometimes()

Returns

PropertyBuilder

The same builder instance so that multiple configuration calls can be chained.