Class PrimitiveCollectionBuilder

Namespace

Microsoft.EntityFrameworkCore.Metadata.Builders

Assembly

Microsoft.EntityFrameworkCore.dll

Provides a simple API for configuring a IMutableProperty.

public class PrimitiveCollectionBuilder : IInfrastructure<IConventionPropertyBuilder>

Inheritance

object

PrimitiveCollectionBuilder

Implements

IInfrastructure<IConventionPropertyBuilder>

Derived

PrimitiveCollectionBuilder<TProperty>

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Extension Methods

AccessorExtensions.GetInfrastructure<T>(IInfrastructure<T>)

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

PrimitiveCollectionBuilder(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 PrimitiveCollectionBuilder(IMutableProperty property)

Parameters

property IMutableProperty

Properties

Metadata

The property being configured.

public virtual IMutableProperty Metadata { get; }

Property Value

IMutableProperty

Methods

ElementType()

Configures the elements of this collection.

public virtual ElementTypeBuilder ElementType()

Returns

ElementTypeBuilder

A builder to configure the collection element type.

ElementType(Action<ElementTypeBuilder>)

Configures the elements of this collection.

public virtual PrimitiveCollectionBuilder ElementType(Action<ElementTypeBuilder> builderAction)

Parameters

builderAction Action<ElementTypeBuilder>

An action that performs configuration of the collection element type.

Returns

PrimitiveCollectionBuilder

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

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 PrimitiveCollectionBuilder 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

PrimitiveCollectionBuilder

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

HasField(string)

Sets the backing field to use for this property.

public virtual PrimitiveCollectionBuilder HasField(string fieldName)

Parameters

fieldName string

The field name.

Returns

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder 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

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder HasSentinel(object? sentinel)

Parameters

sentinel object

The sentinel value.

Returns

PrimitiveCollectionBuilder

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

HasValueGenerator(Type?)

Configures the ValueGenerator that will generate values for this property.

public virtual PrimitiveCollectionBuilder HasValueGenerator(Type? valueGeneratorType)

Parameters

valueGeneratorType Type

A type that inherits from ValueGenerator.

Returns

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder HasValueGeneratorFactory(Type? valueGeneratorFactoryType)

Parameters

valueGeneratorFactoryType Type

A type that inherits from ValueGeneratorFactory.

Returns

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder HasValueGeneratorFactory<TFactory>() where TFactory : ValueGeneratorFactory

Returns

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder HasValueGenerator<TGenerator>() where TGenerator : ValueGenerator

Returns

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder IsConcurrencyToken(bool concurrencyToken = true)

Parameters

concurrencyToken bool

A value indicating whether this property is a concurrency token.

Returns

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder IsRequired(bool required = true)

Parameters

required bool

A value indicating whether the property is required.

Returns

PrimitiveCollectionBuilder

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

IsUnicode(bool)

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

public virtual PrimitiveCollectionBuilder IsUnicode(bool unicode = true)

Parameters

unicode bool

A value indicating whether the property can contain unicode characters.

Returns

PrimitiveCollectionBuilder

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

UsePropertyAccessMode(PropertyAccessMode)

Sets the PropertyAccessMode to use for this property.

public virtual PrimitiveCollectionBuilder UsePropertyAccessMode(PropertyAccessMode propertyAccessMode)

Parameters

propertyAccessMode PropertyAccessMode

The PropertyAccessMode to use for this property.

Returns

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder ValueGeneratedNever()

Returns

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder ValueGeneratedOnAdd()

Returns

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder ValueGeneratedOnAddOrUpdate()

Returns

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder ValueGeneratedOnUpdate()

Returns

PrimitiveCollectionBuilder

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 PrimitiveCollectionBuilder ValueGeneratedOnUpdateSometimes()

Returns

PrimitiveCollectionBuilder

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