Intent.Application.ServiceImplementations.Conventions.CRUD

This module provides automatic implementation of CRUD (Create, Read, Update, Delete) operations for traditional service operations modeled in the Services Designer using a class-based service pattern.

What is CRUD?

CRUD stands for Create, Read, Update, and Delete - the four basic operations for persistent storage. This module automates the implementation of these operations by generating service method code based on mapping actions you configure in the Services Designer, eliminating the need to write repetitive data access code.

What This Module Generates

When you model service operations with appropriate mapping actions, this module generates complete method implementations that:

  • Create Operations: Insert new entities into the database
  • Update Operations: Modify existing entities (including PATCH support for partial updates)
  • Delete Operations: Remove entities from the database
  • Query Operations:
    • Find entities by ID
    • List/query entities with filtering support
    • Query with pagination (when Intent.Application.Dtos.Pagination is installed)

The generated code includes:

  • Repository interactions (fetching, saving, deleting)
  • DTO-to-entity mapping
  • Entity-to-DTO mapping
  • Query filtering and pagination
  • Composite entity handling (automatically fetches parent entities when needed)

How It Works

This module works in conjunction with Intent.Application.DomainInteractions. CRUD implementations are triggered by mapping actions you configure on service operations:

  1. Model your Service in the Services Designer
  2. Add operations (CreateCustomer, UpdateProduct, DeleteOrder, GetById, etc.)
  3. Add mapping actions (Create Entity, Update Entity, Query Entity, Delete Entity)
  4. Configure mappings between DTO fields and entity properties
  5. Run Software Factory - service methods are fully implemented

Key Concept: Mapping Actions Drive Implementation

Simply having a service operation is not enough. The module generates implementations based on explicit mapping actions that connect your DTOs to domain entities. "Map from Domain" only creates the DTO structure - you need mapping actions for CRUD behavior.

Creating CRUD Operations

Quick Start with "Create CRUD Operations"

The fastest way to create CRUD operations is using Intent Architect's built-in wizard:

  1. In the Services Designer, right-click and select Create CRUD Operations
  2. Select Services (not CQRS)
  3. Select the entity you want CRUD operations for
  4. Intent creates all four operations (Create, Update, Delete, Get by ID) with mapping actions pre-configured

This creates a service class with CRUD methods ready to use.

Manual Operation Creation

You can also create operations manually:

  1. Create a Service in the Services Designer
  2. Add an operation (e.g., CreateCustomer)
  3. Add parameters (name, email, etc.)
  4. Right-click the operation and select Create Entity
  5. Select the target entity
  6. Configure the mapping in the dialog

Supported CRUD Operations

Create Operations

Mapping Action: Create Entity

Generates code that:

  • Creates a new entity instance
  • Maps operation parameters to entity properties
  • Adds entity to repository
  • Returns the entity's ID (or other return type)

Example generated code:

public async Task<Guid> CreateCustomer(string name, string email, CancellationToken cancellationToken = default)
{
    var customer = new Customer
    {
        Name = name,
        Email = email,
    };

    _customerRepository.Add(customer);
    await _customerRepository.UnitOfWork.SaveChangesAsync(cancellationToken);
    return customer.Id;
}

For composite entities, automatically fetches and validates parent entities.

Update Operations

Mapping Action: Update Entity

Generates code that:

  • Fetches the existing entity by ID
  • Updates entity properties from parameters
  • Calls repository Update method

Example generated code:

public async Task UpdateCustomer(Guid id, string name, string email, CancellationToken cancellationToken = default)
{
    var customer = await _customerRepository.FindByIdAsync(id, cancellationToken);
    if (customer is null)
    {
        throw new NotFoundException($"Could not find Customer '{id}'");
    }

    customer.Name = name;
    customer.Email = email;

    _customerRepository.Update(customer);
}

Delete Operations

Mapping Action: Delete Entity

Generates code that:

  • Fetches the entity by ID
  • Removes it from the repository
  • Throws NotFoundException if entity doesn't exist

Example generated code:

public async Task DeleteCustomer(Guid id, CancellationToken cancellationToken = default)
{
    var customer = await _customerRepository.FindByIdAsync(id, cancellationToken);
    if (customer is null)
    {
        throw new NotFoundException($"Could not find Customer '{id}'");
    }

    _customerRepository.Remove(customer);
}

Query Operations (Find by ID)

Mapping Action: Query Entity (single result)

Generates code that:

  • Fetches entity by ID from repository
  • Maps entity to DTO
  • Throws NotFoundException if not found

Example generated code:

public async Task<CustomerDto> GetCustomer(Guid id, CancellationToken cancellationToken = default)
{
    var customer = await _customerRepository.FindByIdAsync(id, cancellationToken);
    if (customer is null)
    {
        throw new NotFoundException($"Could not find Customer '{id}'");
    }

    return customer.MapToCustomerDto(_mapper);
}

