Skip to main content

RA.Utilities.Data.Entities

NuGet version NuGet Downloads Codecov Publish NuGet GitHub license

RA.Utilities.Data.Entities provides a standardized, strongly typed foundation of generic base classes for domain and data models in .NET and Entity Framework Core applications.

It eliminates repetitive boilerplate code and guarantees consistency across your data layer by offering standardized primary keys, distinct creation and modification timestamping, user auditing, and soft-delete capabilities.

🎯 Purpose​

In enterprise applications, data models often share common infrastructural requirements: unique identification, audit trails, and deletion tracking. Manually implementing these properties on every entity introduces typos, inconsistent naming conventions, and maintenance overhead.

This package solves these problems by providing:

  • Uniformity: Standardized property names (Id, CreatedAt, LastModifiedAt, CreatedBy, LastModifiedBy, IsDeleted) across the entire codebase.
  • Flexible Key Typing: Complete freedom to use Guid, int, long, string, or custom strongly typed IDs via the generic type parameter TKey.
  • Segregated Concerns: Clean separation between append-only/immutable entities (BaseEntity<TKey>) and mutable entities (WriteEntity<TKey>).
  • Zero Dependencies: Pure .NET base classes with no external package requirements.

✨ Key Features​

  • Entity Marker Interface (IEntity) — A memberless root contract implemented by every base class, so generic abstractions (such as the repository contracts) can constrain to entities without requiring a specific base class.
  • Generic Identifiers (TKey) — Type-safe primary key support on every base class.
  • Append-Only Tracking — Lightweight CreatedAt tracking via BaseEntity<TKey>.
  • Full Lifecycle Timestamps — Dual CreatedAt and LastModifiedAt tracking via WriteEntity<TKey>.
  • Soft Deletion — Built-in IsDeleted lifecycle flag via SoftDeleteEntity<TKey>.
  • User Auditing — Track who created and modified records via AuditableBaseEntity<TKey>.
  • Zero Configuration — Ready to use instantly without dependency injection or external configuration.

🛠️ Getting Started​

Prerequisites​

  • .NET 10.0 or later

Installation​

.NET CLI

dotnet add package RA.Utilities.Data.Entities

Package Manager Console

Install-Package RA.Utilities.Data.Entities

PackageReference (csproj)

<PackageReference Include="RA.Utilities.Data.Entities" Version="10.1.1" />

Hello World​

The simplest way to use the package is to inherit from WriteEntity<TKey> for your domain entities:

using System;
using RA.Utilities.Data.Entities;

public class Product : WriteEntity<Guid>
{
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
}

No service registration or dependency injection setup is required. The Product entity immediately inherits Id (Guid), CreatedAt (DateTime), and LastModifiedAt (DateTime?).

🧠 Core Concepts​

The package organizes data model concerns into a clear, single-inheritance hierarchy rooted at the IEntity marker interface and CoreEntity<TKey>.

ClassBase ClassPrimary RoleKey Properties
IEntityNone (Root marker)Marker interface for all entitiesNone (no members)
CoreEntity<TKey>IEntityUnique identity contractId
BaseEntity<TKey>CoreEntity<TKey>Immutable / append-only entitiesId, CreatedAt
WriteEntity<TKey>CoreEntity<TKey>Standard mutable entitiesId, CreatedAt, LastModifiedAt
SoftDeleteEntity<TKey>WriteEntity<TKey>Soft-deletable recordsId, CreatedAt, LastModifiedAt, IsDeleted
AuditableBaseEntity<TKey>WriteEntity<TKey>User-audited recordsId, CreatedAt, LastModifiedAt, CreatedBy, LastModifiedBy

Inheritance Architecture​

IEntity (marker — no members)
└── CoreEntity<TKey> (Id)
    ├── BaseEntity<TKey> (CreatedAt)
    └── WriteEntity<TKey> (CreatedAt, LastModifiedAt)
        ├── SoftDeleteEntity<TKey> (IsDeleted)
        └── AuditableBaseEntity<TKey> (CreatedBy, LastModifiedBy)

