DEV Community: Kostiantyn Bilous

MediatR Response: Should the Request Handler Return Exceptions?

Kostiantyn Bilous — Fri, 03 May 2024 05:25:27 +0000

In the evolving landscape of software architecture, the choice between traditional exception handling and adhering to functional programming principles to manage errors directly impacts system design and reliability.

Clean architecture advocates for systems independent of frameworks, UI, databases, and external agencies. This independence is crucial for maintaining the system's integrity over time. In line with this, exceptions - traditionally used to handle unforeseen errors - should be reserved for circumstances outside the application's normal functioning. However, the debate continues on how to handle predictable errors and validations.
On one side, proponents of thin controllers in architectures argue that the business logic should be encapsulated away from the API layer, making the API layer as lean as possible. This approach typically leads to handling exceptions at the middleware or framework level, thus maintaining a separation of concerns where controllers focus solely on routing and minimal preprocessing.

Conversely, functional programming offers an alternative by emphasizing immutability and pure functions, which leads to systems that are easier to reason about and test. Here, errors are treated as first-class citizens, taking the form of predictable results rather than as exceptions. This method suggests that all possible outcomes - including errors - are part of a function's expected result, encapsulated in types like Result, which can explicitly represent success or failure states without throwing exceptions.

Both methodologies aim to reduce side effects and enhance system robustness, yet they employ fundamentally different approaches to achieve these objectives. This article will compare these two paradigms by implementing the creation of a Bank Account, where domain validations ensure the account's name and associated bank are valid. We will explore exception handling at the API and application layers using NuGet packages like Ardalis.GuardClauses for assertions that throw ArgumentExceptions if the domain validation rules are violated and employing MediatR and FluentResults to handle operation outcomes more functionally.

Two Approaches to Handling Exceptions

For example, we will implement the creation and persistence of a new Bank Account domain entity from a personal investment tracking application, InWestMan, using two approaches to exception handling: Middleware-Based Error Handling at the API layer and Result Pattern at the application layer.

Upon creation and reconstitution, the Bank Account domain checks that its name is not blank and is associated with a bank. If the check fails, the domain object will throw an ArgumentException. For this purpose, I use Ardalis.GuardClauses NuGet package, which simplifies the domain validations.

using Ardalis.GuardClauses;
using InWestMan.DomainEvents;
using InWestMan.Globals.Currencies;
using InWestMan.Parties;

namespace InWestMan.Assets.BankAccounts;

public class BankAccount : Asset
{
    private BankAccount() { }

    public BankAccount(string name, Guid bankId, CurrencyCode currencyCode) : base(name, currencyCode)
    {
        Guard.Against.NullOrWhiteSpace(name, nameof(Name)); //throws ArgumentException
        Guard.Against.Null(bankId, nameof(BankId)); //throws ArgumentException
        Name = name;
        BankId = bankId;
    }

    public Party Bank { get; set; } = null!;
    public Guid BankId { get; set; }

    public void UpdateBank(Guid bankId)
    {
        Guard.Against.NullOrEmpty(bankId, nameof(BankId)); //throws ArgumentException
        if (!BankId.Equals(bankId))
        {
            BankId = bankId;
            Events.Add(new EntityFieldUpdated<BankAccount>(nameof(BankId), bankId.ToString()));
        }
    }
}

1. Middleware-Based Error Handling

At the application layer, the Create command is designed to generate a new bank account entity, save it in the database, and return a unique identifier (GUID) of this bank account. This is reflected in the structured AddBankAccountCommand, which requires specific details such as the account name, currency code, and associated bank ID, each marked as required to ensure data integrity immediately.

public class AddBankAccountCommand : IRequest<Guid>
{
    [Required] public string Name { get; set; } = string.Empty;

    [Required] public CurrencyCode CurrencyCode { get; set; }

    [Required] public Guid BankId { get; set; }
}

The handler for this command, AddBankAccountCommandHandler, is tasked with validating the request against existing records to prevent duplications using a domain-specific specification. If duplication is detected, it throws a ValidationException, creating unique bank accounts. This validation process is essential for maintaining data consistency and reliability within the system.