Query Operations (List/Filter)

Mapping Action: Query Entity (collection result)

Generates code that:

  • Queries entities from repository
  • Applies filtering based on operation parameters
  • Maps entities to DTOs
  • Supports pagination when configured

Example generated code:

public async Task<List<OrderDto>> GetCustomerOrders(Guid customerId, CancellationToken cancellationToken = default)
{
    var orders = await _orderRepository.FindAllAsync(x => x.CustomerId == customerId, cancellationToken);
    return orders.MapToOrderDtoList(_mapper);
}

PATCH Support for Partial Updates

When you need to update only specific fields (partial update), use HTTP PATCH semantics:

  1. Model an Update operation
  2. Make relevant domain entity attributes nullable
  3. Make corresponding operation parameters nullable
  4. Expose the operation as HTTP endpoint with Verb = PATCH (in Http Settings stereotype)

The generated code will only update fields that are present (non-null) in the request:

public async Task UpdateProduct(Guid id, string? name, string? description, decimal? price, CancellationToken cancellationToken = default)
{
    var product = await _productRepository.FindByIdAsync(id, cancellationToken);
    if (product is null)
    {
        throw new NotFoundException($"Could not find Product '{id}'");
    }

    if (name != null)
    {
        product.Name = name;
    }
    if (description != null)
    {
        product.Description = description;
    }
    if (price != null)
    {
        product.Price = price.Value;
    }

    _productRepository.Update(product);
}

Requirements for PATCH:

  • Domain attributes must be nullable
  • Operation parameters must be nullable
  • HTTP Verb must be set to "PATCH"

Query Filtering

You can model query filters using the Query Action in the Services Designer:

  1. Add parameters to your operation (e.g., customerId, status)
  2. Apply Query Action mapping
  3. Configure how parameters map to query filters

The module generates LINQ expressions for filtering:

var orders = await _orderRepository
    .FindAllAsync(x => x.CustomerId == customerId && x.Status == status, cancellationToken);

Supports:

  • Equality comparisons
  • Boolean properties (simplified expressions: x.IsActive instead of x.IsActive == true)
  • Literal values in filters
  • Complex nested queries

Pagination Support

When Intent.Application.Dtos.Pagination component is installed:

  1. Add paging parameters to your operation (PageNo, PageSize)
  2. The module generates paginated query code:
var orders = await _orderRepository
    .FindAllAsync(
        x => x.CustomerId == customerId,
        queryOptions => queryOptions
            .OrderBy(x => x.OrderDate)
            .Skip((pageNo - 1) * pageSize)
            .Take(pageSize),
        cancellationToken);

For more on pagination, see the Intent.Application.Dtos.Pagination documentation.

Composite Entity Handling

When working with composite entities (entities that cannot exist without a parent), the module automatically:

  1. Fetches the parent entity first
  2. Validates parent exists
  3. Adds/updates the child entity through the parent's collection

This ensures referential integrity and follows aggregate root patterns.

Customizing Generated Code

By default, service methods are generated with [IntentManaged(Mode.Fully)] on the method body when mappings are configured. The Software Factory manages the entire implementation.

If mappings are not fully configured or you want to customize:

  • The method body uses [IntentManaged(Mode.Merge)]
  • A commented throw new NotImplementedException() is generated with [IntentInitialGen]
  • You can add custom logic alongside generated code

For complete custom control, change the attribute to [IntentManaged(Mode.Ignore)] and the Software Factory will not modify your implementation.

When to Use Service Implementations CRUD vs MediatR CRUD

Use Service Implementations CRUD (this module) when:

  • You prefer traditional object-oriented service design
  • Operations are naturally grouped by business capability
  • Your team is familiar with service-oriented patterns
  • You want methods on a class rather than discrete request objects
  • You're working with existing service-oriented patterns

Use MediatR CRUD when:

  • You're using the CQRS pattern with MediatR
  • Operations benefit from pipeline behaviors (validation, logging, transactions)
  • You prefer loose coupling via the mediator pattern
  • Individual operations have complex, distinct concerns
  • You want request/response as first-class objects

Both modules provide the same CRUD implementation capabilities through mapping actions.

Integration with Other Modules

This module works with:

  • Intent.Application.ServiceImplementations - Provides the service class infrastructure
  • Intent.Application.DomainInteractions - Provides the mapping action system that drives CRUD implementations
  • Intent.Application.Dtos - DTOs for response contracts
  • Intent.Application.Dtos.Pagination - Pagination support for query operations
  • Intent.Entities - Domain entities being operated on
  • Intent.EntityFrameworkCore / Intent.CosmosDB / etc. - Repository implementations

For more on traditional Application Services, see Intent.Application.ServiceImplementations documentation.

External Resources