Class ComplexPropertyBuilder

Namespace

Microsoft.EntityFrameworkCore.Metadata.Builders

Assembly

Microsoft.EntityFrameworkCore.dll

Provides a simple API for configuring an IMutableComplexProperty.

public class ComplexPropertyBuilder : IInfrastructure<IConventionComplexPropertyBuilder>, IInfrastructure<IConventionComplexTypeBuilder>

Inheritance

object

ComplexPropertyBuilder

Implements

IInfrastructure<IConventionComplexPropertyBuilder>

IInfrastructure<IConventionComplexTypeBuilder>

Derived

ComplexPropertyBuilder<TComplex>

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

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.

Constructors

ComplexPropertyBuilder(IMutableComplexProperty)

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 ComplexPropertyBuilder(IMutableComplexProperty complexProperty)

Parameters

complexProperty IMutableComplexProperty

Properties

Metadata

The complex property being configured.

public virtual IMutableComplexProperty Metadata { get; }

Property Value

IMutableComplexProperty

PropertyBuilder

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]
protected virtual InternalComplexPropertyBuilder PropertyBuilder { get; }

Property Value

InternalComplexPropertyBuilder

TypeBuilder

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]
protected virtual InternalComplexTypeBuilder TypeBuilder { get; }

Property Value

InternalComplexTypeBuilder

Methods

ComplexProperty(string)

Returns an object that can be used to configure a complex property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexPropertyBuilder ComplexProperty(string propertyName)

Parameters

propertyName string

The name of the property to be configured.

Returns

ComplexPropertyBuilder

An object that can be used to configure the property.

Remarks

When adding a new property with this overload the property name must match the name of a CLR property or field on the complex type. This overload cannot be used to add a new shadow state complex property.

ComplexProperty(string, Action<ComplexPropertyBuilder>)

Configures a complex property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexPropertyBuilder ComplexProperty(string propertyName, Action<ComplexPropertyBuilder> buildAction)

Parameters

propertyName string

The name of the property to be configured.

buildAction Action<ComplexPropertyBuilder>

An action that performs configuration of the property.

Returns

ComplexPropertyBuilder

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

Remarks

When adding a new property with this overload the property name must match the name of a CLR property or field on the complex type. This overload cannot be used to add a new shadow state complex property.

ComplexProperty(Type, string)

Returns an object that can be used to configure a complex property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexPropertyBuilder ComplexProperty(Type propertyType, string propertyName)

Parameters

propertyType Type

The type of the property to be configured.

propertyName string

The name of the property to be configured.

Returns

ComplexPropertyBuilder

An object that can be used to configure the property.

Remarks

When adding a new complex property, if a property with the same name exists in the complex class then it will be added to the model. If no property exists in the complex class, then a new shadow state complex property will be added. A shadow state property is one that does not have a corresponding property in the complex class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the complex class.

ComplexProperty(Type, string, Action<ComplexPropertyBuilder>)

Configures a complex property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexPropertyBuilder ComplexProperty(Type propertyType, string propertyName, Action<ComplexPropertyBuilder> buildAction)

Parameters

propertyType Type

The type of the property to be configured.

propertyName string

The name of the property to be configured.

buildAction Action<ComplexPropertyBuilder>

An action that performs configuration of the property.

Returns

ComplexPropertyBuilder

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

Remarks

When adding a new complex property, if a property with the same name exists in the complex class then it will be added to the model. If no property exists in the complex class, then a new shadow state complex property will be added. A shadow state property is one that does not have a corresponding property in the complex class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the complex class.

ComplexProperty(Type, string, string)

Returns an object that can be used to configure a complex property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexPropertyBuilder ComplexProperty(Type propertyType, string propertyName, string complexTypeName)

Parameters

propertyType Type

The type of the property to be configured.

propertyName string

The name of the property to be configured.

complexTypeName string

The name of the complex type.

Returns

ComplexPropertyBuilder

An object that can be used to configure the property.

Remarks

When adding a new complex property, if a property with the same name exists in the complex class then it will be added to the model. If no property exists in the complex class, then a new shadow state complex property will be added. A shadow state property is one that does not have a corresponding property in the complex class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the complex class.

ComplexProperty(Type, string, string, Action<ComplexPropertyBuilder>)

Configures a complex property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexPropertyBuilder ComplexProperty(Type propertyType, string propertyName, string complexTypeName, Action<ComplexPropertyBuilder> buildAction)

Parameters

propertyType Type

The type of the property to be configured.

propertyName string

The name of the property to be configured.

complexTypeName string

The name of the complex type.

buildAction Action<ComplexPropertyBuilder>

An action that performs configuration of the property.

Returns

ComplexPropertyBuilder

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

Remarks