using System.ComponentModel.DataAnnotations;
using InWestMan.Assets.BankAccounts.Specifications;
using InWestMan.Repositories;
using MediatR;

namespace InWestMan.Assets.BankAccounts.Commands.AddBankAccount;

public class AddBankAccountCommandHandler : IRequestHandler<AddBankAccountCommand, Guid>
{
    private readonly IRepository<BankAccount> _repository;

    public AddBankAccountCommandHandler(IRepository<BankAccount> repository)
    {
        _repository = repository;
    }

    public async Task<Guid> Handle(AddBankAccountCommand request, CancellationToken cancellationToken)
    {
        var bankAccountByNameSpecification = new BankAccountByNameSpecification(request.Name);
        if (await _repository.AnyAsync(bankAccountByNameSpecification, cancellationToken))
            throw new ValidationException("The bank account with the same name already exists.");

        var newBankAccount = new BankAccount(request.Name, request.BankId, request.CurrencyCode);

        await _repository.AddAsync(newBankAccount, cancellationToken);

        return newBankAccount.Id;
    }
}

In the corresponding controller method, the API layer handles the client's POST request by mapping the incoming DTO AddBankAccountCommand and dispatching it using MediatR. The result, which includes the newly created bank account's GUID, is then returned to the client, facilitating a responsive and interactive user experience.

    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesDefaultResponseType]
    public async Task<ActionResult<Guid>> Create([FromBody] CreateBankAccountDto createDto)
    {
        var command = _mapper.Map<AddBankAccountCommand>(createDto);
        var commandResult = await _mediator.Send(command);

        return CreatedAtAction(nameof(GetById), new { id = commandResult }, commandResult);
    }

Transitioning to error handling, we employ middleware to intercept and transform exceptions into structured HTTP responses. This middleware ensures that all unhandled exceptions are caught and appropriately formatted before being sent back to the client, thus safeguarding the API from leaking sensitive error details and providing a consistent error-handling mechanism across the application.

using System.ComponentModel.DataAnnotations;
using System.Net;
using System.Text.Json;

namespace InWestMan.Middlewares;

public class ExceptionHandlerMiddleware
{
    private readonly RequestDelegate _next;

    public ExceptionHandlerMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task Invoke(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception ex)
        {
            await ConvertException(context, ex);
        }
    }

    private Task ConvertException(HttpContext context, Exception exception)
    {
        var httpStatusCode = HttpStatusCode.InternalServerError;

        context.Response.ContentType = "application/json";

        var result = string.Empty;

        switch (exception)
        {
            case ValidationException validationException:
                httpStatusCode = HttpStatusCode.BadRequest;
                result = JsonSerializer.Serialize(validationException.ValidationResult.ErrorMessage);
                break;
            case ArgumentException argumentException:
                httpStatusCode = HttpStatusCode.BadRequest;
                result = JsonSerializer.Serialize(argumentException.Message);
                break;
            case BadRequestException badRequestException:
                httpStatusCode = HttpStatusCode.BadRequest;
                result = badRequestException.Message;
                break;
            case NotFoundException:
                httpStatusCode = HttpStatusCode.NotFound;
                break;
            case not null:
                httpStatusCode = HttpStatusCode.BadRequest;
                break;
        }

        context.Response.StatusCode = (int)httpStatusCode;

        if (result == string.Empty) result = JsonSerializer.Serialize(new { error = exception?.Message });

        return context.Response.WriteAsync(result);
    }
}

Finally, the custom-created error-handling middleware should be registered in the application pipeline configuration.
builder.UseMiddleware();

2. Adopting the Result Pattern

At the application layer, our approach significantly shifts as we adopt the Result pattern, utilizing the FluentResults NuGet package to enhance our error-handling strategy. This method alters the expected output of our commands from a simple GUID to a Result<Guid>. Such a transformation encapsulates the outcome of command execution within a structured result, offering more granular control over error handling, which neatly complies with our business logic requirements.

public class AddBankAccountCommand : IRequest<Result<Guid>>
{
    [Required] public string Name { get; set; } = string.Empty;

    [Required] public CurrencyCode CurrencyCode { get; set; }

    [Required] public Guid BankId { get; set; }
}

