Franz.Common.Business 1.4.4

Franz.Common.Business

A core library of the Franz Framework, designed to facilitate Domain-Driven Design (DDD) and CQRS (Command Query Responsibility Segregation) in .NET applications. It provides abstractions, utilities, and patterns for building scalable, maintainable, and testable business logic.

• Current Version: 1.4.3

Features

1. Domain-Driven Design (DDD) Building Blocks

• Entities: Represent unique objects identified by a primary key, with auditing + soft delete built-in.
• Value Objects: Immutable, equality-driven domain concepts.
• Enumerations: Strongly typed enums with behavior and metadata.
• Repositories: Interfaces for persistence (IAggregateRepository<TAggregateRoot>, IReadRepository<T>).

Entity Example:

public class Order : Entity<Guid>
{
    public string CustomerName { get; private set; }
    public decimal TotalAmount { get; private set; }

    public Order(Guid orderId, string customerName, decimal totalAmount)
    {
        Id = orderId;
        CustomerName = customerName;
        TotalAmount = totalAmount;
    }
}

Value Object Example:

public class Address : ValueObject
{
    public string Street { get; }
    public string City { get; }
    public string PostalCode { get; }

    public Address(string street, string city, string postalCode)
    {
        Street = street;
        City = city;
        PostalCode = postalCode;
    }

    protected override IEnumerable<object> GetEqualityComponents()
    {
        yield return Street;
        yield return City;
        yield return PostalCode;
    }
}

2. Aggregates (Event-Sourced)

🆕 Since 1.2.65, aggregates follow a strict event-driven model:

• Enforce consistency across related entities.
• State is modified only through events.
• Support replay via event sourcing.
• Always identified by Guid.

Example:

public class Product : EventSourcedAggregateRoot<ProductEvent>
{
    public string Name { get; private set; }
    public decimal Price { get; private set; }
    private readonly List<ProductReview> _reviews = new();
    public IReadOnlyCollection<ProductReview> Reviews => _reviews.AsReadOnly();

    public Product(Guid id, string name, decimal price) : base(id)
    {
        RaiseEvent(new ProductCreatedEvent(id, name, price));
    }

    public void UpdatePrice(decimal newPrice)
    {
        if (newPrice <= 0) throw new InvalidOperationException("Price must be positive.");
        RaiseEvent(new ProductPriceUpdatedEvent(Id, newPrice));
    }

    public void AddReview(string comment, int rating)
    {
        if (rating < 1 || rating > 5) throw new InvalidOperationException("Rating must be between 1 and 5.");
        RaiseEvent(new ProductReviewAddedEvent(Id, comment, rating));
    }

    public void Apply(ProductCreatedEvent @event) { Id = @event.ProductId; Name = @event.Name; Price = @event.Price; }
    public void Apply(ProductPriceUpdatedEvent @event) { Price = @event.NewPrice; }
    public void Apply(ProductReviewAddedEvent @event) { _reviews.Add(new ProductReview(@event.Comment, @event.Rating)); }
}

3. Events

Supports both domain events and integration events.

• IEvent
• IEventHandler<TEvent>
• IntegrationEvent
• BaseEvent

Example:

public class OrderCreatedEvent : IEvent
{
    public Guid OrderId { get; set; }
    public string CustomerName { get; set; }
}

public class OrderCreatedHandler : IEventHandler<OrderCreatedEvent>
{
    public async Task Handle(OrderCreatedEvent @event, CancellationToken cancellationToken)
    {
        Console.WriteLine($"Order created for {@event.CustomerName}.");
    }
}

4. CQRS Support

• Commands (ICommandRequest<T>, ICommandHandler<TCommand,TResponse>)
• Queries (IQueryRequest<T>, IQueryHandler<TQuery,TResponse>)

Command Example:

public class CreateOrderCommand : ICommandRequest<Guid>
{
    public string CustomerName { get; set; }
    public decimal TotalAmount { get; set; }
}

public class CreateOrderHandler : ICommandHandler<CreateOrderCommand, Guid>
{
    public async Task<Guid> Handle(CreateOrderCommand request, CancellationToken cancellationToken)
    {
        var orderId = Guid.NewGuid();
        Console.WriteLine($"Order created for {request.CustomerName} with ID: {orderId}");
        return orderId;
    }
}

