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', primaryKey: 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.
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.
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}}). To have the text used as-is prefix with a + plus-sign character.
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}}). To have the text used as-is prefix with a + plus-sign character.
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
primaryKey	Indicates whether the property is considered part of the primary (unique) 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.
stringCasing	The string casing to be performed on Set and CleanUp. Valid options are: UseDefault, None, Lower, Upper, Title. † 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.
cacheKey	Indicates whether the property is considered part of the Cache Key. † This will implement ICacheKey for the generated entity.
internalOnly	Indicates whether the property is for internal use only; declared in Business entities only. † In this instance the Property will be excluded from the Common entity declaration and Business JSON serialization.

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. Valid options are: Optional, Always, Never. † 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).Optional indicates when ExecutionContext.IsRefDataTextSerializationEnabled is set to true then a value is output, Always indicates that the value is always output, and Never indicates that feature is turned off.
refDataTextName	The corresponding reference data Text property name; defaults to Name + 'Text'.
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.
serializationAlwaysInclude	Indicates whether to include the value (default or otherwise) when serializing.
dataModelIgnore	Indicates whether the property is to be included within the data model. † All properties are included in the data model by default.
dataModelSerializationIgnore	Indicates whether the property is not to be serialized where outputting as a data model. † All properties are included in the data model by default.

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 Type.
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 PrimaryKey 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: Set, Ignore, Map, Flatten. † Defaults to Set.

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: Set, Ignore, Map, Flatten. † Defaults to Set.

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: Set, Ignore, Map, Flatten. † Defaults to Set.

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.

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.