In implementing this pattern, the AddBankAccountCommandHandler in the Application layer plays a crucial role. It processes the creation requests and directly integrates error handling into the workflow using the Result pattern. This allows for immediate feedback on the operation's success or failure and the communication of specific error messages directly related to the business rules, enhancing user experience and system reliability.

using FluentResults;
using InWestMan.Assets.BankAccounts.Specifications;
using InWestMan.Repositories;
using MediatR;

namespace InWestMan.Assets.BankAccounts.Commands.AddBankAccount;

public class AddBankAccountCommandHandler : IRequestHandler<AddBankAccountCommand, Result<Guid>>
{
    private readonly IRepository<BankAccount> _repository;

    public AddBankAccountCommandHandler(IRepository<BankAccount> repository)
    {
        _repository = repository;
    }

    public async Task<Result<Guid>> Handle(AddBankAccountCommand request, CancellationToken cancellationToken)
    {
        try
        {
            var bankAccountByNameSpecification = new BankAccountByNameSpecification(request.Name);
            if (await _repository.AnyAsync(bankAccountByNameSpecification, cancellationToken))
                return Result.Fail("The bank account with the same name already exists.");

            var newBankAccount = new BankAccount(request.Name, request.BankId, request.CurrencyCode);

            await _repository.AddAsync(newBankAccount, cancellationToken);

            return Result.Ok(newBankAccount.Id);
        }
        catch (ArgumentException ex)
        {
            return Result.Fail(ex.Message);
        }
    }
}

Transitioning to the controller level, the Create Bank Account Controller method adapts to accommodate the Result pattern. Instead of merely returning a GUID, it now handles the Result object, facilitating a response mechanism that directly reflects the outcome of the command - either confirming successful account creation or detailing the reasons for failure.

    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesDefaultResponseType]
    public async Task<ActionResult<Guid>> Create([FromBody] CreateBankAccountDto createDto)
    {
        var command = _mapper.Map<AddBankAccountCommand>(createDto);
        var commandResult = await _mediator.Send(command);
        if (commandResult.IsFailed)
        {
            return BadRequest(commandResult.Errors);
        }

        return CreatedAtAction(nameof(GetById), new { id = commandResult.Value }, commandResult.Value );
    }

With the adoption of this comprehensive Result pattern, the necessity for custom exception-handling middleware diminishes. All potential exceptions and errors are addressed directly within the Application layer, obviating the need for middleware to catch and reformat exceptions. This results in a cleaner architecture that reduces overhead and enhances clarity and maintainability by localizing error handling within the context where it is most relevant.

Conclusion: Choosing the Error Handling Strategy

In software architecture, error-handling strategies are pivotal in defining the system's robustness and clarity. Comparing the two approaches discussed exception handling versus the application layer result reveals distinct advantages and considerations for each, informing their appropriate use cases.

API Layer: Middleware-Based

This approach centralizes error management in the middleware, abstracting it away from the business logic.

Pros:

Centralization of Error Handling: This method simplifies the control flow by managing exceptions centrally, making it easier to handle unanticipated errors uniformly across various application parts.
Simplicity in Implementation: Developers can implement and modify error-handling strategies without touching the business logic, promoting a cleaner separation of concerns.

Cons:

Potential for Overuse: There's a risk of using exceptions for control flow, which can lead to systems where exceptions are thrown for expected, non-exceptional conditions, potentially impacting performance.
Decreased Transparency: As exceptions bubble up to the middleware, it might obscure the source and context of errors, making debugging more challenging.

Use Cases:

It is ideal for applications requiring a uniform way to handle unanticipated or external system errors, such as failures in external services or database issues.

Application Layer: Result Pattern

Employing a result pattern at the application layer treats errors as expected outcomes, handled via types that explicitly represent success or failure.

Pros:

Enhanced Error Clarity: This approach treats errors as regular values, avoiding the pitfalls of exception handling for control flow and making error states explicit and predictable.
Better Alignment with Functional Principles: It promotes immutability and function purity, making the system easier to reason about and test.

Cons:

Increased Complexity: Requires more initial setup and can complicate the API with additional result-checking code.
Potential for Duplication: Handling errors explicitly in each function might lead to repetitive error handling code unless carefully managed.

