Entity Data Model
Generator
The following table of contents provides an outline of the documentation for this generator.
1. Overview
Generates Entity Data Model (.edmx) file from the Xomega object model with proper associations between entities,
which further allows generating C# classes for Entity Framework's entities using standard T4 templates. These
entity classes are then used by the service classes generated by the
Service Implementations generator, or by any custom backend code as needed.
The generator uses objects and their fields defined in the model to create EDM entities for both the conceptual model
and the storage model. It also leverages the structure of sub-objects, as well as the way key fields or fieldsets are set up,
in order to infer the associations between the entities, so that they wouldn't need to be defined explicitly.
Objects and Associations. For primary objects (i.e. not sub-objects) with a single key field, the generated
entities will have a set of properties based largely on the list of the object's fields. Xomega model requires key fields
to have dedicated types declared in the model. If such a key type (or any of its derived types) is used for a non-key field,
or for a field with a key attribute set to "reference", then that field will be assumed to reference the object,
for which this is a key type. In this case, the entity will contain the referenced entity using field's name and a postfix "Object".
The following example illustrates how the key field "customer id" of the "customer" object uses a dedicated type, also named
"customer", while the "customer id" field of the "sales order" object below it also uses this type, thereby referencing
the "customer" object.
If the object contains a fieldset in the list of fields, then the entity will contain all fields from
that fieldset, using its fields' names prepended with the name of the fieldset in the object, if set.
If the object has a sub-object defined, then the entity will have a collection of the associated sub-object entities,
with a name of the subobject and a postfix "ObjectList".
Complex Associations and Sub-objects. If an object has a composite key, then it should
have a dedicated fieldset declared in the model, which will be used as the key of type "supplied" on that object.
If such a fieldset is used in another object's fields without a key attribute, or with one set to "reference",
then that other object will be considered as referencing the object with a composite key.
The following example shows how the "special offer product" object has a composite key implemented by the corresponding
fieldset with the same name, and the "detail" subobject of the "sales order" object uses that fieldset,
thereby referencing the "special offer product" object.
The key of the parent object is automatically included in all of its subobjects, and there will be a reference to the parent
entity generated on each subobject entity. On top of that, if the key on the subobject is not "serial" (i.e. not unique),
the parent object's key will be part of the subobject's key as well.
EDM attributes. The EDM attributes for the properties of the generated entities will be largely driven by
configuration of the field's type or its based types. The actual EDM type is specified on the edm:type config element
of the field's type, which may contain some additional attributes as well. The maximum size of the field will come from
the size attribute of the type itself. Whether or not the entity property is required comes from the required
attribute on the field, but each field can have additional field-specific EDM configuration under its edm:property
config element.
The following example illustrates EDM configuration for the logical type "city name", and additional field-specific
EDM attributes for the "rowguid" property.
1.2 Generator outputs
This generator creates Conceptual Model, Storage Model and an EDM Mapping between the two in the specified .edmx file,
including all the necessary Entities and Associations between them. This helps to hide the complexities and intricacies
of different EDM models, and allows you to generate C# classes for the entities from it using standard T4 templates
provided by the Entity Framework. Those T4 generators are automatically included when you use a Xomega solution template
to create your projects. But if you don't have those .tt generators under your .edmx file in the project, you can
open the EDM in the model, and select 'Add Code Generation Item...' context menu to add them.
2. Configuration
The following sections describe configuration parameters used by the generator.
2.1 Generator parameters
The following table lists configuration parameters that are set as the generator’s properties.
| Parameter |
Value Example |
Description |
| Generator Name |
Entity Data Model
|
The name of the current configuration of the generator that will appear in the model project and the build output. |
| Folder |
Data Layer
|
Folder path to the generator inside the Model project. The folders are separated by a backslash (\). |
| Include In Build |
True
|
A flag indicating whether or not running this generator should be included in building of the model project. |
| Output |
| Output Path |
../MySolution.Services.Entities /Entities/EntityModel.edmx |
Relative path where to output generated Entity Data Model file. |
| Add To Project |
../MySolution.Services.Entities /MySolution.Services.Entities.csproj |
Relative path to the project file to add the generated file to. The project will be reloaded every time you run the generator.
Leave it blank if you don't want generated file to be added to your project automatically.
|
| Config File |
../MySolution.Client.Web/Web.config |
Relative path to the configuration file to add entity connection string to based on the project's database connection.
Leave it blank if you don't want entity connection string to be added to your config automatically.
|
| Database |
| Database |
SQL Server |
Database type for the Entity Data Model. Currently only SQL Server (sqlsrv) is supported.
Value 'Use Project Settings' takes this value from the corresponding property of the model project.
|
| Database Version |
11.0 |
The version of the database for the Entity Data Model.
Value 'Use Project Settings' takes this value from the corresponding property of the model project.
|
| Database Case |
CamelCase |
The database case for the database objects' names: UPPER_CASE, lower_case or CamelCase.
Value 'Use Project Settings' takes this value from the corresponding property of the model project.
|
| Database Connection |
Use Project Settings |
Database connection string for the Entity Data Model. Edited via a 'Database Connection Configuration'
dialog, which also sets the other Database parameters of the generator, and allows saving them for the entire project.
Value 'Use Project Settings' takes this value from the corresponding property of the model project.
|
2.2 Model configuration
Configuration parameters for the generator that need to be also accessible to other generators are specified in the Xomega
model in the edm:entities-config element under the top level config element, which is conventionally
placed in the global_config.xom file. These parameters include the name for the generated entity model, as shown below.
2.3 Common configurations
There expected to be just one configuration of this generator in the model, with the parameter values as illustrated above.
3. How to use the generator
The sections below provide some details on how to work with the generator.
3.1 Running the generator
To run this generator, you need to select it in the model project, and then select Generate menu from either the context
menu or the top-level Project menu. This should also automatically run any T4 templates for the EDM file, but if you need
to re-run them manually, you can expand the .edmx file in the project, right click on the corresponding .tt file nested
under it, and select the 'Run Custom Tool' menu option from the context menu.
You can rerun the generator when you change any objects, fields or types in the model, which may require re-running
other generators that depend on the same model elements, such as generators of service implementations.
Therefore, this generator can be included in the build of the model project in the configuration while the entity schema
is still changing, such as during initial prototyping and development. After that it can be excluded from the build,
and rerun manually whenever the schema changes.
3.2 Customizing the output
You should never edit the properties of the generated Entity Data Model directly to avoid losing your changes when you
rerun the generator. You should make your updates to the Xomega model instead. You can lay out the generated EDM entities
on different diagrams in the EDM designer, and they should be preserved when the EDM is regenerated, but it's still better
to move the diagrams to a separate file in the designer.
3.3 Cleaning generator’s output
The generator doesn't support cleaning the entities, since all entities are regenerated when you rerun the generator.
If you delete any objects in the model, you may need to manually delete the generated files with C# entities for those objects.