Entity-Property-Config.md

'Property' object (entity-driven)

The Property object defines an Entity property and its charateristics.

Example

A YAML configuration example is as follows:

properties: [
  { name: Id, type: Guid, text: '{{Employee}} identifier', uniqueKey: true, dataName: EmployeeId, dataAutoGenerated: true },
  { name: FirstName, type: string },
  { name: LastName, type: string },
  { name: Gender, type: RefDataNamespace.Gender, dataName: GenderCode },
  { name: Birthday, type: DateTime, dateTimeTransform: DateOnly },
  { name: ETag, type: string },
  { name: ChangeLog, type: ChangeLog }
]

Property categories

The Property object supports a number of properties that control the generated code output. These properties are separated into a series of logical categories.

Category	Description
Key	Provides the key configuration.
Property	Provides additional Property configuration.
RefData	Provides the Reference Data configuration.
Serialization	Provides the Serialization configuration.
Manager	Provides the Manager-layer configuration.
Data	Provides the generic Data-layer configuration.
Database	Provides the specific Database (ADO.NET) configuration where Entity.AutoImplement or Operation.AutoImplement is Database.
EntityFramework	Provides the specific Entity Framework (EF) configuration where Entity.AutoImplement or Operation.AutoImplement is EntityFramework.
Cosmos	Provides the specific Cosmos DB configuration where Entity.AutoImplement or Operation.AutoImplement is Cosmos.
OData	Provides the specific OData configuration where Entity.AutoImplement or Operation.AutoImplement is OData.
HttpAgent	Provides the specific HTTP Agent configuration where Entity.AutoImplement or Operation.AutoImplement is HttpAgent.
Annotation	Provides additional property Annotation configuration.
WebApi	Provides the data Web API configuration.
gRPC	Provides the gRPC configuration.

The properties with a bold name are those that are more typically used (considered more important).

Key

Provides the key configuration.

Property	Description
name	The unique property name. [Mandatory]
text	The overriding text for use in comments. † By default the Text will be the Name reformatted as sentence casing. Depending on whether the Type is bool, will appear in one of the two generated sentences. Where not bool it will be: Gets or sets a value indicating whether {text}.'. Otherwise, it will be: Gets or sets the {text}.'. To create a <see cref="XXX"/> within use moustache shorthand (e.g. {{Xxx}}).
modelText	The overriding model text for use in comments. † By default the ModelText will be the Name reformatted as sentence casing. Depending on whether the Type is bool, will appear in one of the two generated sentences. Where not bool it will be: Gets or sets a value indicating whether {text}.'. Otherwise, it will be: Gets or sets the {text}.'. To create a <see cref="XXX"/> within use moustache shorthand (e.g. {{Xxx}}).
type	The .NET Type. † Defaults to string. To reference a Reference Data Type always prefix with RefDataNamespace (e.g. RefDataNamespace.Gender) or shortcut ^ (e.g. ^Gender). This will ensure that the appropriate Reference Data using statement is used. Shortcut: Where the Type starts with (prefix) RefDataNamespace. or ^, and the correspondong RefDataType attribute is not specified it will automatically default the RefDataType to string.
nullable	Indicates whether the .NET Type should be declared as nullable; e.g. string?. Will be inferred where the Type is denoted as nullable; i.e. suffixed by a ?.
inherited	Indicates whether the property is inherited and therefore should not be output within the generated Entity class.
privateName	The overriding private name. † Overrides the Name to be used for private fields. By default reformatted from Name; e.g. FirstName as _firstName.
argumentName	The overriding argument name. † Overrides the Name to be used for argument parameters. By default reformatted from Name; e.g. FirstName as firstName.

Property

Provides additional Property configuration.

