BaseShared 1.1.0

BaseShared

Shared building blocks for .NET solutions. This package provides reusable domain primitives, CQRS abstractions, result pattern, validation helpers, specification pattern, repository and unit-of-work abstractions, and supporting utilities that can be used in any domain.

Contents

• Domain base types
  • BaseEntity, AggregateRoot, ValueObject
  • Domain event interfaces and base classes (IDomainEvent, BaseDomainEvent, IDomainEventHandler)
  • IDateTime abstraction for testable time access
• Result pattern
  • Result, Error, ValidationError, ErrorType, CommonErrors
  • Extensions to convert results to API responses (ApiResponse, ResultToResponseMapper)
• CQRS abstractions
  • ICommand, ICommandHandler<TCommand>
  • IQuery<TResult>, IQueryHandler<TQuery, TResult>
• Repository and Unit of Work
  • Generic repository interface IRepository<T> for aggregate roots
  • Unit of work abstraction IUnitOfWork and error definitions UnitOfWorkErrors
• Specification pattern
  • ISpecification<T>, BaseSpecification<T>
  • SpecificationExtensions for combining and applying specifications
• Validation helpers
  • CommonRegularExpressions, CommonValidationErrors
  • Validation extensions for primitives, enums, dates and pagination
• Common utilities
  • PaginatedResult<T> and PaginationExtensions
  • ChangeWrapper<T> for tracking value changes
  • IDomainService marker interface
  • Date/time extensions (DateTimeExtensions)
  • Time zone support via IANATimeZone
• Email models
  • EmailAddress, EmailAttachment, EmailMessage, EmailSendResult

Installation

After you have added the package source (local feed, private feed, or nuget.org), install the package into your project:

dotnet add package BaseShared --version 1.0.1

Or use the Manage NuGet Packages UI in Visual Studio and search for BaseShared.

Basic usage

Working with the Result pattern

using Meta.Shared.ResultPattern;

public async Task<Result<User>> RegisterUserAsync(RegisterUserCommand command)
{
    if (await _userRepository.ExistsAsync(command.Email))
    {
        return Result.Failure<User>(CommonErrors.Conflict("User with this email already exists."));
    }

    var user = new User(command.Email, command.Name);
    await _userRepository.AddAsync(user);

    return Result.Success(user);
}

CQRS handlers

using Meta.Shared.CQRS;
using Meta.Shared.ResultPattern;

public sealed record GetUserByIdQuery(Guid Id) : IQuery<Result<UserDto>>;

public sealed class GetUserByIdQueryHandler
    : IQueryHandler<GetUserByIdQuery, Result<UserDto>>
{
    private readonly IUserReadRepository _users;

    public GetUserByIdQueryHandler(IUserReadRepository users) => _users = users;

    public async Task<Result<UserDto>> Handle(GetUserByIdQuery query, CancellationToken cancellationToken)
    {
        var user = await _users.GetByIdAsync(query.Id, cancellationToken);
        if (user is null)
        {
            return Result.Failure<UserDto>(CommonErrors.NotFound("User"));
        }

        return Result.Success(new UserDto(user.Id, user.Email, user.Name));
    }
}

Specifications and repositories

using Meta.Shared.RepositoryPattern;
using Meta.Shared.SpecificationPattern.Core;

public sealed class ActiveUsersSpecification : BaseSpecification<User>
{
    public ActiveUsersSpecification()
    {
        AddCriteria(u => u.IsActive);
        AddOrderBy(u => u.CreatedOnUtc);
    }
}

public async Task<IReadOnlyList<User>> GetActiveUsersAsync(IRepository<User> repository)
{
    var spec = new ActiveUsersSpecification();
    return await repository.ListAsync(spec);
}

Domain base classes

using Meta.Shared.Common;
using Meta.Shared.Common.DomainEvents;

public sealed class User : AggregateRoot<Guid>
{
    // Value object and properties omitted for brevity

    public void Activate()
    {
        // business rules...
        AddDomainEvent(new UserActivatedDomainEvent(Id));
    }
}

public sealed record UserActivatedDomainEvent(Guid UserId) : BaseDomainEvent;

How to use this package in new solutions

1. Add the package source

• Point NuGet to your feed that contains BaseShared.1.0.1.nupkg (local folder, Azure Artifacts, GitHub Packages, or nuget.org).

2. Install the package

• Add BaseShared to your application, API, or infrastructure projects.

3. Adopt the patterns

• Use the provided domain base classes for new aggregates and entities.
• Implement commands, queries and handlers using the CQRS interfaces.
• Return Result/Result<T> from your application services and handlers.
• Use repositories, unit of work and specifications to access your persistence layer.
• Reuse validation helpers and common error definitions for consistent validation and error handling.

4. Extend as needed

• If your project requires additional shared primitives or patterns, add them to BaseShared and publish a new package version.

Target framework

BaseShared currently targets .NET 9.0 (net9.0). Consumer projects must target .NET 9.0 or a compatible later framework.