When adding a new complex property, if a property with the same name exists in the complex class then it will be added to the model. If no property exists in the complex class, then a new shadow state complex property will be added. A shadow state property is one that does not have a corresponding property in the complex class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the complex class.

ComplexProperty<TProperty>(string)

Returns an object that can be used to configure a complex property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexPropertyBuilder<TProperty> ComplexProperty<TProperty>(string propertyName)

Parameters

propertyName string

The name of the property to be configured.

Returns

ComplexPropertyBuilder<TProperty>

An object that can be used to configure the property.

Type Parameters

TProperty

The type of the property to be configured.

Remarks

When adding a new property, if a property with the same name exists in the complex class then it will be added to the model. If no property exists in the complex class, then a new shadow state complex property will be added. A shadow state property is one that does not have a corresponding property in the complex class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the complex class.

ComplexProperty<TProperty>(string, Action<ComplexPropertyBuilder<TProperty>>)

Configures a complex property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexPropertyBuilder ComplexProperty<TProperty>(string propertyName, Action<ComplexPropertyBuilder<TProperty>> buildAction)

Parameters

propertyName string

The name of the property to be configured.

buildAction Action<ComplexPropertyBuilder<TProperty>>

An action that performs configuration of the property.

Returns

ComplexPropertyBuilder

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

Type Parameters

TProperty

The type of the property to be configured.

Remarks

When adding a new property, if a property with the same name exists in the complex class then it will be added to the model. If no property exists in the complex class, then a new shadow state complex property will be added. A shadow state property is one that does not have a corresponding property in the complex class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the complex class.

ComplexProperty<TProperty>(string, string)

Returns an object that can be used to configure a complex property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexPropertyBuilder<TProperty> ComplexProperty<TProperty>(string propertyName, string complexTypeName)

Parameters

propertyName string

The name of the property to be configured.

complexTypeName string

The name of the complex type.

Returns

ComplexPropertyBuilder<TProperty>

An object that can be used to configure the property.

Type Parameters

TProperty

The type of the property to be configured.

Remarks

When adding a new property, if a property with the same name exists in the complex class then it will be added to the model. If no property exists in the complex class, then a new shadow state complex property will be added. A shadow state property is one that does not have a corresponding property in the complex class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the complex class.

ComplexProperty<TProperty>(string, string, Action<ComplexPropertyBuilder<TProperty>>)

Configures a complex property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexPropertyBuilder ComplexProperty<TProperty>(string propertyName, string complexTypeName, Action<ComplexPropertyBuilder<TProperty>> buildAction)

Parameters

propertyName string

The name of the property to be configured.

complexTypeName string

The name of the complex type.

buildAction Action<ComplexPropertyBuilder<TProperty>>

An action that performs configuration of the property.

Returns

ComplexPropertyBuilder

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

Type Parameters

TProperty

The type of the property to be configured.

Remarks

When adding a new property, if a property with the same name exists in the complex class then it will be added to the model. If no property exists in the complex class, then a new shadow state complex property will be added. A shadow state property is one that does not have a corresponding property in the complex class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the complex class.

HasChangeTrackingStrategy(ChangeTrackingStrategy)

Configures the ChangeTrackingStrategy to be used for this entity type. This strategy indicates how the context detects changes to properties for an instance of the entity type.

public virtual ComplexPropertyBuilder HasChangeTrackingStrategy(ChangeTrackingStrategy changeTrackingStrategy)

Parameters

changeTrackingStrategy ChangeTrackingStrategy

The change tracking strategy to be used.

Returns

ComplexPropertyBuilder

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 ComplexPropertyBuilder HasField(string fieldName)

Parameters

fieldName string

The field name.

Returns

ComplexPropertyBuilder

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.

HasPropertyAnnotation(string, object?)

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