Property	Description
uniqueKey	Indicates whether the property is considered part of the unique (primary) key. † This is also used to simplify the parameter specification for an Entity Operation by inferrence.
isEntity	Indicates that the property Type is another generated entity / collection and therefore specific capabilities can be assumed (e.g. CopyFrom and Clone). † Will be inferred (default to true) where the Type is ChangeLog or the Type is found as another Entity within the code-generation configuration file.
immutable	Indicates that the value is immutable and therefore cannot be changed once set.
dateTimeTransform	The DateTime transformation to be performed on Set and CleanUp. Valid options are: UseDefault, None, DateOnly, DateTimeLocal, DateTimeUtc, DateTimeUnspecified. † Defaults to UseDefault. This is only applied where the Type is DateTime.
stringTrim	The string trimming of white space characters to be performed on Set and CleanUp. Valid options are: UseDefault, None, Start, End, Both. † Defaults to UseDefault. This is only applied where the Type is string.
stringTransform	The string transformation to be performed on Set and CleanUp. Valid options are: UseDefault, None, NullToEmpty, EmptyToNull. † Defaults to UseDefault. This is only applied where the Type is string.
autoCreate	Indicates whether an instance of the Type is to be automatically created/instantiated when the property is first accessed (i.e. lazy instantiation).
default	The C# code to default the value. † Where the Type is string then the specified default value will need to be delimited. Any valid value assignment C# code can be used.
partitionKey	Indicates whether the property is considered part of the Partition Key. † This will implement IPartitionKey for the generated entity.
secondaryPropertyChanged	The names of the secondary property(s), comma delimited, that are to be notified on a property change.
bubblePropertyChanges	Indicates whether the value should bubble up property changes versus only recording within the sub-entity itself. † Note that the IsEntity property is also required to enable.
excludeCleanup	Indicates that CleanUp is not to be performed for the property within the Entity.CleanUp method.
internalOnly	Indicates whether the property is for internal use only; declared in Business entities only. † This is only applicable where the Entity.EntityScope is Autonomous. In this instance the Property will be excluded from the Common entity declaration.

RefData

Provides the Reference Data configuration.

Property	Description
refDataType	The underlying Reference Data Type that is also used as the Reference Data serialization identifier (SID). Valid options are: string, int, Guid. † Defaults to string (being the ReferenceDataBase.Code) where not specified and the corresponding Type starts with (prefix) RefDataNamespace. or ^. Note: an Id of type string is currently not supported; the use of the Code is the recommended approach.
refDataList	Indicates that the Reference Data property is to be a serializable list (ReferenceDataSidList). † This is required to enable a list of Reference Data values (as per RefDataType) to be passed as an argument for example.
refDataText	Indicates whether a corresponding Text property is added when generating a Reference Data property, overriding the Entity.RefDataText selection. † This is used where serializing within the Web API Controller and the ExecutionContext.IsRefDataTextSerializationEnabled is set to true (which is automatically set where the url contains $text=true).
refDataMapping	Indicates whether the property should use the underlying Reference Data mapping capabilities. † Mapped properties are a special Reference Data property type that ensure value uniqueness; this allows the likes of additional to/from mappings to occur between systems where applicable.

Serialization

Provides the Serialization configuration.

Property	Description
jsonName	The JSON property name. † Defaults to ArgumentName where not specified (i.e. camelCase); however, where the property is ETag it will default to the Config.ETagJsonName.
jsonDataModelName	The JSON property name for the corresponding data model (see Entity.DataModel). † Defaults to JsonName where not specified.
serializationIgnore	Indicates whether the property is not to be serialized. † All properties are serialized by default.
serializationEmitDefault	Indicates whether to emit the default value when serializing.
dataModelJsonName	The override JSON property name where outputting as a data model. † Defaults to JsonName where not specified.

Manager

Provides the Manager-layer configuration.

Property

Description

identifierGenerator

The Identifier Generator Type to generate the identifier on create via Dependency Injection. † Should be formatted as Type + ^ + Name; e.g. IGuidIdentifierGenerator^GuidIdGen. Where the Name portion is not specified it will be inferred. Where the Type matches an already inferred value it will be ignored. See Beef.Entities.IInt32IdentifierGenerator, Beef.Entities.IInt64IdentifierGenerator, Beef.Entities.IGuidIdentifierGenerator or Beef.Entities.IStringIdentifierGenerator for underlying implementation requirements.

Data

