Add New Entity

Overview

The EF Core entity and its attributes form the foundation of everything in Spiderly. All other components are built and generated based on these entities.

In this step-by-step guide, you'll learn how to create a new entity in your project using the Spiderly CLI, which automates the entire process including backend entity creation, frontend page generation, routing, and navigation menu setup.

Add New Entity

Run the following command from the root of your application:

spiderly add-new-entity

Or, if you want to generate a data view instead of a table for the list page:

spiderly add-new-entity --data-view

The CLI will prompt you to enter the entity name in PascalCase (e.g., YourEntityName).

This command will automatically generate:

1. Backend Entity:

   • Backend\YourAppName.Business\Entities\YourEntityName.cs

2. List Page:

   • Frontend\src\app\pages\your-entity-name\your-entity-name-list.component.ts
   • Frontend\src\app\pages\your-entity-name\your-entity-name-list.component.html

3. Details Page:

   • Frontend\src\app\pages\your-entity-name\your-entity-name-details.component.ts
   • Frontend\src\app\pages\your-entity-name\your-entity-name-details.component.html

4. Routes in Frontend\src\app\app.routes.ts

5. Menu Item in Frontend\src\app\business\layout\layout.component.ts

Customize the Entity

After generation, open the entity file at Backend\YourAppName.Business\Entities\YourEntityName.cs and customize it according to your needs.

The entity class inherits from BusinessObject<ID> which supports create, read, update and delete operations. If you need a read-only entity that does not support create, update, or delete operations from the UI, change the base class to ReadonlyObject<ID>.

Optimistic concurrency

Every BusinessObject<ID> carries a [ConcurrencyCheck] Version column that gives you optimistic concurrency for free — ReadonlyObject<ID> has none. Spiderly manages it end to end, so you never set or increment it yourself:

• On insert, Version is set to 1; on every update it is incremented inside SaveChanges.
• The value round-trips to the client on the entity's DTO, so the client always holds the version it last read.
• On update, the generated Save{Entity} reloads the row and compares the stored Version against the one the client sent back. If they differ, the write is rejected with a localized ConcurrencyException.

This means two users editing the same record can't silently overwrite each other — the second save fails loudly instead of clobbering the first. No per-entity configuration is required. (The check runs on update only: deletes use a bulk ExecuteDeleteAsync and are not version-guarded, and inserts have no version to race — guard duplicate creation with a unique index instead.)

Example of a customized entity:

namespace YourAppName.Business.Entities
{
    [SpiderlyEntity]
    [DoNotAuthorize]
    public class YourEntityName : BusinessObject<long>
    {
        [StringLength(75, MinimumLength = 1)]
        [Required]
        public string Name { get; set; }

        [UIControlType(nameof(UIControlTypeCodes.TextArea))]
        [StringLength(500, MinimumLength = 1)]
        public string Description { get; set; }
    }
}

The [SpiderlyEntity] attribute is required — source generators only enroll classes that carry it. The CLI adds it for you; on hand-created entities, add it yourself. Hand-written DTOs use [SpiderlyDTO]. Generated DTOs ({Entity}DTO, {Entity}SaveBodyDTO, {Entity}MainUIFormDTO) are emitted by Spiderly and need no marker.

Database Table Naming

Spiderly creates database tables with the exact same name as your entity class — singular, PascalCase. For example, a YourEntityName class produces a "YourEntityName" table, not "YourEntityNames".

Add Your Entity to the Database

Open a terminal in the Backend folder and run the following commands to create and apply a migration:

spiderly add-migration YourMigrationName
spiderly update-database