public virtual ComplexPropertyBuilder HasPropertyAnnotation(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

ComplexPropertyBuilder

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

HasTypeAnnotation(string, object?)

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

public virtual ComplexPropertyBuilder HasTypeAnnotation(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

ComplexPropertyBuilder

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

Ignore(string)

Excludes the given property from the complex type. This method is typically used to remove properties and navigations from the complex type that were added by convention.

public virtual ComplexPropertyBuilder Ignore(string propertyName)

Parameters

propertyName string

The name of the property to be removed from the complex type.

Returns

ComplexPropertyBuilder

IndexerProperty(Type, string)

Returns an object that can be used to configure a property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexTypePropertyBuilder IndexerProperty(Type propertyType, string propertyName)

Parameters

propertyType Type

The type of the property to be configured.

propertyName string

The name of the property to be configured.

Returns

ComplexTypePropertyBuilder

An object that can be used to configure the property.

Remarks

Indexer properties are stored in the entity using an indexer supplying the provided property name.

IndexerProperty<TProperty>(string)

Returns an object that can be used to configure a property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexTypePropertyBuilder<TProperty> IndexerProperty<TProperty>(string propertyName)

Parameters

propertyName string

The name of the property to be configured.

Returns

ComplexTypePropertyBuilder<TProperty>

An object that can be used to configure the property.

Type Parameters

TProperty

The type of the property to be configured.

Remarks

Indexer properties are stored in the entity using an indexer supplying the provided property name.

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

Parameters

required bool

A value indicating whether the property is required.

Returns

ComplexPropertyBuilder

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

PrimitiveCollection(string)

Returns an object that can be used to configure a property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexTypePrimitiveCollectionBuilder PrimitiveCollection(string propertyName)

Parameters

propertyName string

The name of the property to be configured.

Returns

ComplexTypePrimitiveCollectionBuilder

An object that can be used to configure the property.

Remarks

When adding a new property with this overload the property name must match the name of a CLR property or field on the complex type. This overload cannot be used to add a new shadow state property.

PrimitiveCollection(Type, string)

Returns an object that can be used to configure a property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexTypePrimitiveCollectionBuilder PrimitiveCollection(Type propertyType, string propertyName)

Parameters

propertyType Type

The type of the property to be configured.

propertyName string

The name of the property to be configured.

Returns

ComplexTypePrimitiveCollectionBuilder

An object that can be used to configure the property.

Remarks

When adding a new property, if a property with the same name exists in the entity class then it will be added to the model. If no property exists in the entity class, then a new shadow state property will be added. A shadow state property is one that does not have a corresponding property in the entity class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the entity class.

PrimitiveCollection<TProperty>(string)

Returns an object that can be used to configure a property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexTypePrimitiveCollectionBuilder<TProperty> PrimitiveCollection<TProperty>(string propertyName)

Parameters

propertyName string

The name of the property to be configured.

Returns

ComplexTypePrimitiveCollectionBuilder<TProperty>

An object that can be used to configure the property.

Type Parameters

TProperty

The type of the property to be configured.

Remarks

When adding a new property, if a property with the same name exists in the entity class then it will be added to the model. If no property exists in the entity class, then a new shadow state property will be added. A shadow state property is one that does not have a corresponding property in the entity class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the entity class.

Property(string)

Returns an object that can be used to configure a property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexTypePropertyBuilder Property(string propertyName)

Parameters

propertyName string

The name of the property to be configured.

Returns

ComplexTypePropertyBuilder

An object that can be used to configure the property.

Remarks

When adding a new property with this overload the property name must match the name of a CLR property or field on the complex type. This overload cannot be used to add a new shadow state property.

Property(Type, string)

Returns an object that can be used to configure a property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexTypePropertyBuilder Property(Type propertyType, string propertyName)

Parameters

propertyType Type

The type of the property to be configured.

propertyName string

The name of the property to be configured.

Returns

ComplexTypePropertyBuilder

An object that can be used to configure the property.

Remarks

When adding a new property, if a property with the same name exists in the entity class then it will be added to the model. If no property exists in the entity class, then a new shadow state property will be added. A shadow state property is one that does not have a corresponding property in the entity class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the entity class.

Property<TProperty>(string)

Returns an object that can be used to configure a property of the complex type. If no property with the given name exists, then a new property will be added.

public virtual ComplexTypePropertyBuilder<TProperty> Property<TProperty>(string propertyName)

Parameters

propertyName string

The name of the property to be configured.

Returns

ComplexTypePropertyBuilder<TProperty>

An object that can be used to configure the property.

Type Parameters

TProperty

The type of the property to be configured.

Remarks

When adding a new property, if a property with the same name exists in the entity class then it will be added to the model. If no property exists in the entity class, then a new shadow state property will be added. A shadow state property is one that does not have a corresponding property in the entity class. The current value for the property is stored in the ChangeTracker rather than being stored in instances of the entity class.

UseDefaultPropertyAccessMode(PropertyAccessMode)

Sets the PropertyAccessMode to use for all properties of this complex type.

public virtual ComplexPropertyBuilder UseDefaultPropertyAccessMode(PropertyAccessMode propertyAccessMode)

Parameters

propertyAccessMode PropertyAccessMode

The PropertyAccessMode to use for properties of this complex type.

Returns

ComplexPropertyBuilder

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 all properties of this complex type as described in the PropertyAccessMode enum.

Calling this method overrides for all properties of this complex type any access mode that was set on the model.

UsePropertyAccessMode(PropertyAccessMode)

Sets the PropertyAccessMode to use for this property.

public virtual ComplexPropertyBuilder UsePropertyAccessMode(PropertyAccessMode propertyAccessMode)

Parameters

propertyAccessMode PropertyAccessMode

The PropertyAccessMode to use for this property.

Returns

ComplexPropertyBuilder

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.