Provides the generic Data-layer configuration.

Property	Description
dataName	The data name where Entity.AutoImplement is selected. † Defaults to the property Name. Represents the column name for a Database, or the correspinding property name for the other options.
dataConverter	The data Converter class name where Entity.AutoImplement is selected. † A Converter is used to convert a data source value to/from a .NET Type where no standard data conversion can be applied. Where this value is suffixed by <T> or {T} this will automatically set DataConverterIsGeneric to true.
dataConverterIsGeneric	Indicates whether the data Converter is a generic class and will automatically use the corresponding property Type as the generic T.
dataMapperIgnore	Indicates whether the property should be ignored (excluded) from the Data-layer / data Mapper generated output. † All properties are included by default.
dataAutoGenerated	Indicates whether the UniqueKey property value is automatically generated by the data source on Create.
dataOperationTypes	The operations types (ExecutionContext.OperationType) selection to enable inclusion and exclusion of property mapping. Valid options are: Any, AnyExceptCreate, AnyExceptUpdate, AnyExceptGet, Get, Create, Update, Delete. † Defaults to Any.

Database

Provides the specific Database (ADO.NET) configuration where Entity.AutoImplement or Operation.AutoImplement is Database.

Property	Description
databaseMapper	The database property Mapper class name where Entity.AutoImplement is selected. † A Mapper is used to map a data source value to/from a .NET complex Type (i.e. class with one or more properties).
databaseIgnore	Indicates whether the property should be ignored (excluded) from the database Mapper generated output.
databaseDbType	The database DbType override (versus inferring from the corresponding .NET Type). † Overrides the inferred database type; i.e. can specify Date or DateTime2, for .NET Type System.DateTime.

EntityFramework

Provides the specific Entity Framework (EF) configuration where Entity.AutoImplement or Operation.AutoImplement is EntityFramework.

Property	Description
entityFrameworkMapper	The Entity Framework Mapper approach for the property. Valid options are: Map, Ignore, Skip. † Defaults to Map which indicates the property will be explicitly mapped. A value of Ignore will explicitly Ignore, whilst a value of Skip will skip code-generated mapping altogether.

Cosmos

Provides the specific Cosmos DB configuration where Entity.AutoImplement or Operation.AutoImplement is Cosmos.

Property	Description
cosmosMapper	The Cosmos Mapper approach for the property. Valid options are: Map, Ignore, Skip. † Defaults to Map which indicates the property will be explicitly mapped. A value of Ignore will explicitly Ignore, whilst a value of Skip will skip code-generated mapping altogether.

OData

Provides the specific OData configuration where Entity.AutoImplement or Operation.AutoImplement is OData.

Property	Description
odataMapper	The OData Mapper approach for the property. Valid options are: Map, Ignore, Skip. † Defaults to Map which indicates the property will be explicitly mapped. A value of Ignore will explicitly Ignore, whilst a value of Skip will skip code-generated mapping altogether.

HttpAgent

Provides the specific HTTP Agent configuration where Entity.AutoImplement or Operation.AutoImplement is HttpAgent.

Property	Description
httpAgentMapper	The HttpAgent Mapper approach for the property. Valid options are: Map, Ignore, Skip. † Defaults to Map which indicates the property will be explicitly mapped. A value of Ignore will explicitly Ignore, whilst a value of Skip will skip code-generated mapping altogether.

Annotation

Provides additional property Annotation configuration.

Property	Description
displayName	The display name used in the likes of error messages for the property. † Defaults to the Name as sentence case.
annotation1	The property annotation (e.g. attribute) declaration code.
annotation2	The property annotation (e.g. attribute) declaration code.
annotation3	The property annotation (e.g. attribute) declaration code.

WebApi

Provides the data Web API configuration.

Property	Description
webApiQueryStringConverter	The IPropertyMapperConverter to perform Type to string conversion for writing to and parsing from the query string.

gRPC

Provides the gRPC configuration.

Property	Description
grpcFieldNo	The unique (immutable) field number required to enable gRPC support.
grpcType	The underlying gRPC data type; will be inferred where not specified.