Use Cases:

It is particularly suitable for domains where business rules are complex and errors are a regular, expected part of operations, such as financial applications or systems with complex input validation needs.

In conclusion, a project's requirements and constraints should guide the choice between these error-handling strategies. Middleware-based exception handling might be more appropriate for applications where unexpected errors from external systems dominate. In contrast, an application layer result pattern fits scenarios requiring fine-grained control over business rules and where mistakes are as informative as successful outcomes. Both approaches can coexist within a clean architecture, chosen based on different aspects or layers of the application to optimize clarity, maintainability, and functionality.

Original article on Medium

Stay tuned for more insights and detailed analyses, and feel free to share your thoughts or questions in the comments below!

SharpAssembly on Dev.to
SharpAssembly on Medium
SharpAssembly on Telegram

Cover credits: DALL·E generated

Step-by-step Guide to Implementing Multi-Tenancy in WebAPI Using ASP.NET Core Identity

Kostiantyn Bilous — Thu, 22 Feb 2024 05:34:23 +0000

Original article on Medium

Building web applications for financial services requires a keen focus on security and scalability. One key challenge is managing and protecting client data while serving multiple clients from a single application instance. Multi-tenancy offers a solution by allowing a single application to serve different clients, or "tenants," thereby keeping their data isolated and secure.

Implementing a multi-tenant model in ASP.NET Core, with ASP.NET Core Identity managing user authentication and authorization, requires specific steps that we will discuss below.

Multi-Tenancy: An Overview

Multi-tenancy is commonly seen in cloud computing and SaaS (Software as a Service) applications, enabling efficient resource utilization, simplified application management, and reduced operational costs. Multi-tenancy's complexity and implementation requirements vary depending on the application's needs.

Types of Multi-Tenancy

Single-Tenant Architecture: Each tenant has a dedicated instance of the software and underlying infrastructure. While not multi-tenancy in the strict sense, it's often discussed in contrast to actual multi-tenant architectures.
Separate Database: Tenants are separated into different databases with a single application instance. This keeps data separate and requires a new database environment for each new tenant.
Shared Database, Separate Schemas: Tenants share the same database but have their own schemas and tables. This keeps data separate but within the same database environment.
Shared Database, Shared Schema: The most complex form of multi-tenancy, where all tenants share the same database and schema. Tenant-specific identifiers differentiate data within the tables but require careful implementation to ensure data isolation.

Benefits of Multi-Tenancy

Cost Efficiency: Sharing resources among tenants helps reduce hardware and software costs.
Ease of Maintenance: Updates and patches must be applied to only one application instance, simplifying maintenance.
Scalability: Scaling a single application instance is more manageable than maintaining multiple instances for each tenant.
Resource Utilization: Multi-tenancy can result in more efficient resource use, as idle capacity can be reallocated.

Drawbacks of Multi-Tenancy

Complexity: Implementing a multi-tenant architecture, particularly ensuring data isolation and security, can be complex.
Performance Risks: Resource contention among tenants can impact performance.
Security Concerns: Maintaining data isolation when using shared resources requires strict security measures to prevent potential data leaks and meet regulatory requirements.
Customization Limitations: Providing deep customization options to tenants poses more challenges in a shared environment.

Practical example

Now, let's dive into a practical example from InWestMan, a software application for tracking personal investments that requires isolating sensitive client data to be accessible only to users who created them. In the example, we will add multitenancy support to ensure clients can access and manipulate only portfolios created by them. We will use the last multitenancy type, "Shared Database, Shared Schema," using ASP.NET Core Identity.

1. First, in our Infrastructure project, we switch to using ASP.NET Core Identity's DbContext, which includes all required identity models, by changing the inheritance of our AppDbContext from the basic Entity Framework's DbContext to IdentityDbContext.

public class AppDbContext : IdentityDbContext

2. Next, in our WebAPI project, we need to register the Identity service in the Program.cs file.

services.AddIdentity<IdentityUser, IdentityRole>()
            .AddEntityFrameworkStores<AppDbContext>();

3. Subsequently, in our Domain project, we add a TenantId property to Aggregate Roots, which, according to our domain model, are sensitive, for example, a Portfolio entity that stores the client's Positions.

