How-to Guides

Create and design an entity

Be aware of the following when creating and designing an entity:

  • Each entity must have a field that is set as the primary key.

  • The entity and the fields in the entity will be used to create the database table. Each entity will be created as one table. The field settings will be used to create the table schema.

  • The database is created after you generate projects and then run the Web APIs project. The database file data.db will be created under the Web APIs project.

  • Once the database is created, if you want to make changes to the entity (including adding/deleting/modifying the field or deleting entities), database conflicts may occur and data operations may fail. You will need to manually delete or migrate the database by following instructions in Updating the database after entity changes.

For example, to add a base entity:

Step 1: Right click the design project node and select Add > New Item. In the Add New Item dialog, select Entity design, specify the entity name (for example, “EntityBase”) and then click Create.

Step 2: In the entity designer, click Add fields to add and specify the field settings.

The base entity can contain the fields that are used by all the other entities.

Field Name Field Type Field settings
ID Int32 Key: selected
InsertTime DateTime Default value: Now()
UpdateTime DateTime Default value: Now()

Step 3: Select which models to generate for the base entity and the fields.

Entity Name Models to generate
EntityBase Queryable, Creatable, Updatable
Field Name Models to generate
ID Queryable, Creatable
InsertTime Queryable, Creatable
UpdateTime Queryable, Creatable, Updatable

Step 4: Leave the options in the API Design tab and the View Settings tab as unselected, as there is no need to generate APIs or views for the base entity.

Step 5: You can have a closer look at these settings in the EntityBase.dmedm file in the order sample.

For another example, to add an entity (and inherit fields from the base entity):

Step 1: Right click the design project node and select Add > New Item. In the Add New Item dialog, select Entity design, specify the entity name (for example, “Consumer”) and then click Create.

Step 2: In the entity designer, select to inherit from the base entity, and select the Show base class option so that the fields in the base entity will display as read-only at the end of the field list.

Step 3: Click Add fields to add and specify the field settings.

Field Name Field Type Field settings
ConsumerNo Guid Default value: NewGuid()
Name String Minimum length: 2
Maximum length: 20
Telephone PhoneNumber Regular validation: [add expression as needed]
Regular validation error: [add error message as needed]
Set index: selected
Uniqueness validation: selected
Orders Association to the “Order” entity, many-to-one relationship Collection: selected. If there are more than one order, the orders will be displayed as one value.
Deletion strategy: Cascade Delete

Step 4: Select which models to generate for the entity and the fields.

Entity Name Models to generate
Consumer Queryable, Creatable, Updatable, Deletable
Field Name Models to generate
ConsumerNo Queryable, Updatable
Name Queryable, Creatable, Updatable
Telephone Queryable, Creatable, Updatable
Orders -

Step 5: In the API Design tab, select to generate all basic APIs.

Step 6: In the View Settings tab, select in which page the entity and fields will be shown.

Step 7: You can have a closer look at these settings in the Consumer.dmedm file in the order sample.

Generate database from entities

Once the entities are created, you can generate a database automatically from these entities.

Step 1: After creating the entities in the low-code design project, right click the design project node and select Generate Projects.

Step 2: In the Generate Projects window, click Generate. Make sure the project generation is successful.

When project generation is successful, the following projects are generated: Sample.Client, Sample.Common, Sample.EFCore, Sample.Services, Sample.WebApi.

Step 3: In the IDE toolbar, select Sample.WebApi from the project list and then click Run to start the Web APIs.

Step 4: Once the Web APIs start successfully, the database file (data.db) is automatically generated under the Web APIs project node.

By default, a SQLite database is generated. For more information, refer to Managing and updating database connections.

Add or modify a field in the entity

Once the database file data.db is generated (for example, after generating and running the Web APIs and front-end application), adding/deleting/modifying fields in the existing entities may cause database conflicts (hence data operations will fail). In such cases, you will need to manually delete or migrate the database by following instructions in Updating the database after entity changes.

If you modify the following field settings in the entity, you will also need to manually delete or migrate the database, in order to include these changes in the database schema.

  • Field Name
  • Data Type
  • Collection
  • Nullable
  • EF Core 6 > Key
  • EF Core 6 > Column name
  • EF Core 6 > Column type
  • EF Core 6 > Set concurrency check
  • EF Core 6 > Set index
  • EF Core 6 > Set index > Uniqueness validation

Configure one-to-many relationship between entities

