Generating a CRUD page
When you add an existing project or create a new one, the project will be listed in the "Open Recent" section. To select the project, click on the project name.
Be aware that, ABP Suite generates a unique URL for every project. After you select your project, you can safely bookmark it to your browser to access it faster.
Entity info
To create a new entity, make sure the -New entity- is selected in the Entity combo box which is on the top-right of the page. In this section, you need to provide the meta data of your entity. Do not use C# reserved keywords for your entity name, plural name, database table name or the namespace.
Entity type: Specifies the entity's type. (master or child)
Name: Name of the entity.
Plural name: Folder names of the entity and name of
DbSet
in theDbContext
.Database table/collection name: Name of the database table for relational databases or name of the collection name for NoSQL databases.
Namespace: Namespaces of the entities, DTOs and other
C#
classes.Page title: Specifies the page title for the current entity. It will be used in the page title as the localization key, so you can localize it for different languages later on.
Base class: There are several base classes that comes out of the box from the ABP. Basically there are 2 main types of entity.
AggregateRoot
and simpleEntity
. And these two have 2 more variants withAudited
andFullAudited
derivatives.If your entity consists of child entities like an
Order
with itsOrderDetail
entities, then you should choose AggregateRoot / AuditedAggregateRoot / FullAuditedAggregateRoot.If it doesn't have any child entities like a
City
entity, you can choose Entity / AuditedEntity / FullAuditedEntityAlternatively, you can choose BasicAggregateRoot if you want to create an aggregate root without the
IHasExtraProperties
andIHasConcurrencyStamp
interfaces implemented (extra properties & concurrency check).Entity and AggregateRoot are the low-level simple base classes.
AuditedEntity and AuditedAggregateRoot adds these fields to the entity:
CreationTime
CreatorId
LastModificationTime
LastModifierId
Hence, it keeps track of who created and changed the data with the date time information.
FullAuditedEntity and FullAuditedAggregateRoot adds these fields to the entity:
CreationTime
CreatorId
LastModificationTime
LastModifierId
IsDeleted
DeleterId
DeletionTime
It extends the audited entity features with soft delete functionality. When the data is deleted, it sets the
IsDeleted
field totrue
instead of physically removing it. The ABP automatically filters the soft deleted data on data fetch. Also it saves who and when deleted.
Primary key type: Primary key is a field in a table or collection which uniquely identifies each record. ABP Suite allows you to create an entity with one of the 4 types:
Int
,Long
,Guid
andString
. ABP Suite recommendsGuid
because,- You can identify objects at the application level.
- You can generate
IDs
anywhere, instead of having to roundtrip to the database. - Better migration and replication! When working with other databases it's easy to migrate data with all its child entities because unique across every table, database and server.
- Allows easy distribution of databases across multiple servers
- The performance is not bad as
String
because database systems handleGuids
nicely. - It's being generated as sequentially by the ABP, so that the physical order of the data in your database will be creation order.
Guids
use 16 bytes. When comparing toInt
as 4 bytes, additional 12 bytes do come at a cost.
On the other hand
Int
andLong
types have some other advantages:- Small storage footprint
- Optimal join / index performance
- Useful for data warehousing
- Native data type of the OS and easy to work with in all languages
Customizable code: Specifies hook-points to allow adding custom code blocks. Then, the code blocks that were written by you will not be overridden in the next entity generation and will be respected.
Multi-tenant: For your multi-tenant application, you can set an entity as multi-tenant which means the data will be isolated between the tenants. To make an entity multi-tenant, ABP Suite adds the
IMultiTenant
interface to the entity. Further information see Multi-Tenancy- If you created your application with Separated tenant schema support, then when you enable the multi-tenancy for the entity, database configurations (DbSet definitions and model configurations) will be defined in both
MyProjectNameDbContext
andMyProjectNameTenantDbContext
(can be used for tenant-specific configurations) classes. Otherwise, the database configurations will only be defined in theMyProjectNameDbContext
class for the host.
- If you created your application with Separated tenant schema support, then when you enable the multi-tenancy for the entity, database configurations (DbSet definitions and model configurations) will be defined in both
Add migration: Adds a new migration for the new entity. If you are updating an existing entity, it creates an update migration.
- Update database: When you add a new migration, ABP Suite can automatically execute update-database command so that the changes are being applied to the database.
Create user interface: Creates pages, modals, components,
JavaScript
,CSS
files and adds the new page to the main menu. If you don't have a requirement to manage the entity via user interface, you can uncheck this option.Excel export: Creates a button that exports a list of all the data that were added to the entity to an Excel file.
Bulk delete: Performs bulk deletion of records based on specified criteria.
Create unit & integration tests: Generates unit and integrations tests for your entity.
Concurrency check: Implements the
IHasConcurrencyStamp
interface of the entity. If the base class isAggregateRoot
, concurrency control is enabled by default. For more details see the Concurrency Check document.
Properties
Define a property
A property is a field in the entity which refers a column in the relational database table or a JSON
field in NoSQL
database collection. In the properties section, you can manage the properties your entity. To add a new property, click the "Add Property" button on the top-right of the page.
- Property name: Name of the field. Do not use C# reserved keywords and database reserved keywords.
- Property type: Choose a relevant property type from the list.
- Default Value: Add a default value for this property every time it's created.
- Min-Max length: These values are used to limit the data value. The length of the database column will also be created by taking this number into consideration. ABP validates the data on the client and server side according to these values.
- Regex: Add a general expression for the property.
- Email validation: Choose if your property is an email and needs to be validated.
- Required: Defines whether a value is required or not.
- Filterable: Adds the property into the advanced search filters and includes it in the filters.
- Text area: Make the property a text area to input a text, e.g. description.
- Nullable: Allows you to set the property as
nullable
for theC#
supported data types.
Property list
The list of all properties defined for the entity. You can delete or edit a property.
Sorting
You can use sorting field column to specify or change the order in which results are sorted. To arrange sorting, click the first combo box (Sort Index
) that you want to set order index. Choose Ascending
or Descending
to specify the sort order for the column.
Navigation Properties
A navigation property is a type of property on an entity that allows for navigation from one end of an association to the other end. Unlike normal properties, navigation properties do not carry data.
Navigation properties provide a way to navigate an association between two entity types. Every object can have a navigation property for every relationship in which it participates.
When you create a navigation property with ABP Suite, you will have a dropdown or look up table to pick a record from the dependent record list. ABP Suite allows you to create a navigation property for 1-to-many (1:N) and many-to-many (N:N) relationships.
In this scenario there are multiple records from one entity associated with a single record from another entity. This means you have a principal (parent) entity and many dependent (child) entities.
Let's see an example to understand it deeper...
We will have a Book
entity and an Author
entity. Let each book has an author.
Book
entity (1) is associated toAuthor
entity (N).
Step by step creating a navigation property (with 1-to-many relationship)
Let's see how to create a navigation property for a Book Store project. We will create an Author
entity and a Book
entity. The Book
entity will hold a foreign key to the Author
entity which will store the primary key of the Author
entity.
To create many-to-many relationship, check out Creating Many-To-Many Relationship
1- Create the "Author" entity
Author
entity is the dependent or child entity of the Book
entity. So we will firstly create the Author
entity. In the Entity Info tab, write "Author" in the name field. The rest will be automatically filled. Then click Properties tab and add the below 2 properties:
- Property name:
NameSurname
, Property type:string
- Property name:
Age
, Property type:int
Click Save and generate button and wait for ABP Suite to create the page.
After it finishes, run the web project and go to Authors page. Click New Author button and add the below 3 records:
- Name Surname:
Miguel de Cervantes
, Age:40
- Name Surname:
Charles Dickens
, Age:35
- Name Surname:
Antoine de Saint-Exupery
, Age:45
2- Create the "Book" entity
Book
is the principal (parent) entity. It will hold a reference to the Author
entity in AuthorId
property. Let's create the Book
entity in the ABP Suite. Click -New entity- in the Entity dropdown on the top of the page and write "Book" in the Name field. The rest will be automatically filled. Then click Properties tab and add 2 properties:
- Property name:
Title
, Property type:string
- Property name:
Year
, Property type:int
Click the Navigation properties tab. Then click Add navigation property button. In the opening window, click Select dependent entity textbox. A file browser will pop up. Find the Author.cs
that we previously created in step 1. Author.cs
is located in src\Acme.BookStore.Domain\Authors
directory. After you select the file, almost all fields will be automatically filled, except Display Property. Select NameSurname
from the Properties dropdown. It will write it to the Display Property textbox. Revise the other fields for the last check and click OK button. A new navigation property is added. Click Save and generate button and wait for the ABP Suite to create the Books page with the navigation property.
Notice that almost all fields are automatically filled by convention. If you don't rename the
DTO
names,DbSet
names in theDbContext
, navigation property names or namespaces, this tool will automatically set all required fields. On the other hand, these textboxes are not readonly, so that you can change them according to your requirements.
In the below image, you will see the mappings of the navigation property fields with the code classes.
Description of the navigation property window fields
Entity namespace: Namespace of the dependent (child) entity you want to use as the navigation property. Example:
Acme.BookStore.Authors
.Entity name: Name of the dependent entity. Example
Author
.Display property: Property name of the dependent entity which you want to show as display text on the UI. Should be a string field. Example:
NameSurname
.Primary key: Primary key type of the dependent entity. Example:
Guid
.DTO name: Name of the dependent entity DTO. Example:
AuthorDto
.DTO namespace: Namespace of the dependent entity DTO. Example:
Acme.BookStore.Authors
.Collection name: Collection name or DbSet name of the of the dependent entity in the
DbContext
. You can select your collection name from Collection names dropdown. Example:Authors
.Property name: Name of the property that will be created in the principal (parent) entity. Example:
AuthorId
.UI pick type: Specifies the method of setting the navigation value. There are 2 types:
- Modal: Value is being set in a modal window. A button named as Pick will allow users to open a look up table which has search functionality. User will be able to select a single record from the look up table. It's recommended for entities with large data.
- Dropdown: A dropdown will allow users to select a single record. It's recommended for entities with fewer data.
Database structure of navigation property
AppBooks
table stores items for the principal entity and AppAuthors
stores the items for dependent entity. Each book has an AuthorId
field referenced to Authors
table.
Final look
The below image is the final page created by the ABP Suite. The new book dialog has Author dropdown which lists all authors. After saving the book, the author column will show the NameSurname
field (display property) of the author entity.
Saving an entity
There are 2 options to save an entity.
Save
Saves only the entity as draft and doesn't generate code. This is useful when you don't want to apply changes to your project.
Save and generate
Saves the entity and generates code. Your project will be added a new CRUD page.
Database table
When you click Save and generate button it'll create all the related objects. The below screenshot is the MS-SQL database table which is generated by the ABP Suite.
Establishing/Creating Relations with Installed ABP Modules' Entities
ABP Suite allows you to establish one-to-many relationship with pre-installed ABP Modules. You can add any entity from pre-installed ABP modules as a navigation property, by checking the Include entities from ABP modules checkbox in the navigation property model and choosing the related module entity as in the following figure:
In the example above, the IdentityUser
entity is selected as the navigation property. You can choose any entity from the installed ABP modules in the navigation property model.
Note: Ensure that your solution is built properly before establishing relationship between your own entity and a module entity because ABP Suite scans assemblies and finds which ABP modules you are using and lists their entities in the navigation property model if you have checked the Include entities from ABP modules checkbox.
Adding An Existing Entity as a Navigation Property
Alternatively, you can add IdentityUser
entity (or any other entity) as a navigation property to an entity by manually entering the required information. See the screenshot below:
User interface
New book dialog
Book list page
Troubleshooting
What to Check If Angular UI Cannot Be Generated
There are some adjustments you may need to make before generating CRUD pages for your legacy ABP app using the latest version of the suite.
Check if your environment variables have
rootNamespace
defined as explained here.Check if your workspace configuration satisfies one of the following. Examples assume your solution namespace is
BookStore
,Acme.BookStore
, orAcme.Retail.BookStore
.- Project key is in pascal case. E.g.
BookStore
. - Project key is in camel case. E.g.
bookStore
. - Project key is in kebab case. E.g.
book-store
. - Project is defined as
defaultProject
.
- Project key is in pascal case. E.g.
Generating CRUD Pages via Command Line
You can generate CRUD pages via ABP CLI, without opening ABP Suite's user interface. To do this, you need to pass your entity JSON file and your solution path to the ABP CLI.
Example:
abp suite generate --entity D:\Projects\BookStore\.suite\entities\Book.json --solution D:\Projects\BookStore\Acme.Bookstore.sln
In this example, Book.json
was previously created via ABP Suite.
Parameters
--entity
or-e
: Path of the entity's JSON file.--solution
or-s
: Path of the target solution file (*.sln).
Entity JSON file is the metadata for an entity. It has all the information to generate a CRUD page for an entity. When you generate an entity on ABP Suite, you can find the entity JSON file of that entity in
.suite\entities
folder of the solution. You can use that file directly to re-generate the entity via Abp CLI. When you copy an entity from a solution to another which has different namespace, then you may need to update your entity JSON. The reason for that, the navigation properties are saved with their namespaces, therefore you need to update the namespaces of navigation properties.