public abstract class BaseEntityWithMultitenancy<TId>
{
    public List<BaseDomainEvent> Events = [];

    public string TenantId { get; set; } = string.Empty;

    public TId Id { get; set; } = default!;
}

public class Portfolio : BaseEntityWithMultitenancy<Guid>, IAggregateRoot
{
    public string Name { get; set; } = string.Empty;
    public ICollection<Position> Positions { get; set; } = new List<Position>();

    // other logic and sensitive fields...
}

4. Furthermore, in the Application project, we need to create MultiTenancyService that will keep a current tenant in the scope of the WebAPI call.

public interface IMultiTenancyService
{
    string CurrentTenant { get; }
    void SetCurrentTenant(string tenant);
}

public class MultiTenancyService : IMultiTenancyService
{
    private string _tenant = string.Empty;

    public string CurrentTenant
    {
        get => _tenant;
        private set
        {
            if (_tenant != value)
            {
                var oldTenant = _tenant;
                _tenant = value;
            }
        }
    }

    public void SetCurrentTenant(string tenant)
    {
        if (string.IsNullOrWhiteSpace(tenant))
            throw new ArgumentException("CurrentTenant cannot be null or whitespace.", nameof(tenant));
        CurrentTenant = tenant;
    }
}

5. It is crucial to remember to register the new MultiTenancyService in the service collection in the Program.cs file in the WebAPI project.

services.AddScoped(typeof(IMultiTenancyService), typeof(MultiTenancyService));

6. Now, let's return to our Application project. I utilize the MediatR's AddPortfolioCommand to add a new Portfolio to the database; therefore, I need to update my AddPortfolioHandler to include the client's tenant when saving the created entity. To achieve this, I pass an IMultiTenancyService instance to my AddPortfolioHandler class and explicitly assign the current TenantId to the newly created Portfolio object before saving.

public class AddPortfolioCommand : IRequest<Result<Guid>>
{
    public string Name { get; set; }
    public CurrencyCode CurrencyCode { get; set; }
}

public class AddPortfolioHandler : IRequestHandler<AddPortfolioCommand, Result<Guid>>
{
    private readonly IMultiTenancyService _multiTenancyService;
    private readonly IRepository<Portfolio> _repository;

    public AddPortfolioHandler(IRepository<Portfolio> repository,
        IMultiTenancyService multiTenancyService)
    {
        _repository = repository;
        _multiTenancyService = multiTenancyService;
    }

    public async Task<Result<Guid>> Handle(AddPortfolioCommand request, CancellationToken cancellationToken)
    {
        try
        {
            var portfolio = new Portfolio(request.Name, request.CurrencyCode);
            portfolio.TenantId = _multiTenancyService.CurrentTenant;

            await _repository.AddAsync(portfolio, cancellationToken);
            return Result.Ok(portfolio.Id);
        }
        catch (ArgumentException ex)
        {
            return Result.Fail<Guid>(ex.Message);
        }
    }
}

7. Returning to our Infrastructure project, we must ensure that the user will be provided only with data associated with her and only her tenancy. To achieve this, we add a global filter in AppDbContext for Portfolio entity into the overridden method OnModelCreating(). Additionally, we specify a new index based on the TenantId field to improve read query performance.

public class AppDbContext : IdentityDbContext
{
    private readonly IMultiTenancyService _multiTenancyService;

    public AppDbContext(DbContextOptions<AppDbContext> options,
        IMultiTenancyService multiTenancyService)
        : base(options)
    {
        _multiTenancyService = multiTenancyService;
    }

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

        modelBuilder.Entity<Portfolio>()
            .HasQueryFilter(b => b.TenantId == _multiTenancyService.CurrentTenant)
            .HasIndex(b => b.TenantId)
            .IsUnique(false);    
    }
}

8. Next, we switch to the WebAPI project, where it's necessary to read a tenancy claim from HTTP cookies and set the TenantId in MultiTenancyService using a specially created MultiTenancy middleware.

public class MultiTenancy
{
    private readonly RequestDelegate _next;

    public MultiTenancy(RequestDelegate next)
    {
        _next = next;
    }