Terminology​

  • Entity Marker (IEntity): The memberless root interface implemented by every base class; it lets generic abstractions such as the repository contracts constrain their type parameters to entities.
  • TKey: The data type of the entity's primary key (e.g., Guid, long, int, string).
  • Creation Timestamp (CreatedAt): Set once when the entity is first persisted; represents when the record was born.
  • Modification Timestamp (LastModifiedAt): Updated whenever the entity's state changes; null if the entity has never been updated since creation.
  • Soft Deletion (IsDeleted): Flag indicating that an entity is logically deleted without removing its row from storage, preserving relational integrity.
  • Auditing (CreatedBy / LastModifiedBy): Captures user identifiers (usernames, user IDs, or system agents) responsible for lifecycle operations.

📖 How-To Guides​

1. Create an Append-Only or Event Log Entity​

Use BaseEntity<TKey> for immutable records such as event store entries, access logs, or transaction histories where records are inserted once and never modified.

using RA.Utilities.Data.Entities;

public class SecurityAuditLog : BaseEntity<long>
{
    public string EventType { get; set; } = string.Empty;
    public string IpAddress { get; set; } = string.Empty;
    public string Details { get; set; } = string.Empty;
}

2. Create a Mutable Entity with Timestamps​

Use WriteEntity<TKey> for domain models that can be updated over time.

using System;
using RA.Utilities.Data.Entities;

public class Customer : WriteEntity<Guid>
{
    public string FullName { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public bool IsActive { get; set; } = true;
}

3. Implement Soft Deletion​

Inherit from SoftDeleteEntity<TKey> to enable logical deletion.

using System;
using RA.Utilities.Data.Entities;

public class Article : SoftDeleteEntity<Guid>
{
    public string Title { get; set; } = string.Empty;
    public string Content { get; set; } = string.Empty;
}

4. Track User Identity on Data Changes​

Inherit from AuditableBaseEntity<TKey> to record the user responsible for creating and modifying entities.

using System;
using RA.Utilities.Data.Entities;

public class Invoice : AuditableBaseEntity<Guid>
{
    public string InvoiceNumber { get; set; } = string.Empty;
    public decimal Subtotal { get; set; }
    public decimal Tax { get; set; }
}

5. Combine Soft Deletion with User Auditing​

When you require both soft deletion and user auditing, create a composite base class in your domain layer:

using System;
using RA.Utilities.Data.Entities;

/// <summary>
/// Combines user auditing and soft deletion support for domain entities.
/// </summary>
/// <typeparam name="TKey">The type of the primary key.</typeparam>
public abstract class AuditableSoftDeleteEntity<TKey> : AuditableBaseEntity<TKey>
{
    /// <summary>
    /// Gets or sets a value indicating whether the entity is marked as deleted.
    /// </summary>
    public bool IsDeleted { get; set; }
}

public class Order : AuditableSoftDeleteEntity<Guid>
{
    public DateTime OrderDate { get; set; }
    public decimal TotalAmount { get; set; }
    public Guid CustomerId { get; set; }
}

6. Configure with Entity Framework Core​

These base entities work naturally with EF Core. You can configure table mappings, keys, and global query filters in your DbContext:

using System;
using Microsoft.EntityFrameworkCore;
using RA.Utilities.Data.Entities;

public class ApplicationDbContext : DbContext
{
    public DbSet<Product> Products => Set<Product>();
    public DbSet<Article> Articles => Set<Article>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);

        modelBuilder.Entity<Product>(entity =>
        {
            entity.HasKey(e => e.Id);
            entity.Property(e => e.Name).IsRequired().HasMaxLength(200);
            entity.Property(e => e.Price).HasPrecision(18, 2);
        });

        // Global query filter to automatically filter out soft-deleted records
        modelBuilder.Entity<Article>(entity =>
        {
            entity.HasKey(e => e.Id);
            entity.HasQueryFilter(e => !e.IsDeleted);
        });
    }
}

⚙️ Configuration​

This package has no configuration options and requires no dependency injection setup. All types are abstract base classes ready for direct inheritance.

🙌 Contributing & Support​

Found a bug or have a suggestion?​

Contributing​

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin feature/my-new-feature)
  5. Submit a Pull Request
ResourceURL
NuGetRA.Utilities.Data.Entities on NuGet
SourceGitHub — RedonAlla/RA.Utilities
LicenseMIT License
DocumentationOfficial Documentation