Hmz.Core.SharedKernel 0.1.7

Hmz.Core.SharedKernel (SharedKernel)

The shared kernel library for the Hmz ecosystem providing core abstractions, utilities, and domain building blocks that serve as the foundation for all Hmz projects.

Overview

This project contains reusable patterns and utilities based on Domain-Driven Design (DDD) principles and Clean Architecture. It provides a consistent foundation for building domain-driven applications within the Hmz family of projects.

Features

🛡️ Guard Clauses & Validation

Leverage Ardalis.GuardClauses for concise and expressive input validation:

Guard.Against.Null(input);
Guard.Against.NullOrEmpty(text);
Guard.Against.OutOfRange(age, min: 0, max: 120);

📋 Result Pattern

Implement consistent error handling with Ardalis.Result:

public Result<User> CreateUser(string email)
{
 Guard.Against.NullOrEmpty(email);

 var user = new User(email);
 return Result.Success(user);
}

🔍 Specification Pattern

Build complex queries in a domain-driven way with Ardalis.Specification and Entity Framework Core integration:

public class ActiveUserSpec : Specification<User>
{
 public ActiveUserSpec()
 {
 Query.Where(u => u.IsActive);
 }
}

var users = await repository.ListAsync(new ActiveUserSpec());

🏷️ Smart Enums

Type-safe enumerations with Ardalis.SmartEnum:

public class UserStatus : SmartEnum<UserStatus>
{
 public static readonly UserStatus Active = new("Active", 1);
 public static readonly UserStatus Inactive = new("Inactive", 2);

 private UserStatus(string name, int value) : base(name, value) { }
}

🧪 HTTP Client Testing

Utilities for testing HTTP clients with Ardalis.HttpClientTestExtensions.

🔧 Startup Services Management

Introspect and list registered services with Ardalis.ListStartupServices.

🌐 ASP.NET Core Integration

Seamless integration with ASP.NET Core through Ardalis.Result.AspNetCore.

Project Setup

Configuration

• Target Framework: .NET 10
• C# Language Version: Latest (preview)
• Nullable Reference Types: Enabled
• Implicit Usings: Enabled
• Treat Warnings as Errors: Enabled

Package Information

• Package ID: Hmz.Core.SharedKernel
• Version: 0.1.0
• Target: Distributed as a NuGet package for use across Hmz projects

Usage

In a .NET Project

1. Add package reference:

dotnet add package Hmz.Core.SharedKernel

2. Use the utilities:

using Ardalis.GuardClauses;
using Ardalis.Result;

public class OrderService
{
 public Result<Order> CreateOrder(OrderRequest request)
 {
 Guard.Against.Null(request);
 Guard.Against.NullOrEmpty(request.CustomerId);

 var order = new Order(request.CustomerId);
 return Result.Success(order);
 }
}

Dependencies

All dependencies are managed through Directory.Packages.props at the solution level:

• Ardalis.GuardClauses - Guard clauses and validation
• Ardalis.HttpClientTestExtensions - HTTP client testing utilities
• Ardalis.ListStartupServices - Service introspection
• Ardalis.Result - Result pattern
• Ardalis.Result.AspNetCore - ASP.NET Core integration
• Ardalis.SharedKernel - Shared kernel abstractions
• Ardalis.SmartEnum - Smart enumerations
• Ardalis.Specification - Specification pattern
• Ardalis.Specification.EntityFrameworkCore - EF Core integration

Best Practices

When extending the SharedKernel:

1. Validation First: Always validate inputs using Guard clauses

   Guard.Against.NullOrEmpty(name, nameof(name));
   

2. Consistent Error Handling: Use Result pattern for operations that can fail

   return Result.Failure("User not found");
   

3. Domain-Driven Queries: Leverage Specification pattern for complex queries

   var spec = new UsersByRoleSpec(role);
   var users = await repository.ListAsync(spec);
   

4. Type-Safe Enums: Use SmartEnum for status and state enumerations

   if (status == OrderStatus.Pending)
   {
    // Handle pending order
   }
   

Building and Testing

Build the Project

dotnet build

Run Tests

dotnet test

Create NuGet Package

dotnet pack --configuration Release

Architecture

The SharedKernel follows these architectural principles:

• Domain-Driven Design (DDD): Core domain concepts are clearly expressed
• Clean Architecture: Separation of concerns with clear boundaries
• SOLID Principles: Adherence to design principles for maintainability
• Reusability: Components are designed to be used across multiple projects

Contributing

When adding new features to the SharedKernel:

1. Ensure compatibility with .NET 10
2. Follow the existing patterns and conventions
3. Add proper guard clauses and validation
4. Use the Result pattern for error handling
5. Document public APIs thoroughly
6. Update this README if adding major features

Support

For questions or issues regarding the SharedKernel, please refer to the main documentation or contact the Hmz development team.