    public async Task Invoke(HttpContext httpContext, IMultiTenancyService multiTenancyService)
    {
        var tenantId = DetermineTenant(httpContext);

        multiTenancyService.SetCurrentTenant(tenantId);

        await _next(httpContext);
    }

    private string DetermineTenant(HttpContext context)
    {
        var user = context.User;
        if (user.HasClaim(c => c.Type == "tenant"))
        {
            return user.FindFirst("tenant")?.Value ?? string.Empty;
        }

        return "default-tenant";
    }
}

9. Subsequently, we must incorporate our MultiTenancy middleware in the Program.cs file. It should be added after the authentication process, as we will read a TenantId from the authenticated user's HttpContext.

app.UseAuthentication();
app.UseAuthorization();
app.UseMiddleware<Middlewares.MultiTenancy>();
app.MapControllers();

10. Finally, we must ensure the TenantId is generated and stored as a Claim in the user's profile during the client registration process in the Authentication controller, and then returned to HTTP cookies upon successful authentication.

[HttpPost("Register")]
public async Task<IActionResult> Register([FromBody] UserDto model)
{
    if (ModelState.IsValid)
    {
        var user = new IdentityUser { UserName = model.Name, Email = model.Email };
        var result = await _userManager.CreateAsync(user, model.Password);

        if (result.Succeeded)
        {
            var tenantId = Guid.NewGuid().ToString();
            var tenantClaim = new Claim("tenant", tenantId);
            await _userManager.AddClaimAsync(user, tenantClaim);

            return Ok(new { message = "User registered successfully" });
        }

        foreach (var error in result.Errors)
        {
            ModelState.AddModelError(string.Empty, error.Description);
        }
    }

    return BadRequest(ModelState);
}

Conclusion

Implementing multi-tenancy in an ASP.NET Core WebAPI is a strategic approach to managing and protecting client data across multiple tenants within a single application instance. We explored the essential steps to set up a multi-tenant architecture using ASP.NET Core Identity and Entity Framework Core, ensuring data isolation and security while maintaining performance and scalability.

We've demonstrated how multi-tenancy can be achieved through a shared database and shared schema approach, leveraging ASP.NET Core Identity for user management and custom MultiTenancy middleware for tenant identification. Following the practical example, you can adapt these concepts for your projects, ensuring each client's data remains secure and isolated, even in a shared environment.

Multi-tenancy offers numerous benefits, including cost efficiency, ease of maintenance, and scalability, making it an attractive option for SaaS applications and services. However, it's crucial to be mindful of the potential complexities and security implications, planning your implementation carefully to avoid performance issues and ensure robust data protection.

Whether you're building a new application or enhancing an existing one, I hope the principles and practices outlined in this guide will help you navigate multi-tenancy challenges, enabling you to deliver a more flexible, secure, and scalable solution to your users.

Original article on Medium

Stay tuned for more insights and detailed analyses, and feel free to share your thoughts or questions in the comments below!

SharpAssembly on Dev.to
SharpAssembly on Medium
SharpAssembly on Telegram

Cover credits: DALL·E generated

Refactoring Currency: Mastering Universal Currency Value Objects with Enums and Attributes

Kostiantyn Bilous — Tue, 30 Jan 2024 21:16:14 +0000

Original article on Medium

Precision is paramount in financial software development, where even seemingly minor components can have major implications. Among these, the representation of Currency stands as a foundational element that demands meticulous attention. This article delves into the art of refining Currency representation within financial systems. By adopting Domain-Driven Design (DDD) principles, we'll explore how to transform Currency from a basic Entity into a well-defined Value Object. Discover how crafting robust and universal Currency Value Objects can subtly yet significantly enhance the clarity and reliability of financial applications.

Theoretical Underpinnings: Entities and Value Objects in Domain-Driven Design

In Domain-Driven Design (DDD), understanding the distinction between Entities and Value Objects is fundamental. Entities are defined by their identity, while Value Objects are characterized by their attributes. Often misconstrued as a mere attribute, Currency holds substantial complexity, primarily when interacting with different system parts. It could be misconceptually implemented as an Entity in the Bounded Context, where it naturally behaves as a Value Object.