Let’s use the order sample to walk through the process of configuring a one-to-many relationship. In the order sample, there are two entities: Product and Manufacturer. More than one products are associated with one manufacturer. Therefore, we should establish the one-to-many relationship between these two entities.

Step 1: In the Product entity, set the Manufacturer field to associate with the Manufacturer entity; and set the Manufacturer field as queryable, creatable, or updatable according to your needs.

Step 2: Go to the API Design tab, and make sure the Generate options for the corresponding APIs are selected.

Step 3: Go to the View Settings tab, select the field of the Manufacturer entity that you want to display for the Product.Manufacturer field, and then select in which page you want to display the field: list page, new page, edit page, or details page according to your needs.

Step 4: Generate projects and run the application.

Use the inverse navigation property

The inverse navigation property is used when two entities have more than one relationship.

Suppose there are two entities: Employee and Department. The Department.EmpList field needs to associate with the Employee entity (a one-to-one relationship), and the Department.Manager field also needs to associate with the Employee entity (another one-to-one relationship). There are more than one relationship between the Employee and Department entities.

In this case, you should set the Inverse navigation property for the Department.EmpList and Department.Manager fields.

Step 1: In the Employee entity, set the EmpDept field and the ManagerDept field to associate with the Department entity.

Step 2: In the Department entity, set the EmpList field and the Manager field to associate with the Employee entity, and then set the Inverse navigation property:

For the EmpList field, select EmpDept (EmpDept) as the Inverse navigation property

For the Manager field, select ManagerDept (ManagerDept) as the Inverse navigation property

Set both fields to Nullable, and Deletion strategy to Set null, so that if an employee is also a department manager, and when s/he is removed from Employee, the corresponding Department.EmpList and Department.Manager values will be set to null.

Generate CRUD operations for a field

Let’s use the WeatherForecast template project to walk through the process of generating CRUD operations for a field (using the TemperatureC field as an example):

Step 1: Open the WeatherForecast entity file, make sure the Queryable, Creatable, Updatable, and Deletable options are selected for the TemperatureC field. (The Deletable option is effective to all fields in the entity once selected or de-selected)

Step 2: Select the API Design tab, and make sure the Generate option is selected for the Get, GetList, GetPage, Create, Update, and Delete APIs.

Step 3: Select the View Settings tab, make sure the List page, New page, Edit page, and Details page are selected for the TemperatureC field.

Step 4: Generate projects and run the application.

The Temperature (Celsius) field is shown in the list page by default.

Click Add. You can input a value to the Temperature (Celsius) field in the Add page.

Click edit. You can modify the value of the Temperature (Celsius) field in the Edit page.

Click detail. The Temperature (Celsius) field is shown in the Detail page.

Click delete to delete the entire data record including the value of Temperature (Celsius).

Generate a report (using model)

The following steps show you how to add a model to display the average temperature of the weather forecast (using the WeatherForecast template project).

Step 1: Right click the design project node and select Add > New Item. In the Add New Item dialog, select Model design, specify the model name and then click Create.

Step 2: The model design file will by default contain a field. Expand this field, and add an expression to the Read From option.

If you want the field to show the average temperature of the weather forecast, you can double click the Average function and then double click the TemperatureC field, the expression Average(WeatherForecast.TemperatureC) is automatically input as shown below.

Step 3: Change the display name to “Average Temperature”, change the data type to Double, and then select the Queryable option for this field.

Step 4: Select the API Design tab, and then select the Generate option for the Get API.

Step 5: Select the View Settings tab, and then select the Details page option.

Step 6: Generate projects and run the application.

The model you created is automatically listed on the left navigation bar of the application. When you select the model on the left, the page and the data is displayed on the right.

Add a search field (using condition)

To add a search field to the application:

Step 1: Open the entity file in the designer. (Let’s use the WeatherForecast template and open the WeatherForecast.dmedm file directly)

Step 2: Select the Condition Design tab, then click Add Condition, and then specify the options for the new condition.

For example, if you want to add a search field which allows users to input a date and filter out the dates that are greater than the input date, then you should specify the condition settings like below.

Step 3: Select the API Design tab, and then select the Generate option for the GetPage API for the new condition you created just now.

Step 4: Select the View Settings tab, and then select the condition from the Condition list.

Step 5: Generate projects and run the application.

The search field displays on the top of the list page by default.

Step 6: If you select a date and then click Search, the data which date is greater than the selected date will be filtered out.