.NET Architecture at Scale: Visual Guide to Modern Design Patterns#
⚡ Performance Note: This article contains 16 comprehensive patterns with visual diagrams. For faster loading, consider bookmarking specific sections or using the “Find in Page” (Ctrl+F) feature to jump to relevant patterns.
The landscape of .NET architecture has evolved dramatically with .Net and Azure’s latest services, creating unprecedented opportunities for building scalable, resilient applications. Modern enterprises face complex challenges: distributed systems that must handle millions of transactions, microservices that need seamless communication, and legacy systems requiring careful modernization.
This comprehensive visual guide explores 16 essential architectural patterns through workflow diagrams, decision trees, and interaction flows that help architects make informed decisions about system design using the latest .NET ecosystem.
Table of Contents#
- Foundational Architecture Patterns
- Advanced Communication Patterns
- Service Integration Patterns
- Resilience and Data Patterns
- Modern .NET and Azure Integration
- Deployment and Infrastructure Patterns
- Comprehensive Pattern Selection Guide
- Best Practices for Implementation
Comprehensive Pattern Selection Guide#
This section provides both interactive decision flows and detailed comparison matrices to help you choose optimal architectural patterns for your .NET applications.
Interactive Decision Flow#
Start your architectural journey with this decision tree to identify the most suitable patterns for your specific requirements:
Complexity vs. Benefit Analysis#
⭐⭐⭐⭐⭐] L2[API Gateway
⭐⭐⭐⭐] L3[Circuit Breaker
⭐⭐⭐⭐] end subgraph "Medium Complexity" M1[Hexagonal Architecture
⭐⭐⭐] M2[CQRS
⭐⭐⭐] M3[BFF
⭐⭐⭐] M4[Serverless
⭐⭐⭐] end subgraph "High Complexity" H1[Onion Architecture
⭐⭐] H2[Event Sourcing
⭐⭐] H3[Saga Pattern
⭐⭐] H4[Strangler Fig
⭐⭐] end style L1 fill:#c8e6c9 style L2 fill:#c8e6c9 style L3 fill:#c8e6c9 style M1 fill:#fff3e0 style M2 fill:#fff3e0 style M3 fill:#fff3e0 style M4 fill:#fff3e0 style H1 fill:#ffcdd2 style H2 fill:#ffcdd2 style H3 fill:#ffcdd2 style H4 fill:#ffcdd2
Comprehensive Pattern Comparison Matrix#
| Pattern | Team Skill Level | Setup Time | Maintenance | Scalability | Testability | Use Case Fit |
|---|---|---|---|---|---|---|
| Layered | Beginner | Fast | Low | Medium | Medium | CRUD Apps |
| Hexagonal | Intermediate | Medium | Medium | High | Very High | Clean Architecture |
| Onion | Advanced | Slow | High | Very High | Very High | Enterprise DDD |
| CQRS | Intermediate | Medium | Medium | Very High | High | Read/Write Split |
| Event-Driven | Advanced | Slow | High | Very High | Medium | Real-time Systems |
| Saga | Expert | Very Slow | Very High | High | Medium | Distributed Transactions |
| API Gateway | Beginner | Fast | Low | Very High | Medium | Microservices |
| BFF | Intermediate | Medium | Medium | High | High | Multi-client Apps |
| Serverless | Intermediate | Fast | Low | Auto | Medium | Event Processing |
| Strangler Fig | Advanced | Variable | High | High | Medium | Legacy Migration |
| Circuit Breaker | Beginner | Fast | Low | Medium | High | Fault Tolerance |
| Outbox | Intermediate | Medium | Medium | High | Medium | Message Reliability |
| Sidecar | Intermediate | Medium | Medium | High | Medium | Cross-cutting Concerns |
| Ambassador | Advanced | Medium | High | High | Medium | Service Proxy |
| Bulkhead | Advanced | Slow | High | Very High | Medium | Resource Isolation |
| Event Sourcing | Expert | Very Slow | Very High | High | Medium | Audit Trail |
Quick Selection Guide#
Architectural Pattern Categories#
Understanding pattern relationships helps in making informed architectural decisions:
Foundational Architecture Patterns#
Layered Architecture#
Layered Architecture remains the most familiar pattern for .NET developers, organizing applications into horizontal layers with clear separation of concerns. While simpler than modern alternatives, it provides an excellent foundation for understanding architectural principles.
Architecture Flow#
Controllers, Views, APIs] --> B[Business Logic Layer
Services, Domain Logic] B --> C[Data Access Layer
Repositories, ORM, DAL] C --> D[Database Layer
SQL Server, Entity Framework] style A fill:#e1f5fe style B fill:#f3e5f5 style C fill:#e8f5e8 style D fill:#fff3e0
Request Processing Flow#
When to Use Decision Tree#
Best for: CRUD applications, rapid prototyping, small teams, learning projects.
Benefits: Familiarity, simplicity, quick development cycles.
Challenges: Tight coupling between layers, difficulty in testing, scalability limitations.
Implementation Example#
// Business Logic Layer - Service
public class ProductService : IProductService
{
private readonly IProductRepository _productRepository;
public ProductService(IProductRepository productRepository)
{
_productRepository = productRepository;
}
public async Task<IEnumerable<Product>> GetAllProductsAsync()
{
return await _productRepository.GetAllAsync();
}
public async Task<Product> CreateProductAsync(CreateProductRequest request)
{
var product = new Product
{
Name = request.Name,
Price = request.Price,
CreatedAt = DateTime.UtcNow
};
return await _productRepository.CreateAsync(product);
}
}
// Data Access Layer - Repository
public class ProductRepository : IProductRepository
{
private readonly AppDbContext _context;
public ProductRepository(AppDbContext context)
{
_context = context;
}
public async Task<IEnumerable<Product>> GetAllAsync()
{
return await _context.Products.ToListAsync();
}
public async Task<Product> CreateAsync(Product product)
{
_context.Products.Add(product);
await _context.SaveChangesAsync();
return product;
}
}When to use: Simple to medium-complexity applications, traditional enterprise systems, rapid prototyping, or when working with junior developers.
Advantages include: Simplicity, familiarity, and quick development cycles.
Disadvantages include: Tight coupling, testing challenges, and database-centric design that can hinder flexibility.
Hexagonal Architecture#
Hexagonal Architecture, also known as Ports and Adapters, isolates core business logic from external concerns through well-defined interfaces. This pattern excels when technology independence and testability are paramount.
Architecture Structure#
Business Logic] end subgraph "Ports" P2[Outbound Interfaces] end subgraph "Secondary Adapters" S1[Database] S2[Email Service] S3[External APIs] end A1 --> P1 A2 --> P1 A3 --> P1 P1 --> AC AC --> P2 P2 --> S1 P2 --> S2 P2 --> S3 style AC fill:#ffeb3b style P1 fill:#e3f2fd style P2 fill:#e3f2fd
Dependency Flow#
Testing Strategy#
✓ Fast ✓ Isolated] B --> B2[Use Cases
✓ Mock Adapters] C --> C1[Adapter Tests
✓ Real Infrastructure] C --> C2[Port Tests
✓ Contract Validation] D --> D1[End-to-End
✓ Full System] style B1 fill:#c8e6c9 style B2 fill:#c8e6c9 style C1 fill:#fff3e0 style C2 fill:#fff3e0 style D1 fill:#ffcdd2
Implementation Guidelines#
// Core Contracts - Keep Minimal
public interface IProductRepository
{
Task<Product> GetByIdAsync(int id);
Task<Product> SaveAsync(Product product);
}
public interface IProductService
{
Task<ProductDto> CreateProductAsync(CreateProductRequest request);
}Best for: Applications requiring high testability, technology independence, or complex business logic.
Benefits: Technology agnostic, highly testable, clean dependencies.
Challenges: Initial complexity, learning curve, potential over-engineering for simple applications.
Implementation Example#
// Port - Interface defined by business needs
public interface IProductRepository
{
Task<Product> GetByIdAsync(int id);
Task<IEnumerable<Product>> GetAllAsync();
Task<Product> SaveAsync(Product product);
}
// Application Service - Orchestrates business logic
public class ProductService
{
private readonly IProductRepository _productRepository;
private readonly INotificationService _notificationService;
public ProductService(IProductRepository productRepository,
INotificationService notificationService)
{
_productRepository = productRepository;
_notificationService = notificationService;
}
public async Task<Product> CreateProductAsync(string name, decimal price)
{
var product = new Product(name, price);
var savedProduct = await _productRepository.SaveAsync(product);
await _notificationService.SendProductCreatedNotificationAsync(savedProduct);
return savedProduct;
}
}When to use: Complex business logic applications, systems requiring high testability, applications with multiple interfaces, or systems with frequently changing external dependencies.
Advantages include: Technology independence, high testability, and maintainability.
Disadvantages include: Increased complexity and potential over-engineering for simple applications.
Onion Architecture#
Onion Architecture builds upon Hexagonal principles with explicit concentric layers, placing domain logic at the center and ensuring dependencies flow inward. This pattern excels for enterprise applications with complex business rules.
Concentric Layer Structure#
Dependency Flow Rules#
✓ Pure Business Logic
✓ Domain Events] C --> C1[✓ Depends on Domain Only
✓ Use Cases & Services
✓ Interface Definitions] D --> D1[✓ Implements Interfaces
✓ External Concerns
✓ Data Access & APIs] E --> E1[✓ Depends on Application
✓ User Interface
✓ Controllers & Views] style B1 fill:#ffeb3b style C1 fill:#e3f2fd style D1 fill:#f3e5f5 style E1 fill:#e8f5e8
Use Case Flow#
remains isolated
Project Structure Guidelines#
Property.Management.Domain/
├── Entities/
├── ValueObjects/
├── DomainServices/
└── Events/
Property.Management.Application/
├── UseCases/
├── Services/
├── DTOs/
└── Interfaces/
Property.Management.Infrastructure/
├── Persistence/
├── ExternalServices/
└── Configuration/
Property.Management.Presentation/
├── Controllers/
├── Models/
└── Views/Best for: Enterprise applications with complex business rules, Domain-Driven Design implementations, long-term maintainable systems.
Benefits: Clear separation of concerns, testable architecture, business logic isolation.
Challenges: Initial setup complexity, learning curve for teams new to DDD.
Implementation Example#
// Domain Layer - Rich domain model
public class Order
{
private readonly List<OrderItem> _items = new();
public int Id { get; private set; }
public string CustomerName { get; private set; }
public DateTime OrderDate { get; private set; }
public OrderStatus Status { get; private set; }
public decimal TotalAmount => _items.Sum(i => i.Price * i.Quantity);
public Order(string customerName)
{
OrderDate = DateTime.UtcNow;
Status = OrderStatus.Draft;
}
public void AddItem(string productName, decimal price, int quantity)
{
if (Status != OrderStatus.Draft)
throw new InvalidOperationException("Cannot modify confirmed order");
_items.Add(new OrderItem(productName, price, quantity));
}
public void ConfirmOrder()
{
if (!_items.Any())
throw new InvalidOperationException("Cannot confirm empty order");
if (Status != OrderStatus.Draft)
throw new InvalidOperationException("Order already confirmed");
Status = OrderStatus.Confirmed;
}
}
// Application Layer - Use cases
public class OrderService : IOrderService
{
private readonly IOrderRepository _orderRepository;
private readonly IEmailService _emailService;
public OrderService(IOrderRepository orderRepository, IEmailService emailService)
{
_orderRepository = orderRepository;
_emailService = emailService;
}
public async Task<OrderDto> CreateOrderAsync(CreateOrderRequest request)
{
var order = new Order(request.CustomerName);
var savedOrder = await _orderRepository.SaveAsync(order);
return new OrderDto
{
Id = savedOrder.Id,
CustomerName = savedOrder.CustomerName,
OrderDate = savedOrder.OrderDate,
Status = savedOrder.Status.ToString(),
TotalAmount = savedOrder.TotalAmount
};
}
public async Task<OrderDto> ConfirmOrderAsync(int orderId)
{
var order = await _orderRepository.GetByIdAsync(orderId);
if (order == null)
throw new ArgumentException("Order not found");
order.ConfirmOrder();
var confirmedOrder = await _orderRepository.SaveAsync(order);
await _emailService.SendOrderConfirmationAsync(confirmedOrder);
return MapToDto(confirmedOrder);
}
}When to use: Enterprise applications with complex business rules, Domain-Driven Design implementations, or long-term software projects requiring high maintainability.
Advantages include: Domain-centric design, high testability, and clear structure.
Disadvantages include: Complexity and potential over-engineering for simple applications.
Advanced Communication Patterns#
CQRS (Command Query Responsibility Segregation)#
Command Query Responsibility Segregation (CQRS) separates read and write operations, allowing independent optimization of each concern. This pattern enables different models for reading and writing data.
Architecture Overview#
Decision Flow for CQRS#
Same Database] D -->|High| F{Consistency Requirements?} F -->|Eventual OK| G[CQRS + Event Sourcing] F -->|Strong Required| H[CQRS + Saga Pattern] E --> I[MediatR Implementation] G --> J[Separate Read/Write Stores] H --> K[Distributed Transactions] style C fill:#ffcdd2 style I fill:#c8e6c9 style J fill:#c8e6c9 style K fill:#fff3e0
Message Flow Patterns#
Implementation Strategy#
✓ Command/Query Handlers
✓ Same Database] C --> C1[✓ Write Models
✓ Read Models
✓ Event Publishing] D --> D1[✓ Write Database
✓ Read Database
✓ Event Sourcing] style B1 fill:#c8e6c9 style C1 fill:#fff3e0 style D1 fill:#ffcdd2
Core Contracts#
// Keep contracts minimal and focused
public interface ICommand<TResult> : IRequest<TResult> { }
public interface IQuery<TResult> : IRequest<TResult> { }
// Example command
public record CreateOrderCommand(string CustomerId, List<OrderItem> Items) : ICommand<int>;
// Example query
public record GetOrderQuery(int OrderId) : IQuery<OrderDto>;Best for: Applications with different read/write patterns, high-scale systems, complex reporting requirements.
Benefits: Independent scaling, optimized data models, clear separation.
Challenges: Increased complexity, eventual consistency, debugging across models.
Implementation Example#
// Controllers using MediatR
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
private readonly IMediator _mediator;
public ProductsController(IMediator mediator)
{
_mediator = mediator;
}
[HttpPost]
public async Task<IActionResult> CreateProduct([FromBody] CreateProductCommand command)
{
var productId = await _mediator.Send(command);
return CreatedAtAction(nameof(GetProduct), new { id = productId }, productId);
}
[HttpGet("{id}")]
public async Task<IActionResult> GetProduct(int id)
{
var product = await _mediator.Send(new GetProductByIdQuery(id));
return Ok(product);
}
}CQRS Benefits: Independent scaling of read and write operations, optimized data models for specific use cases, and reduced contention.
Challenges include: Increased complexity, eventual consistency, and additional infrastructure requirements.
Event-Driven Architecture#
Event-Driven Architecture enables loose coupling between components through asynchronous message passing, allowing systems to scale independently and react to business events in real-time.
Event Flow Architecture#
Azure Service Bus / RabbitMQ] end subgraph "Event Consumers" EC1[Email Service] EC2[Analytics Service] EC3[Audit Service] end EP1 --> EB EP2 --> EB EP3 --> EB EB --> EC1 EB --> EC2 EB --> EC3 style EB fill:#ffeb3b style EP1 fill:#ffcdd2 style EP2 fill:#ffcdd2 style EP3 fill:#ffcdd2 style EC1 fill:#c8e6c9 style EC2 fill:#c8e6c9 style EC3 fill:#c8e6c9
Event Processing Patterns#
✓ Services React to Events
✓ No Central Coordinator] C --> C1[✓ Central Coordinator
✓ Workflow Management
✓ Explicit Process Control] B1 --> B2[Pro: Loose Coupling
Con: Hard to Debug] C1 --> C2[Pro: Clear Flow
Con: Central Point of Failure] style B1 fill:#c8e6c9 style C1 fill:#fff3e0
Event Consistency Patterns#
Implementation Approach#
// Minimal event contract
public record OrderCreatedEvent(
int OrderId,
string CustomerId,
decimal Amount,
DateTime CreatedAt);
// Event handler interface
public interface IEventHandler<in TEvent>
{
Task HandleAsync(TEvent eventData);
}Best for: Microservices communication, real-time systems, scalable architectures.
Benefits: Loose coupling, scalability, resilience.
Challenges: Debugging complexity, eventual consistency, monitoring requirements.
Implementation Example#
// Command Handler using MediatR
public class CreateOrderCommandHandler : IRequestHandler<CreateOrderCommand, int>
{
private readonly IOrderRepository _orderRepository;
private readonly IMediator _mediator;
public async Task<int> Handle(CreateOrderCommand request, CancellationToken cancellationToken)
{
var order = new Order(request.CustomerId, request.Items);
await _orderRepository.SaveAsync(order);
// Publish domain event
await _mediator.Publish(new OrderCreatedEvent
{
OrderId = order.Id,
CustomerId = request.CustomerId,
Items = request.Items,
TotalAmount = order.TotalAmount
}, cancellationToken);
return order.Id;
}
}
}
}
// Event Handlers
public class InventoryEventHandler : INotificationHandler<OrderCreatedEvent>
{
private readonly IInventoryService _inventoryService;
public async Task Handle(OrderCreatedEvent notification, CancellationToken cancellationToken)
{
foreach (var item in notification.Items)
{
await _inventoryService.ReserveInventoryAsync(item.ProductId, item.Quantity);
}
}
}
public class EmailNotificationHandler : INotificationHandler<OrderCreatedEvent>
{
private readonly IEmailService _emailService;
public async Task Handle(OrderCreatedEvent notification, CancellationToken cancellationToken)
{
await _emailService.SendOrderConfirmationAsync(
notification.CustomerId,
notification.OrderId);
}
}When to use: E-commerce platforms with order processing workflows, IoT applications processing sensor data, real-time analytics systems, or microservices communication.
Advantages include: Loose coupling, fault tolerance, and horizontal scalability.
Disadvantages include: Debugging complexity, message ordering, and monitoring requirements.
Saga Pattern#
The Saga Pattern manages distributed transactions across multiple microservices by coordinating a sequence of local transactions with compensating actions for rollback scenarios.
Implementation Example#
// Saga State Machine
public class OrderProcessingSaga
{
public string OrderId { get; set; }
public string CustomerId { get; set; }
public decimal Amount { get; set; }
public SagaState State { get; set; }
public List<string> CompletedSteps { get; set; } = new();
public enum SagaState
{
Started,
PaymentProcessed,
InventoryReserved,
OrderConfirmed,
Failed,
Compensating
}
}
// Saga Orchestrator
public class OrderSagaOrchestrator
{
private readonly IMediator _mediator;
private readonly ISagaRepository _sagaRepository;
public async Task HandleOrderCreatedAsync(OrderCreatedEvent orderCreated)
{
var saga = new OrderProcessingSaga
{
OrderId = orderCreated.OrderId.ToString(),
CustomerId = orderCreated.CustomerId,
Amount = orderCreated.TotalAmount,
State = OrderProcessingSaga.SagaState.Started
};
await _sagaRepository.SaveAsync(saga);
// Start the saga by processing payment
await _mediator.Send(new ProcessPaymentCommand(
saga.OrderId,
saga.CustomerId,
saga.Amount));
}
public async Task HandlePaymentProcessedAsync(PaymentProcessedEvent paymentProcessed)
{
var saga = await _sagaRepository.GetByOrderIdAsync(paymentProcessed.OrderId);
saga.State = OrderProcessingSaga.SagaState.PaymentProcessed;
saga.CompletedSteps.Add("Payment");
await _sagaRepository.UpdateAsync(saga);
// Next step: Reserve inventory
await _mediator.Send(new ReserveInventoryCommand(
saga.OrderId,
paymentProcessed.Items));
}
public async Task HandleStepFailedAsync(SagaStepFailedEvent stepFailed)
{
var saga = await _sagaRepository.GetByOrderIdAsync(stepFailed.OrderId);
saga.State = OrderProcessingSaga.SagaState.Compensating;
await _sagaRepository.UpdateAsync(saga);
// Execute compensating transactions in reverse order
await ExecuteCompensatingTransactionsAsync(saga);
}
private async Task ExecuteCompensatingTransactionsAsync(OrderProcessingSaga saga)
{
var completedSteps = saga.CompletedSteps.AsEnumerable().Reverse();
foreach (var step in completedSteps)
{
switch (step)
{
case "Inventory":
await _mediator.Send(new ReleaseInventoryCommand(saga.OrderId));
break;
case "Payment":
await _mediator.Send(new RefundPaymentCommand(saga.OrderId, saga.Amount));
break;
}
}
saga.State = OrderProcessingSaga.SagaState.Failed;
await _sagaRepository.UpdateAsync(saga);
}
}Saga Pattern Benefits: Data consistency without distributed transactions, better error handling, and improved system resilience.
Challenges include: Increased complexity, debugging difficulties, and compensation logic complexity.
Service Integration Patterns#
API Gateway#
The API Gateway Pattern provides a single entry point for clients to access multiple backend services, commonly implemented using Azure API Management or Azure Application Gateway.
Azure API Management Configuration#
// Rate limiting policy
@{
return context.Request.IpAddress == "192.168.1.1" ? 1000 : 100;
}
// Route based on User-Agent
@{
return context.Request.Headers.GetValueOrDefault("User-Agent", "").Contains("Mobile")
? "mobile-backend"
: "web-backend";
}API Gateway Features: Layer 7 routing, authentication and authorization, rate limiting, request/response transformation, caching, and monitoring integration. Azure API Management offers different tiers including Consumption (serverless), Developer, Basic, Standard, and Premium, each with varying features and pricing models.
When to use: E-commerce platforms routing requests to catalog, inventory, and payment services; multi-tenant applications requiring tenant-based routing; or API versioning scenarios.
Advantages include: Reduced latency through caching, cost efficiency, and centralized infrastructure management.
Disadvantages include: Potential single point of failure and performance bottlenecks.
Backend for Frontend (BFF)#
The Backend for Frontend (BFF) Pattern creates dedicated backend services for specific frontend applications or interfaces, optimizing each backend for particular client needs rather than using a single general-purpose API.
Implementation Example#
// Mobile BFF Service
[ApiController]
[Route("api/mobile/[controller]")]
public class MobileProductController : ControllerBase
{
private readonly IProductService _productService;
private readonly IImageService _imageService;
[HttpGet("{id}")]
public async Task<MobileProductDto> GetProduct(int id)
{
var product = await _productService.GetByIdAsync(id);
// Mobile-specific optimization: smaller images, essential data only
return new MobileProductDto
{
Id = product.Id,
Name = product.Name,
Price = product.Price,
ThumbnailUrl = await _imageService.GetThumbnailAsync(product.ImageUrl, "mobile"),
Rating = product.AverageRating,
InStock = product.StockLevel > 0
};
}
}
// Web BFF Service
[ApiController]
[Route("api/web/[controller]")]
public class WebProductController : ControllerBase
{
private readonly IProductService _productService;
private readonly IReviewService _reviewService;
[HttpGet("{id}")]
public async Task<WebProductDto> GetProduct(int id)
{
var product = await _productService.GetByIdAsync(id);
var reviews = await _reviewService.GetRecentReviewsAsync(id, 10);
// Web-specific: full data with reviews, recommendations
return new WebProductDto
{
Id = product.Id,
Name = product.Name,
Description = product.Description,
Price = product.Price,
ImageUrls = product.ImageUrls,
Specifications = product.Specifications,
Reviews = reviews,
StockLevel = product.StockLevel,
EstimatedDelivery = CalculateDeliveryDate(product)
};
}
}When to use: Multi-platform applications (web, mobile, IoT), different client requirements, or API versioning scenarios.
Advantages include: Optimized data transfer, client-specific optimizations, and independent evolution.
Disadvantages include: Code duplication, increased infrastructure complexity, and additional maintenance overhead.
Serverless Pattern#
The Serverless Pattern enables event-driven, scalable applications using Azure Functions with .NET, supporting various hosting models and orchestration patterns.
Implementation Example#
// .NET Isolated Worker Model
[Function("ProcessOrder")]
public async Task<IActionResult> ProcessOrder(
[HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req,
[CosmosDBOutput("OrdersDB", "Orders", Connection = "CosmosDB")] IAsyncCollector<Order> orders)
{
var order = await req.ReadFromJsonAsync<Order>();
await orders.AddAsync(order);
return new OkObjectResult(new { OrderId = order.Id, Status = "Processing" });
}
// Durable Functions Orchestration
[Function("OrderProcessingOrchestrator")]
public async Task<string> RunOrchestrator(
[OrchestrationTrigger] IDurableOrchestrationContext context)
{
var order = context.GetInput<Order>();
// Function chaining pattern
await context.CallActivityAsync("ValidateOrder", order);
await context.CallActivityAsync("ProcessPayment", order);
await context.CallActivityAsync("UpdateInventory", order);
await context.CallActivityAsync("ShipOrder", order);
return "Order processed successfully";
}Serverless Benefits: Automatic scaling, pay-per-execution pricing, and reduced operational overhead.
Challenges include: Cold starts, execution time limits, and vendor lock-in considerations.
Strangler Fig Pattern#
The Strangler Fig Pattern enables incremental modernization of legacy systems by gradually replacing functionality while maintaining operational continuity.
Implementation Example#
// Routing Facade Implementation
public class StranglerFacade : IHostedService
{
private readonly IServiceProvider _serviceProvider;
private readonly IConfiguration _configuration;
public async Task RouteRequest(HttpContext context)
{
var feature = DetermineFeature(context.Request.Path);
if (IsModernizedFeature(feature))
{
await RouteToModernService(context, feature);
}
else
{
await RouteToLegacySystem(context);
}
}
private bool IsModernizedFeature(string feature)
{
return _configuration.GetValue<bool>($"Features:{feature}:Modernized");
}
private async Task RouteToModernService(HttpContext context, string feature)
{
// Route to new microservice
var modernServiceUrl = _configuration[$"Services:{feature}:Url"];
// Implementation details...
}
private async Task RouteToLegacySystem(HttpContext context)
{
// Route to legacy system
var legacyUrl = _configuration["LegacySystem:BaseUrl"];
// Implementation details...
}
}Strangler Fig Implementation phases: Establish facade, incremental migration, data migration, and legacy retirement.
Advantages include: Reduced risk, continuous operation, and flexible timeline.
Disadvantages include: Complexity of managing two systems and maintaining data consistency.
Resilience and Data Patterns#
Circuit Breaker Pattern: Fault Tolerance#
The Circuit Breaker Pattern prevents cascading failures by monitoring service health and failing fast when dependencies are unhealthy, like an electrical circuit breaker.
Circuit Breaker State Flow#
Requests Pass Through
Monitor Failures Open: Circuit Tripped
Fail Fast
No Requests Allowed HalfOpen: Testing Recovery
Limited Test Requests
Evaluate Health note right of Closed Success Rate > Threshold Reset Failure Counter end note note right of Open Immediate Rejection Resource Protection Wait for Recovery end note note right of HalfOpen Single Test Request Quick Failure Detection Gradual Recovery end note
Implementation Example#
// Modern .Net Implementation
services.AddHttpClient<PaymentService>()
.AddStandardResilienceHandler(options =>
{
options.CircuitBreaker.FailureRatio = 0.5;
options.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(10);
options.CircuitBreaker.MinimumThroughput = 8;
options.CircuitBreaker.BreakDuration = TimeSpan.FromSeconds(30);
});
// Custom Circuit Breaker with Polly v8
var circuitBreakerOptions = new CircuitBreakerStrategyOptions
{
FailureRatio = 0.5,
SamplingDuration = TimeSpan.FromSeconds(10),
MinimumThroughput = 8,
BreakDuration = TimeSpan.FromSeconds(30),
ShouldHandle = new PredicateBuilder()
.Handle<HttpRequestException>()
.Handle<TimeoutRejectedException>()
.HandleResult<HttpResponseMessage>(r => !r.IsSuccessStatusCode)
};
var resiliencePipeline = new ResiliencePipelineBuilder()
.AddCircuitBreaker(circuitBreakerOptions)
.Build();Circuit Breaker States: Closed (normal operation), Open (circuit tripped), and Half-Open (testing recovery).
Advantages include: Preventing cascading failures, resource conservation, and improved user experience.
Disadvantages include: Configuration complexity and potential false positives.
Outbox Pattern: Reliable Message Delivery#
The Outbox Pattern ensures reliable message delivery by storing outbound messages in the same database transaction as business data, then publishing them asynchronously.
Outbox Pattern Flow#
At-least-once semantics
Outbox Table Structure#
Implementation Example#
// Outbox Event Entity
public class OutboxEvent
{
public Guid Id { get; set; }
public string Type { get; set; }
public string Data { get; set; }
public DateTime CreatedAt { get; set; }
public bool IsProcessed { get; set; }
public DateTime? ProcessedAt { get; set; }
}
// Service Implementation
public class OrderService
{
private readonly ApplicationDbContext _context;
public async Task CreateOrderAsync(Order order)
{
using var transaction = await _context.Database.BeginTransactionAsync();
try
{
// Save business data
_context.Orders.Add(order);
// Save outbox event
var outboxEvent = new OutboxEvent
{
Id = Guid.NewGuid(),
Type = "OrderCreated",
Data = JsonSerializer.Serialize(new OrderCreatedEvent(order.Id)),
CreatedAt = DateTime.UtcNow,
IsProcessed = false
};
_context.OutboxEvents.Add(outboxEvent);
await _context.SaveChangesAsync();
await transaction.CommitAsync();
}
catch
{
await transaction.RollbackAsync();
throw;
}
}
}
// Outbox Processor
public class OutboxProcessor : BackgroundService
{
private readonly IServiceProvider _serviceProvider;
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
await ProcessOutboxEventsAsync();
await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken);
}
}
private async Task ProcessOutboxEventsAsync()
{
using var scope = _serviceProvider.CreateScope();
var context = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
var serviceBus = scope.ServiceProvider.GetRequiredService<IServiceBus>();
var pendingEvents = await context.OutboxEvents
.Where(e => !e.IsProcessed)
.OrderBy(e => e.CreatedAt)
.Take(100)
.ToListAsync();
foreach (var outboxEvent in pendingEvents)
{
try
{
await serviceBus.PublishAsync(outboxEvent.Type, outboxEvent.Data);
outboxEvent.IsProcessed = true;
outboxEvent.ProcessedAt = DateTime.UtcNow;
await context.SaveChangesAsync();
}
catch (Exception ex)
{
// Log error and continue
}
}
}
}Outbox Pattern Benefits: Guaranteed delivery, data consistency, and resilience to system failures.
Challenges include: Complexity, latency from asynchronous processing, and duplicate message handling requirements.
Modern .Net and Azure Integration#
Latest .Net Features#
.Net introduces significant performance improvements with Dynamic Profile-Guided Optimization (PGO) enabled by default, providing up to 20% performance gains. Enhanced JIT compilation with On Stack Replacement (OSR), AVX-512 support, and Native AOT improvements deliver faster startup times and reduced memory consumption.
Key scalability features include improved parallelism support, enhanced garbage collection optimized for high-throughput scenarios, and System.Text.Json improvements with source generators to avoid reflection overhead.
Azure Container Apps and Dapr Integration#
Azure Container Apps provides fully managed Dapr integration with built-in support for Dapr runtime APIs, serverless container orchestration, and automatic scaling from zero to thousands of instances.
Azure Integration Architecture#
Container App] CA2[Payment Service
Container App] CA3[Inventory Service
Container App] end subgraph "Dapr Runtime" D1[Service Discovery] D2[State Management] D3[Pub/Sub] D4[Secret Management] end subgraph "Azure Infrastructure" ASB[Azure Service Bus
Message Broker] ACR[Azure Container Registry
Image Storage] KV[Azure Key Vault
Secret Storage] COSMOS[Cosmos DB
State Store] AI[Application Insights
Monitoring] end end subgraph "External Systems" EXT[External APIs] LEGACY[Legacy Systems] end CA1 --> D1 CA2 --> D2 CA3 --> D3 D1 -.-> ASB D2 -.-> COSMOS D3 -.-> ASB D4 -.-> KV CA1 --> AI CA2 --> AI CA3 --> AI CA1 -.-> EXT CA2 -.-> LEGACY style CA1 fill:#e3f2fd style CA2 fill:#c8e6c9 style CA3 fill:#fff3e0 style ASB fill:#ffeb3b style COSMOS fill:#ffeb3b style KV fill:#ffeb3b
.NET Aspire Integration Flow#
// .NET Aspire Integration
var builder = DistributedApplication.CreateBuilder(args);
var catalog = builder.AddProject<Projects.Catalog_API>("catalog")
.WithDaprSidecar();
var ordering = builder.AddProject<Projects.Ordering_API>("ordering")
.WithDaprSidecar();
var gateway = builder.AddProject<Projects.Gateway>("gateway")
.WithReference(catalog)
.WithReference(ordering);
builder.Build().Run();.NET Aspire provides opinionated tooling for building observable, production-ready distributed applications with 40+ pre-built integrations and built-in telemetry capabilities.
Deployment and Infrastructure Patterns#
Sidecar Pattern: Auxiliary Service Deployment#
The Sidecar Pattern deploys auxiliary services alongside main applications, providing cross-cutting functionality without modifying the core application logic.
Sidecar Architecture Overview#
.Net API] end subgraph "Sidecar Services" LS[Logging Sidecar
Fluentd] MS[Monitoring Sidecar
Prometheus Exporter] SS[Security Sidecar
Service Mesh Proxy] CS[Configuration Sidecar
Config Sync] end SV[Shared Volumes
Logs, Config, Temp] end subgraph "External Services" ELK[ELK Stack
Log Aggregation] PROM[Prometheus
Metrics Collection] VAULT[HashiCorp Vault
Secret Management] CONSUL[Consul
Service Discovery] end MA -.-> SV LS -.-> SV MS -.-> SV SS -.-> SV CS -.-> SV LS --> ELK MS --> PROM SS --> VAULT CS --> CONSUL style MA fill:#ffeb3b style LS fill:#c8e6c9 style MS fill:#e3f2fd style SS fill:#ffcdd2 style CS fill:#fff3e0
Sidecar Communication Patterns#
Sidecar vs Traditional Architecture#
Tightly Coupled] T1 --> T2[Cross-cutting Concerns
Mixed with Business Logic] T2 --> T3[Technology Lock-in
Hard to Change] end subgraph "Sidecar Pattern" S1[Clean Application
Business Logic Only] S2[Infrastructure Sidecars
Loosely Coupled] S1 -.-> S2 S2 --> S3[Technology Independence
Easy to Swap] end style T3 fill:#ffcdd2 style S3 fill:#c8e6c9
Implementation Example#
// Main Application Service
[ApiController]
[Route("api/[controller]")]
public class OrderController : ControllerBase
{
private readonly IOrderService _orderService;
[HttpPost]
public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest request)
{
// Main business logic - sidecar handles logging, monitoring automatically
var order = await _orderService.CreateAsync(request);
return Ok(order);
}
}
// Sidecar Configuration (docker-compose.yml)version: '3.8'
services:
order-service:
image: myapp/order-service:latest
ports:
- "8080:80"
environment:
- ASPNETCORE_ENVIRONMENT=Production
# Logging Sidecar
fluentd-sidecar:
image: fluent/fluentd:latest
volumes:
- ./fluentd.conf:/fluentd/etc/fluent.conf
- order-logs:/var/log/orders
depends_on:
- order-service
# Monitoring Sidecar
prometheus-exporter:
image: prom/prometheus:latest
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.ymlSidecar Implementation with .NET:
// Health Check Sidecar
public class HealthCheckSidecar : BackgroundService
{
private readonly IServiceProvider _serviceProvider;
private readonly ILogger<HealthCheckSidecar> _logger;
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
using var scope = _serviceProvider.CreateScope();
var healthCheckService = scope.ServiceProvider.GetRequiredService<HealthCheckService>();
var result = await healthCheckService.CheckHealthAsync(stoppingToken);
// Report health status to external monitoring
await ReportHealthStatusAsync(result);
await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
}
}
}When to use: Cross-cutting concerns like logging and monitoring, legacy application enhancement, or microservices requiring common functionality.
Advantages include: Language-agnostic implementation, isolated functionality, and simplified main application.
Disadvantages include: Increased resource consumption and orchestration complexity.
Ambassador Pattern: Proxy-Based Service Enhancement#
The Ambassador Pattern creates helper services that send network requests on behalf of consumer applications, acting as an out-of-process proxy for enhanced connectivity.
Ambassador Pattern Architecture#
Main Business Logic] end subgraph "Ambassador Services" PA[Payment Ambassador
Enhanced Connectivity] IA[Inventory Ambassador
Retry & Circuit Breaker] NA[Notification Ambassador
Rate Limiting] end end subgraph "External Services" PS[Payment Service
Third-party API] IS[Inventory Service
Legacy System] NS[Notification Service
Email Provider] end CA --> PA CA --> IA CA --> NA PA --> PS IA --> IS NA --> NS style CA fill:#ffeb3b style PA fill:#c8e6c9 style IA fill:#e3f2fd style NA fill:#fff3e0
Ambassador Request Flow#
Ambassador vs Direct Integration#
+ Auth Logic
+ Retry Logic
+ Monitoring
+ Circuit Breaker] D1 --> D2[Complex Codebase
Hard to Test
Technology Coupling] end subgraph "Ambassador Pattern" A1[Clean Application
Business Logic Only] A2[Ambassador Service
Connectivity Logic] A1 --> A2 A2 --> A3[Specialized Teams
Easy Testing
Technology Abstraction] end style D2 fill:#ffcdd2 style A3 fill:#c8e6c9
Implementation Example#
// Ambassador Service
public class PaymentAmbassador
{
private readonly HttpClient _httpClient;
private readonly ILogger<PaymentAmbassador> _logger;
private readonly CircuitBreakerPolicy _circuitBreaker;
public PaymentAmbassador(HttpClient httpClient, ILogger<PaymentAmbassador> logger)
{
_httpClient = httpClient;
_logger = logger;
_circuitBreaker = Policy
.Handle<HttpRequestException>()
.CircuitBreakerAsync(
exceptionsAllowedBeforeBreaking: 3,
durationOfBreak: TimeSpan.FromSeconds(30));
}
public async Task<PaymentResponse> ProcessPaymentAsync(PaymentRequest request)
{
return await _circuitBreaker.ExecuteAsync(async () =>
{
_logger.LogInformation("Processing payment for Order {OrderId}", request.OrderId);
// Add authentication headers
_httpClient.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", await GetAccessTokenAsync());
// Add tracing headers
_httpClient.DefaultRequestHeaders.Add("X-Trace-Id", Activity.Current?.Id);
var response = await _httpClient.PostAsJsonAsync("/api/payments", request);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<PaymentResponse>();
_logger.LogInformation("Payment processed successfully for Order {OrderId}", request.OrderId);
return result;
});
}
private async Task<string> GetAccessTokenAsync()
{
// Token acquisition logic
return await GetCachedTokenAsync();
}
}
// Main Application using Ambassador
public class OrderService
{
private readonly PaymentAmbassador _paymentAmbassador;
public async Task<Order> ProcessOrderAsync(CreateOrderRequest request)
{
var order = new Order(request);
// Ambassador handles all payment complexity
var paymentResult = await _paymentAmbassador.ProcessPaymentAsync(
new PaymentRequest(order.Id, order.TotalAmount));
if (paymentResult.IsSuccessful)
{
order.MarkAsPaid();
}
return order;
}
}When to use: Legacy application enhancement, common connectivity patterns, or specialized network requirements.
Advantages include: Specialized team implementation, technology abstraction, and enhanced capabilities.
Disadvantages include: Additional network latency and complexity in failure handling.
Bulkhead Pattern: Resource Isolation for Resilience#
The Bulkhead Pattern isolates resources into separate pools to prevent failure in one component from affecting the entire system, similar to watertight compartments in a ship.
Resource Isolation Architecture#
Payment, Authentication] SS[Standard Services
Product Catalog, Search] BT[Background Tasks
Analytics, Cleanup] end AC --> CP1 AC --> SP1 AC --> BP1 CP1 --> CS SP1 --> SS BP1 --> BT style CP1 fill:#ffcdd2 style SP1 fill:#fff3e0 style BP1 fill:#e8f5e8 style CS fill:#ffcdd2 style SS fill:#fff3e0 style BT fill:#e8f5e8
Failure Isolation Demonstration#
20 Threads] --> WB2[All Services
Competing for Resources] WB2 --> WB3[One Service Failure
Affects All Services] end subgraph "With Bulkhead" B1[Critical Pool
10 Threads] --> B2[Payment Service
Isolated & Protected] B3[Standard Pool
5 Threads] --> B4[Catalog Service
Limited Impact] B5[Background Pool
3 Threads] --> B6[Analytics Service
Failure Contained] end style WB3 fill:#ffcdd2 style B2 fill:#c8e6c9 style B4 fill:#c8e6c9 style B6 fill:#c8e6c9
Implementation Example#
// Resource Pool Configuration
public class BulkheadConfiguration
{
public int CriticalServiceThreads { get; set; } = 10;
public int StandardServiceThreads { get; set; } = 5;
public int BackgroundTaskThreads { get; set; } = 3;
}
// Bulkhead Implementation
public class BulkheadService
{
private readonly SemaphoreSlim _criticalSemaphore;
private readonly SemaphoreSlim _standardSemaphore;
private readonly SemaphoreSlim _backgroundSemaphore;
public BulkheadService(BulkheadConfiguration config)
{
_criticalSemaphore = new SemaphoreSlim(config.CriticalServiceThreads);
_standardSemaphore = new SemaphoreSlim(config.StandardServiceThreads);
_backgroundSemaphore = new SemaphoreSlim(config.BackgroundTaskThreads);
}
public async Task<T> ExecuteCriticalOperationAsync<T>(Func<Task<T>> operation)
{
await _criticalSemaphore.WaitAsync();
try
{
return await operation();
}
finally
{
_criticalSemaphore.Release();
}
}
public async Task<T> ExecuteStandardOperationAsync<T>(Func<Task<T>> operation)
{
await _standardSemaphore.WaitAsync();
try
{
return await operation();
}
finally
{
_standardSemaphore.Release();
}
}
}
// Usage in Controller
[ApiController]
public class ProductController : ControllerBase
{
private readonly BulkheadService _bulkheadService;
private readonly IProductService _productService;
private readonly IRecommendationService _recommendationService;
[HttpGet("{id}")]
public async Task<IActionResult> GetProduct(int id)
{
// Critical operation - guaranteed resources
var product = await _bulkheadService.ExecuteCriticalOperationAsync(async () =>
await _productService.GetByIdAsync(id));
// Non-critical operation - limited resources
var recommendations = await _bulkheadService.ExecuteStandardOperationAsync(async () =>
await _recommendationService.GetRecommendationsAsync(id));
return Ok(new { Product = product, Recommendations = recommendations });
}
}When to use: High-traffic applications, mixed workload priorities, or systems requiring guaranteed resource availability.
Advantages include: Failure isolation, resource optimization, and improved system resilience.
Disadvantages include: Increased complexity and potential resource underutilization.
Event Sourcing Pattern: Complete Audit Trail#
Event Sourcing stores application state as a sequence of events rather than current state, providing complete audit trails and enabling temporal queries.
Event Sourcing Architecture#
Order-123] ES --> E2[Event Stream 2
Order-456] ES --> E3[Event Stream 3
Order-789] end subgraph "Event Stream Details" E1 --> EV1[OrderCreated
v1] EV1 --> EV2[ItemAdded
v2] EV2 --> EV3[PaymentProcessed
v3] EV3 --> EV4[OrderShipped
v4] end subgraph "Read Side (CQRS)" ES --> EP[Event Projections] EP --> RM1[Read Model 1
Order Summary] EP --> RM2[Read Model 2
Analytics] EP --> RM3[Read Model 3
Audit Log] end subgraph "Temporal Queries" ES --> TQ[Time Travel Queries] TQ --> HS1[State at 2024-01-01] TQ --> HS2[State at 2024-06-01] TQ --> HS3[Current State] end style AR fill:#ffeb3b style ES fill:#e3f2fd style EP fill:#c8e6c9 style TQ fill:#fff3e0
Event Sourcing vs Traditional Storage#
Order: {Status: Shipped}] --> T2[Lost History
No Audit Trail] T2 --> T3[Update Overwrites
Previous Data] end subgraph "Event Sourcing" E1[Event Stream
All Changes Recorded] --> E2[Complete History
Full Audit Trail] E2 --> E3[Append Only
Immutable Events] E3 --> E4[Temporal Queries
State at Any Point] end style T3 fill:#ffcdd2 style E4 fill:#c8e6c9
Event Stream Timeline#
Implementation Example#
// Domain Events
public abstract record DomainEvent(Guid AggregateId, DateTime OccurredAt);
public record OrderCreated(Guid OrderId, string CustomerId, List<OrderItem> Items, DateTime OccurredAt)
: DomainEvent(OrderId, OccurredAt);
public record OrderItemAdded(Guid OrderId, string ProductId, int Quantity, decimal Price, DateTime OccurredAt)
: DomainEvent(OrderId, OccurredAt);
public record OrderShipped(Guid OrderId, string TrackingNumber, DateTime OccurredAt)
: DomainEvent(OrderId, OccurredAt);
// Event Store
public interface IEventStore
{
Task SaveEventsAsync(Guid aggregateId, IEnumerable<DomainEvent> events, long expectedVersion);
Task<IEnumerable<DomainEvent>> GetEventsAsync(Guid aggregateId);
Task<IEnumerable<DomainEvent>> GetEventsAsync(Guid aggregateId, DateTime fromDate);
}
// Aggregate Root with Event Sourcing
public class Order
{
private readonly List<DomainEvent> _uncommittedEvents = new();
public Guid Id { get; private set; }
public string CustomerId { get; private set; }
public List<OrderItem> Items { get; private set; } = new();
public OrderStatus Status { get; private set; }
public long Version { get; private set; }
// Constructor for new orders
public Order(string customerId, List<OrderItem> items)
{
var orderCreated = new OrderCreated(Guid.NewGuid(), customerId, items, DateTime.UtcNow);
Apply(orderCreated);
_uncommittedEvents.Add(orderCreated);
}
// Constructor for rebuilding from events
public Order(IEnumerable<DomainEvent> events)
{
foreach (var @event in events)
{
Apply(@event);
Version++;
}
}
public void AddItem(string productId, int quantity, decimal price)
{
var itemAdded = new OrderItemAdded(Id, productId, quantity, price, DateTime.UtcNow);
Apply(itemAdded);
_uncommittedEvents.Add(itemAdded);
}
public void Ship(string trackingNumber)
{
var orderShipped = new OrderShipped(Id, trackingNumber, DateTime.UtcNow);
Apply(orderShipped);
_uncommittedEvents.Add(orderShipped);
}
private void Apply(DomainEvent @event)
{
switch (@event)
{
case OrderCreated created:
Id = created.OrderId;
CustomerId = created.CustomerId;
Items = created.Items.ToList();
Status = OrderStatus.Created;
break;
case OrderItemAdded itemAdded:
Items.Add(new OrderItem(itemAdded.ProductId, itemAdded.Quantity, itemAdded.Price));
break;
case OrderShipped shipped:
Status = OrderStatus.Shipped;
break;
}
}
public IEnumerable<DomainEvent> GetUncommittedEvents() => _uncommittedEvents.AsReadOnly();
public void MarkEventsAsCommitted() => _uncommittedEvents.Clear();
}
// Repository Implementation
public class OrderRepository
{
private readonly IEventStore _eventStore;
public async Task SaveAsync(Order order)
{
var events = order.GetUncommittedEvents();
if (events.Any())
{
await _eventStore.SaveEventsAsync(order.Id, events, order.Version);
order.MarkEventsAsCommitted();
}
}
public async Task<Order> GetByIdAsync(Guid orderId)
{
var events = await _eventStore.GetEventsAsync(orderId);
return events.Any() ? new Order(events) : null;
}
public async Task<Order> GetOrderStateAtDateAsync(Guid orderId, DateTime asOfDate)
{
var events = await _eventStore.GetEventsAsync(orderId, asOfDate);
return events.Any() ? new Order(events) : null;
}
}Event Sourcing Benefits: Complete audit trail, temporal queries, debugging capabilities, and natural fit with event-driven architectures.
Challenges include: Complexity, eventual consistency, and query difficulty requiring CQRS implementation.
Pattern Combination Strategies#
Successful architectures often combine multiple patterns. Here are proven combinations:
Common Successful Combinations:
Enterprise-Grade Pattern Combinations#
Onion + CQRS + Event Sourcing: Complex enterprise applications with rich business logic
- Use case: Financial systems, healthcare platforms, enterprise resource planning
- Benefits: Domain-driven design, complete audit trail, high performance
- Complexity: High, requires experienced team
Hexagonal + Event-Driven + Bulkhead: Technology-agnostic business logic with asynchronous communication and resource isolation
- Use case: Microservices architectures, distributed systems
- Benefits: Technology independence, fault isolation, scalability
- Complexity: Medium to High
Client-Facing Pattern Combinations#
API Gateway + BFF + Circuit Breaker: Client-facing applications requiring resilience and optimization
- Use case: Multi-platform applications (web, mobile, IoT)
- Benefits: Client optimization, centralized routing, fault tolerance
- Complexity: Medium
BFF + Serverless + Ambassador: Modern client-optimized backends
- Use case: Event-driven applications with multiple clients
- Benefits: Auto-scaling, cost efficiency, enhanced connectivity
- Complexity: Medium
Legacy Modernization Combinations#
Strangler Fig + BFF + Serverless: Modernizing legacy systems using client-specific backends and event-driven Functions
- Use case: Legacy system modernization with minimal disruption
- Benefits: Gradual migration, reduced risk, modern architecture
- Complexity: Medium to High
Strangler Fig + Event-Driven + Outbox: Reliable legacy integration with modern event systems
- Use case: Legacy systems requiring reliable message delivery
- Benefits: Reliable messaging, gradual modernization, data consistency
- Complexity: High
Resilience-Focused Combinations#
Circuit Breaker + Bulkhead + Outbox: Comprehensive resilience with failure isolation and reliable messaging
- Use case: High-availability systems, critical business applications
- Benefits: Fault tolerance, resource isolation, message reliability
- Complexity: Medium
Sidecar + Ambassador + Circuit Breaker: Infrastructure patterns for cross-cutting concerns
- Use case: Microservices requiring common infrastructure capabilities
- Benefits: Technology independence, enhanced connectivity, fault tolerance
- Complexity: Medium to High
Pattern Relationship Map#
Understanding how patterns complement each other in modern architectures:
1. Pattern Categories Overview#
Core Architecture
▫️ Layered
▫️ Hexagonal
▫️ Onion"] C["💬 COMMUNICATION
Data & Messages
▫️ CQRS
▫️ Event-Driven
▫️ Saga"] I["🔗 INTEGRATION
Service Connection
▫️ API Gateway
▫️ BFF
▫️ Serverless
▫️ Strangler Fig"] R["🛡️ RESILIENCE
Fault Tolerance
▫️ Circuit Breaker
▫️ Bulkhead
▫️ Outbox"] IN["🚀 INFRASTRUCTURE
Deployment Support
▫️ Sidecar
▫️ Ambassador"] D["📊 DATA & EVENTS
State Management
▫️ Event Sourcing"] end F --> C C --> I I --> R R --> IN C --> D style F fill:#e8f5e8,stroke:#4caf50,stroke-width:3px style C fill:#f3e5f5,stroke:#9c27b0,stroke-width:3px style I fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px style R fill:#fff8e1,stroke:#ffc107,stroke-width:3px style IN fill:#fce4ec,stroke:#e91e63,stroke-width:3px style D fill:#f1f8e9,stroke:#8bc34a,stroke-width:3px
2. Foundation to Communication Flow#
Simple 3-tier
👥 Junior Level
⭐ Low Complexity"] F2["HEXAGONAL
Ports & Adapters
👨💻 Senior Level
⭐⭐ Medium Complexity"] F3["ONION
Domain-Centric
👨💻 Senior Level
⭐⭐ Medium Complexity"] end subgraph "💬 Communication Patterns" C1["CQRS
Separate Read/Write
👨💻 Senior Level
⭐⭐ Medium Complexity"] C2["EVENT-DRIVEN
Async Messaging
👨💻 Senior Level
⭐⭐⭐ High Complexity"] C3["SAGA
Distributed Transactions
👨💻 Senior Level
⭐⭐⭐ High Complexity"] end F2 ==>|"Enables Clean Testing"| C1 F3 ==>|"Domain-Driven Design"| C1 C1 ==>|"Often Combined"| C2 C2 ==>|"Orchestrates Complex Workflows"| C3 style F1 fill:#e8f5e8,stroke:#4caf50,stroke-width:3px,color:#000 style F2 fill:#e8f5e8,stroke:#4caf50,stroke-width:3px,color:#000 style F3 fill:#e8f5e8,stroke:#4caf50,stroke-width:3px,color:#000 style C1 fill:#f3e5f5,stroke:#9c27b0,stroke-width:3px,color:#000 style C2 fill:#f3e5f5,stroke:#9c27b0,stroke-width:3px,color:#000 style C3 fill:#f3e5f5,stroke:#9c27b0,stroke-width:3px,color:#000
3. Integration and Resilience Patterns#
Single Entry Point
� Intermediate
⭐⭐ Medium Complexity"] I2["BFF
Backend for Frontend
👥 Intermediate
⭐ Low Complexity"] I3["SERVERLESS
Event-Driven Functions
� Intermediate
⭐ Low Complexity"] I4["STRANGLER FIG
Legacy Modernization
👨💻 Senior
⭐⭐ Medium Complexity"] end subgraph "🛡️ Resilience Patterns" R1["CIRCUIT BREAKER
Fail Fast Protection
👥 Intermediate
⭐ Low Complexity"] R2["BULKHEAD
Resource Isolation
👥 Intermediate
⭐ Low Complexity"] R3["OUTBOX
Reliable Messaging
👨💻 Senior
⭐⭐ Medium Complexity"] end I1 ==>|"Client Optimization"| I2 I1 ==>|"Auto-Scaling"| I3 I1 ==>|"Protection Layer"| R1 R1 ==>|"Resource Protection"| R2 I4 ==>|"Modern Architecture"| I1 style I1 fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px,color:#000 style I2 fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px,color:#000 style I3 fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px,color:#000 style I4 fill:#fff3e0,stroke:#ff9800,stroke-width:3px,color:#000 style R1 fill:#fff8e1,stroke:#ffc107,stroke-width:3px,color:#000 style R2 fill:#fff8e1,stroke:#ffc107,stroke-width:3px,color:#000 style R3 fill:#fff8e1,stroke:#ffc107,stroke-width:3px,color:#000
4. Infrastructure and Data Patterns#
Cross-Cutting Concerns
👥 Intermediate
⭐⭐ Medium Complexity"] IN2["AMBASSADOR
External Service Proxy
👥 Intermediate
⭐⭐ Medium Complexity"] end subgraph "📊 Data & Event Patterns" D1["EVENT SOURCING
Complete Audit Trail
👨💻 Senior
⭐⭐⭐ High Complexity"] end subgraph "Integration Support" IS1["Enhanced Monitoring"] IS2["Service Mesh"] IS3["Temporal Queries"] end IN1 ==>|"Provides"| IS1 IN2 ==>|"Enables"| IS2 D1 ==>|"Supports"| IS3 style IN1 fill:#fce4ec,stroke:#e91e63,stroke-width:3px,color:#000 style IN2 fill:#fce4ec,stroke:#e91e63,stroke-width:3px,color:#000 style D1 fill:#f1f8e9,stroke:#8bc34a,stroke-width:3px,color:#000 style IS1 fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px,color:#000 style IS2 fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px,color:#000 style IS3 fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px,color:#000
5. Common Pattern Combinations#
Relationship Types Explained:
- Solid arrows (—›): Strong dependencies or common combinations
- Dotted arrows (-.→): Optional enhancements or frequent pairings
- Line thickness: Indicates how commonly patterns are used together
- Color coding: Groups patterns by primary purpose and complexity
Key Architectural Combinations:
- Modern Microservices Stack:
Hexagonal + CQRS + Event-Driven + API Gateway + Circuit Breaker - Enterprise Application:
Onion + CQRS + Outbox + BFF + Sidecar - Cloud-Native Solution:
Serverless + Event-Driven + Circuit Breaker + Ambassador - Legacy Modernization:
Strangler Fig + Hexagonal + Event-Driven + API Gateway
Architecture Decision Framework#
Comprehensive Pattern Comparison Matrix#
| Pattern | Complexity | Scalability | Maintainability | Team Skill | Time to Value | Primary Use Cases |
|---|---|---|---|---|---|---|
| 🏗️ Foundation Patterns | ||||||
| Layered | Low ⭐ | Medium ⭐⭐ | Medium ⭐⭐ | Junior+ 👥 | Fast ⚡ | CRUD apps, rapid prototyping |
| Hexagonal | Medium ⭐⭐ | High ⭐⭐⭐ | High ⭐⭐⭐ | Senior 👨💻 | Medium 🔄 | Complex business logic, testability |
| Onion | Medium ⭐⭐ | High ⭐⭐⭐ | High ⭐⭐⭐ | Senior 👨💻 | Medium 🔄 | DDD, enterprise applications |
| 💬 Communication Patterns | ||||||
| CQRS | Medium ⭐⭐ | Very High ⭐⭐⭐⭐ | Medium ⭐⭐ | Senior 👨💻 | Medium 🔄 | Read/write optimization |
| Event-Driven | High ⭐⭐⭐ | Very High ⭐⭐⭐⭐ | Medium ⭐⭐ | Senior 👨💻 | Slow 🐌 | Microservices, real-time |
| Saga | High ⭐⭐⭐ | High ⭐⭐⭐ | Medium ⭐⭐ | Senior 👨💻 | Slow 🐌 | Distributed transactions |
| 🔗 Integration Patterns | ||||||
| API Gateway | Medium ⭐⭐ | High ⭐⭐⭐ | Medium ⭐⭐ | Intermediate 👥 | Fast ⚡ | Service aggregation |
| BFF | Low ⭐ | Medium ⭐⭐ | Medium ⭐⭐ | Intermediate 👥 | Fast ⚡ | Client-specific APIs |
| Serverless | Low ⭐ | Very High ⭐⭐⭐⭐ | Medium ⭐⭐ | Intermediate 👥 | Fast ⚡ | Event-driven, auto-scale |
| Strangler Fig | Medium ⭐⭐ | Medium ⭐⭐ | High ⭐⭐⭐ | Senior 👨💻 | Slow 🐌 | Legacy modernization |
| 🛡️ Resilience Patterns | ||||||
| Circuit Breaker | Low ⭐ | High ⭐⭐⭐ | High ⭐⭐⭐ | Intermediate 👥 | Fast ⚡ | Fault tolerance |
| Bulkhead | Low ⭐ | High ⭐⭐⭐ | High ⭐⭐⭐ | Intermediate 👥 | Fast ⚡ | Resource isolation |
| Outbox | Medium ⭐⭐ | Medium ⭐⭐ | High ⭐⭐⭐ | Senior 👨💻 | Medium 🔄 | Reliable messaging |
| 🚀 Infrastructure Patterns | ||||||
| Sidecar | Medium ⭐⭐ | High ⭐⭐⭐ | High ⭐⭐⭐ | Intermediate 👥 | Medium 🔄 | Cross-cutting concerns |
| Ambassador | Medium ⭐⭐ | High ⭐⭐⭐ | High ⭐⭐⭐ | Intermediate 👥 | Medium 🔄 | External service proxy |
| 📊 Data & Event Patterns | ||||||
| Event Sourcing | High ⭐⭐⭐ | High ⭐⭐⭐ | Medium ⭐⭐ | Senior 👨💻 | Slow 🐌 | Audit trail, temporal queries |
Team Size and Project Type Recommendations#
(1-3 devs)
📊 Focus: Simplicity"] T2["Medium Team
(4-8 devs)
📊 Focus: Structure"] T3["Large Team
(9+ devs)
📊 Focus: Boundaries"] end subgraph ProjectType["🎯 Project Type"] P1["MVP/Prototype
⚡ Speed First"] P2["Enterprise App
🏢 Quality First"] P3["Microservices
🌐 Scale First"] P4["Legacy Migration
🔄 Safety First"] end T1 --> P1 T1 --> |"with guidance"| P2 T2 --> P2 T2 --> P3 T3 --> P2 T3 --> P3 T3 --> P4 P1 -.-> R1["✅ Layered + Serverless
🚀 API Gateway + Circuit Breaker"] P2 -.-> R2["✅ Hexagonal/Onion + CQRS
🚀 BFF + Outbox + Sidecar"] P3 -.-> R3["✅ Event-Driven + API Gateway
🚀 Circuit Breaker + Ambassador + Saga"] P4 -.-> R4["✅ Strangler Fig + Hexagonal
🚀 Event-Driven + API Gateway"] style T1 fill:#e8f5e8 style T2 fill:#fff3e0 style T3 fill:#ffebee style P1 fill:#e3f2fd style P2 fill:#f3e5f5 style P3 fill:#e8f5e8 style P4 fill:#fff8e1
| BFF | Medium | High | Medium | Intermediate | Multi-platform apps, API optimization | | Sidecar | Low | Medium | High | Intermediate | Cross-cutting concerns, auxiliary services | | Ambassador | Medium | Medium | High | Intermediate | Legacy enhancement, proxy patterns | | Bulkhead | Medium | High | High | Senior | Resource isolation, fault tolerance | | Event Sourcing | High | Very High | Medium | Senior | Audit trails, temporal queries |
Pattern Combination Strategies#
Successful architectures often combine multiple patterns. Common combinations include:
Performance Impact Comparison#
Pattern Migration Paths#
• Circuit Breaker
• Bulkhead
• Event Sourcing
• Saga] style Start fill:#e3f2fd style Optimize fill:#ffeb3b style Patterns fill:#c8e6c9
- CQRS + Event-Driven + Event Sourcing: Complete event-based architecture with separated read/write models, event communication, and complete audit trails
- BFF + API Gateway: Client-optimized backends with centralized routing and cross-cutting concerns
- Sidecar + Ambassador: Auxiliary services with enhanced connectivity patterns
- Hexagonal + Event-Driven + Bulkhead: Technology-agnostic business logic with asynchronous communication and resource isolation
- Strangler Fig + BFF + Serverless: Modernizing legacy systems using client-specific backends and event-driven Functions
- Circuit Breaker + Bulkhead + Outbox: Comprehensive resilience with failure isolation and reliable messaging
Best Practices for Implementation#
Pattern Implementation Lifecycle#
Current Architecture Review
Business Requirements
Performance Needs] B --> B1[Pattern Selection
Architecture Design
Technology Stack
Migration Strategy] C --> C1[Code Implementation
Infrastructure Setup
Integration Development
Documentation] D --> D1[Unit Testing
Integration Testing
Performance Testing
Security Testing] E --> E1[Blue-Green Deployment
Feature Flags
Gradual Rollout
Rollback Planning] F --> F1[Performance Monitoring
Error Tracking
Business Metrics
Health Checks] G --> G1[Pattern Effectiveness
Scaling Needs
Technology Updates
Optimization] style A fill:#e3f2fd style B fill:#fff3e0 style C fill:#c8e6c9 style D fill:#ffcdd2 style E fill:#f3e5f5 style F fill:#ffeb3b style G fill:#e1bee7
Team Skill Requirements Matrix#
Start with architectural assessment#
Begin with a thorough assessment of your current system, team capabilities, and business requirements. Simple applications benefit from Layered Architecture, while complex enterprise systems require Onion or Hexagonal approaches.
Implement monitoring and observability#
Modern .Net applications should leverage OpenTelemetry for distributed tracing, Application Insights for performance monitoring, and custom metrics for business-specific monitoring.
Comprehensive Observability Architecture#
Telemetry Data Flow#
// OpenTelemetry Configuration
services.AddOpenTelemetry()
.WithTracing(builder =>
{
builder.AddSource("Polly");
builder.AddAspNetCoreInstrumentation();
})
.WithMetrics(builder =>
{
builder.AddMeter("Polly");
builder.AddMeter("Microsoft.Extensions.Http.Resilience");
});Adopt gradual migration strategies#
When modernizing existing systems, use the Strangler Fig Pattern to gradually replace components while maintaining operational continuity. Start with low-risk components and expand systematically.
Ensure team readiness#
Advanced patterns require skilled teams. Invest in training for Domain-Driven Design, microservices principles, and cloud-native development practices before implementing complex patterns.
Conclusion#
This visual guide transforms complex architectural decisions into clear, actionable workflows. The modern .NET ecosystem offers unprecedented capabilities for building scalable, resilient applications, and the visual decision trees and flow diagrams in this guide help architects navigate the complexity of pattern selection.
Key Takeaways#
Decision Framework Summary#
Follow these visual workflows for architectural success:
- Assessment Phase: Use the pattern selection decision tree to identify suitable patterns
- Design Phase: Apply architecture flow diagrams to structure your solution
- Implementation Phase: Reference minimal code contracts and interfaces
- Evolution Phase: Leverage pattern relationship maps for strategic enhancement
The Visual Advantage#
Diagrams over code samples provide lasting value because they:
- Focus on architectural concepts rather than implementation details
- Remain relevant as technology evolves
- Enable better communication across teams
- Support faster decision-making processes
- Facilitate pattern combination strategies
Success in modern .NET architecture depends on visual thinking, systematic pattern selection, and evolutionary design approaches. Use the decision trees and workflow diagrams in this guide to build applications that are not only functional today but adaptable for tomorrow’s requirements.