Why Refactor Currency into a Value Object?

Immutability: Value Objects are immutable. This immutability aligns perfectly with the nature of the Currency, where the value shouldn't change once instantiated.
Validation and Consistency: Encapsulating the currency as a Value Object allows centralized validation and business rule enforcement, ensuring Currency consistency across the system.
Reduction of Complexity: Representing Currency as a Value Object simplifies operations, abstracting the intricacies of currency handling into well-defined methods.

Practical Application: The Refactoring Process

Let's dive into the practicalities using an example from the InWestMan application. This application is designed for personal investment tracking and uses Money as a Value Object.

Original Scenario: Currency as an Entity
Initially, the Currency in our system was an Entity laden with unnecessary complexity and potential for inconsistencies.

public class Currency : BaseEntity<int> 
{
    public string Code { get; set; }
    public string Name { get; set; }
    public int FractionDigits { get; set; }
}

This Currency is used in theMoney class, which is an Enterprise Pattern commonly used in Domain-Driven Design.

Link to Article on Money Patterns:
Money Patterns in Domain-Driven Design: Navigating the Complexities of Financial Systems

public sealed class Money : ValueObject
{
    private readonly decimal _amount;
    private readonly Currency _currency;

    public Money(decimal amount, Currency currency)
    {
        _amount = amount;
        _currency = currency;
    }

    public Currency Currency => _currency;

    public decimal Amount => decimal.Round(_amount, _currency.FractionDigits, MidpointRounding.ToEven);

    protected override IEnumerable<object> GetEqualityComponents()
    {
        yield return Amount;
        yield return Currency.Code;
    }

    // Methods
}

Refactoring Steps:
1. Defining the Immutable Enum: We define a new CurrencyCode enum (e.g. ISO 4217), encapsulating all relevant properties and behaviors in its attributes.

public enum CurrencyCode
{
    [EnumMember(Value = "USD")] 
    [Description("United States dollar")] 
    [FractionDigit(2)]
    USD = 840,

    [EnumMember(Value = "UAH")] 
    [Description("Ukrainian hryvnia")] 
    [FractionDigit(2)]
    UAH = 980,

    [EnumMember(Value = "EUR")] 
    [Description("Euro")] 
    [FractionDigit(2)]
    EUR = 978

    ...
}

2. Storing Data in Memory as Attributes: We ensure that instances of CurrencyCode contain all relevant data.

[AttributeUsage(AttributeTargets.Field)]
public class FractionDigitAttribute : Attribute
{
    public FractionDigitAttribute(int fractionDigit)
    {
        FractionDigit = fractionDigit;
    }

    public int FractionDigit { get; private set; }
}

3. Centralizing Business Logic: Currency-related data (like full name, fraction digits, etc.) are centralized within the CurrencyCode enum, promoting code reusability and maintainability by static extensions.

public static class CurrencyCodeExtensions
{
    public static int GetFractionDigit(this CurrencyCode currencyCode)
    {
        var type = currencyCode.GetType();
        var memInfo = type.GetMember(currencyCode.ToString());
        if (memInfo.Length > 0)
        {
            var attributes = memInfo[0].GetCustomAttributes(typeof(FractionDigitAttribute), false);
            if (attributes.Length > 0)
                return ((FractionDigitAttribute)attributes[0]).FractionDigit;
        }

        return 2;
    }
}

In the context of our Money class, the refactoring leads to more transparent, more concise operations:

public sealed class Money : ValueObject
{
    private readonly decimal _amount;
    private readonly CurrencyCode _currencyCode;
    private readonly int _fractionDigits;

    public Money(decimal amount, CurrencyCode currencyCode)
    {
        _amount = amount;
        _currencyCode = currencyCode;
        _fractionDigits = _currencyCode.GetFractionDigit();
    }

    public decimal Amount => decimal.Round(_amount, _fractionDigits, MidpointRounding.ToEven);

    public CurrencyCode CurrencyCode => _currencyCode;

    protected override IEnumerable<object> GetEqualityComponents()
    {
        yield return Amount;
        yield return CurrencyCode;
    }

    // Other methods 
}

Conclusion: The Strategic Impact of Refactoring

