Backend C# Code Patterns

When implementing backend C# code in EasyPlatform, follow these patterns exactly.

Full Pattern Reference

See the complete code patterns with examples: backend-code-patterns.md

Quick Reference

Pattern Index

IPlatformQueryableRootRepository<TEntity, TKey>

CreateAsync

GetByIdAsync

GetAllAsync

FirstOrDefaultAsync

CountAsync

PlatformValidationResult.And().AndAsync()

PlatformCqrsEntityEventBusMessageProducer

PlatformApplicationMessageBusConsumer

searchService.Search(q, text, Entity.SearchColumns())

PlatformCqrsCommandApplicationHandler

PlatformCqrsPagedQuery

GetQueryBuilder()

UseCaseEvents/

RootEntity<T, TKey>

[TrackFieldUpdatedDomainEvent]

PlatformEntityDto<T, TKey>.MapToEntity()

.With()

.Then()

.EnsureFound()

.EnsureValid()

.ParallelAsync()

PlatformApplicationPagedBackgroundJobExecutor

[PlatformRecurringJob("cron")]

PlatformApplicationMessageBusConsumer<TMessage>

TryWaitUntilAsync()

PlatformDataMigrationExecutor<TDbContext>

OnlyForDbsCreatedBeforeDate

PlatformEfCorePersistenceModule

PlatformMongoDbPersistenceModule

Critical Rules

1. Repository: Use

   IPlatformQueryableRootRepository<TEntity, TKey>

   - NEVER generic

   IPlatformRootRepository

2. Validation: Use

   PlatformValidationResult

   fluent API (

   .And()

   ,

   .AndAsync()

   ) - NEVER

   throw ValidationException

3. Side Effects: Handle in Entity Event Handlers (

   UseCaseEvents/

   ) - NEVER in command handlers
4. DTO Mapping: DTOs own mapping via

   MapToEntity()

   or

   MapToObject()

   - NEVER map in handlers
5. Command Structure: Command + Result + Handler in ONE file under

   UseCaseCommands/{Feature}/

6. Cross-Service: Use RabbitMQ message bus - NEVER direct database access

Anti-Patterns

// ❌ Direct cross-service DB access → ✅ Use message bus
// ❌ Custom repository interface → ✅ Use platform repo + extensions
// ❌ Manual validation throw → ✅ Use PlatformValidationResult fluent API
// ❌ Side effects in handler → ✅ Use entity event handlers
// ❌ DTO mapping in handler → ✅ DTO owns mapping via MapToObject()/MapToEntity()

Templates

CQRS Command Template

public sealed class Save{Entity}Command : PlatformCqrsCommand<Save{Entity}CommandResult>
{
    public string Id { get; set; } = "";
    public string Name { get; set; } = "";

    public override PlatformValidationResult<IPlatformCqrsRequest> Validate()
        => base.Validate().And(_ => Name.IsNotNullOrEmpty(), "Name required");
}

public sealed class Save{Entity}CommandResult : PlatformCqrsCommandResult
{
    public {Entity}Dto Entity { get; set; } = null!;
}

internal sealed class Save{Entity}CommandHandler : PlatformCqrsCommandApplicationHandler<Save{Entity}Command, Save{Entity}CommandResult>
{
    protected override async Task<Save{Entity}CommandResult> HandleAsync(Save{Entity}Command req, CancellationToken ct)
    {
        var entity = req.Id.IsNullOrEmpty()
            ? req.MapToNewEntity().With(e => e.CreatedBy = RequestContext.UserId())
            : await repo.GetByIdAsync(req.Id, ct).Then(e => req.UpdateEntity(e));
        await entity.ValidateAsync(repo, ct).EnsureValidAsync();
        var saved = await repo.CreateOrUpdateAsync(entity, ct);
        return new Save{Entity}CommandResult { Entity = new {Entity}Dto(saved) };
    }
}

Detailed Instructions

For task-specific guidance, also reference:

• backend-dotnet.instructions.md - .NET patterns
• cqrs-patterns.instructions.md - CQRS handlers
• entity-development.instructions.md - Entity design
• validation.instructions.md - Validation patterns
• repository.instructions.md - Repository patterns
• message-bus.instructions.md - Message bus
• background-jobs.instructions.md - Background jobs
• migrations.instructions.md - Data migrations