5. Registration Examples

The Business layer integrates seamlessly with the Mediator and resilience pipelines.

a) AddBusinessWithMediator

Strict registration – will throw if your *.Application assembly is not found.

builder.Services.AddBusinessWithMediator(typeof(Program).Assembly);

b) TryAddBusinessWithMediator

Soft registration – logs a warning but continues if the application assembly is missing.

builder.Services.TryAddBusinessWithMediator(typeof(Program).Assembly);

c) AddFranzPlatform

Full-stack registration – Business + Mediator + Logging + Resilience pipelines.

builder.Services.AddFranzPlatform(
    typeof(Program).Assembly,
    options =>
    {
        options.DefaultTimeout = TimeSpan.FromSeconds(30);
    });

6. Resilience Pipelines (via Mediator)

When you call AddFranzPlatform, Franz.Common.Business wires up the following Mediator pipelines:

• ✅ RetryPipeline<TRequest, TResponse>
• ✅ CircuitBreakerPipeline<TRequest, TResponse>
• ✅ TimeoutPipeline<TRequest, TResponse>
• ✅ BulkheadPipeline<TRequest, TResponse>

These are implemented in Franz.Common.Mediator.Pipelines.Resilience. Franz.Common.Business just activates them for you.

7. appsettings.json Configuration

Each pipeline reads its Options from configuration:

{
  "Franz": {
    "Resilience": {
      "Retry": {
        "Enabled": true,
        "RetryCount": 3,
        "BaseDelayMilliseconds": 200
      },
      "CircuitBreaker": {
        "Enabled": true,
        "FailureThreshold": 5,
        "OpenDurationSeconds": 60
      },
      "Timeout": {
        "Enabled": true,
        "TimeoutSeconds": 15
      },
      "Bulkhead": {
        "Enabled": true,
        "MaxParallelization": 50,
        "MaxQueuingActions": 100
      }
    }
  }
}

8. Options Mapping

• Retry → RetryOptions
• CircuitBreaker → CircuitBreakerOptions
• Timeout → TimeoutOptions
• Bulkhead → BulkheadOptions

9. Logging

On startup you’ll see log messages confirming bootstrap:

[INF] ✅ Franz.Business bootstrapped with MyProduct.Application, Version=1.0.0.0
[INF] 🛡️ Resilience pipelines registered: Retry, CircuitBreaker, Timeout, Bulkhead
[WRN] ⚠️ No Application assembly found for MyProduct.Application, Business layer not registered.

What’s New in 1.4.2

• 🗑️ Removed SaveEntitiesAsync → all auditing + domain event dispatching happens in SaveChangesAsync.
• ✅ Aligned with DbContextBase from Franz.Common.EntityFramework.
• 🧹 Internal cleanup and consistency improvements.

Dependencies

• Scrutor (4.2.2) – assembly scanning & DI.
• Microsoft.Extensions.DependencyInjection (9.0.0) – DI support.
• Franz.Common.Mediator – CQRS + pipelines.
• Franz.Common.Errors – standardized error handling.

Installation

dotnet add package Franz.Common.Business --version 1.4.2

⚠️ Since 1.4.1, MediatR is no longer required. Uses Franz.Common.Mediator internally.

Contributing

This package is part of the private Franz Framework.

1. Clone repo.
2. Create a feature branch.
3. Submit a PR for review.

License

Licensed under the MIT License.

Changelog

1.4.2

• Removed SaveEntitiesAsync → replaced with SaveChangesAsync in DbContextBase.
• Improved alignment with EntityFramework package (auditing + domain events).

1.4.1

• Independent from MediatR → runs on Franz.Common.Mediator.
• Lifecycle tracking for entities & aggregates.
• Stronger value object equality.
• Enriched domain events with metadata.
• Scrutor-powered DI auto-discovery.

1.3

• Upgraded to .NET 9.
• Compatible with both in-house mediator & MediatR.

1.2.65

• Aggregates redesigned to use event sourcing.
• All aggregates now require Guid identifiers.