The transition from treating Currency as an Entity to a Value Object in financial software isn't merely a technical refactor but a strategic enhancement. It aligns the codebase with the principles of Domain-Driven Design, promoting clarity, consistency, and maintainability. This refactoring journey exemplifies how thoughtful changes in code structure can lead to more robust, reliable, and scalable financial systems.

Original article on Medium

Stay tuned for more insights and detailed analyses, and feel free to share your thoughts or questions in the comments below!

SharpAssembly on Dev.to
SharpAssembly on Medium
SharpAssembly on Telegram

Cover credits: DALL·E generated

Mastering Financial Complexity with Money Patterns in Domain-Driven Design

Kostiantyn Bilous — Sun, 28 Jan 2024 09:33:50 +0000

Original article on Medium

At first glance, finance appears straightforward: numbers on a screen, simple transfers, and account balances. Yet, this facade masks a realm of intricate operations. Each banking application keystroke or transaction culminates in complex, error-intolerant processes. Domain-driven design (DDD) emerges as a vital methodology in this complicated world, transforming convoluted financial tasks into well-organized, manageable solutions.

This post delves into how DDD's Money patterns untangle these complexities, offering practical strategies for handling and processing financial data in software systems and highlighting their indispensable role in crafting robust financial applications.

Theoretical Foundations: The Significance of Money in DDD

Domain-driven design meticulously models software to align with its intended domain. In financial systems, 'Money' isn't just a number; it's a pivotal concept. Treating it merely as a numerical value can spawn critical issues: rounding discrepancies and currency inconsistencies, which are unacceptable in precision-dependent financial software.

Key Principles:

Immutability: Money is often considered a Value Object within DDD. It's immutable, defined by characteristics (amount, currency) rather than an identity.
Precision and Scale: Financial computations require utmost precision. Money patterns cater to this need by utilizing precise data types like decimals and sidestepping rounding errors.
Currency Handling: Financial applications frequently deal with diverse currencies and conversions, necessitating robust currency management in the domain model.

Practical Implementation: Money in the Investment Sphere

Now, let's explore how these principles are applied in a real-world scenario, focusing on the investment sector. Venturing into the investment sector, consider the InWestMan application, a tool for personal investment monitoring. Here, precise representation and manipulation of monetary values are paramount.

Case Study: Portfolio Valuation

Envision a feature computing an investor's total portfolio worth. This entails aggregating the values of assorted assets, often in different currencies. The code snippet below illustrates this:

public sealed class Money : ValueObject
{
    public decimal Amount { get; }
    public Currency Currency { get; }

    public Money(decimal amount, Currency currency)
    {
        Amount = amount;
        Currency = currency;
    }

    public Money Add(Money other)
    {
        CheckSameCurrency(other);
        return new Money(this.Amount + other.Amount, this.Currency);
    }

    private void CheckSameCurrency(Money other) 
    {
        if (Currency != other.Currency) 
              throw new CurrencyMismatchException();
    }

    public static Money operator +(Money a, Money b) 
    {
        return a.Add(b);
    }

    // Additional operations for Money, such as subtraction, multiplication, etc., are also defined.
}

public class Portfolio : BaseEntity
{
    private List<Investment> Investments;

    public Money CalculateTotalValue()
    {
        Money totalValue = new Money(0, Currency.USD); // Assuming USD for simplicity
        foreach (var investment in Investments)
        {
            totalValue = totalValue + investment.CurrentValue;
        }
        return totalValue;
    }
}

In this code, Money is a Value Object with operations to guarantee secure financial computations. The Portfolio class employs Money to ascertain the collective value, adhering to domain rules like currency uniformity.

Conclusion: Strategic Benefits of Money Patterns in DDD

Incorporating Money Patterns into DDD offers a robust technical framework, providing a strategic lens for developing dependable, precise, and domain-focused financial software. By acknowledging the intricacies and importance of money, we can foster the development of scalable, trustworthy systems and ensure the precision of financial calculations.

Original article on Medium

Stay tuned for more insights and detailed analyses, and feel free to share your thoughts or questions in the comments below!

SharpAssembly on Medium
SharpAssembly on Telegram

Cover credits: DALL·E generated