refactor(arch): introduce IEbookRepository, ISyncBroadcaster, fix EpubReader path resolution
Critical fixes (review findings #1, #2, #3): - Create IEbookRepository abstraction in Application layer - Remove illegal EF Core dependency from IngestEbookCommandHandler - Create EbookRepository implementation in Infrastructure/Persistence - Create ISyncBroadcaster in Application/Abstractions/Messaging - Create SignalRSyncBroadcaster in Infrastructure/RealTime - Move UpdateReadingProgressCommandHandler from Infrastructure → Application - Add EbookId to GetReaderPageQuery and IEpubReader signature - Rewrite EpubReaderService: DB-resolved file path, remove auto-provisioning - Split EpubService.cs into EpubReaderService.cs + EpubMetadataExtractor.cs - Add CurrentEbookId to IReaderNavigationService and ReaderNavigationService - Update WasmEpubReader and /api/epub endpoint for new signature High severity fixes (#4, #6, #7, #8, #16): - Change BookStorageService registration from Singleton → Scoped - Fix empty catch{} in ReaderCanvas JS interop init — now logs warnings - Replace all Console.WriteLine with ILogger in KnowledgeService + ReaderCanvas - Cache JsonSerializerOptions as static field in KnowledgeService - Wrap SyncService Task.Run body in comprehensive try/catch with ILogger Medium/Low fixes (#11, #13, #14, #15, #18, #20): - BookIngestionModal.DisposeAsync now nullifies _epubBytes (50MB array) - KnowledgeCoordinator.OnGraphUpdated: Action<T> → Func<T, Task> - BookStorageService: Path.Combine → forward-slash string interpolation - SignalR CancellationToken passed as named parameter (not payload arg)
This commit is contained in:
@@ -0,0 +1,140 @@
|
||||
---
|
||||
name: nexus-dotnet-architect
|
||||
description: Guides the development of production-grade .NET 10 APIs and microservices for the Nexus project, enforcing Clean Architecture, CQRS, Result Pattern, Mapster, no async void, specific project standards like Multi-Tenancy and EF Core migrations, and backend development best practices like caching, resilience, observability, and AI-powered code analysis. Use when building backend services or APIs within the Nexus ecosystem.
|
||||
---
|
||||
|
||||
# Nexus Dotnet Architect Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides expert guidance for developing production-grade .NET 10 APIs and microservices within the Nexus project ecosystem. It enforces a strict adherence to the defined architecture, technical constraints, and development workflow, ensuring high performance, maintainability, and scalability.
|
||||
|
||||
## Core Principles & Constraints
|
||||
|
||||
This skill mandates the following architectural and development standards:
|
||||
|
||||
### Architecture
|
||||
|
||||
- **Clean Architecture:** Strict separation of concerns: `Domain` -> `Application` <- `Infrastructure`.
|
||||
- **CQRS Pattern:** Mandatory use of `MediatR`. All business logic must reside in handlers, not UI components.
|
||||
- **Result Pattern:** Zero exceptions for flow control. All handlers must return `Result<T>` via `FluentResult`.
|
||||
- **Mapping:** Exclusive use of `Mapster`. No other mapping libraries are permitted.
|
||||
|
||||
### Technical Constraints
|
||||
|
||||
- **Platform:** Target .NET 10 with **Native AOT** compatibility. Optimize for mobile performance.
|
||||
- **UI Framework:** Blazor Component Model. Use isolated Razor Components (`.razor` + `.razor.css`). No raw HTML/CSS in components.
|
||||
- **Directory Structure:** `/src` for application code and `/tests` for testing code at the solution root level.
|
||||
|
||||
### Development Workflow
|
||||
|
||||
- **Verification-Led:** Define tests and verification steps *before* writing feature code.
|
||||
- **Step-by-Step Execution:** Break complex tasks into manageable, verifiable chunks.
|
||||
- **Layer Integrity:** Constantly check for and prevent illegal cross-layer dependencies (e.g., `Application` depending on `Infrastructure`).
|
||||
- **Mandatory Build Gate:** After **every** code change, run `dotnet build NexusReader.slnx --no-restore` from the solution root. The agent must not proceed if there are any `error CS*` compiler errors. Build warnings are acceptable.
|
||||
|
||||
### API & Microservice Focus
|
||||
|
||||
- Develop production-grade APIs and microservices using C# and ASP.NET Core.
|
||||
- Leverage modern C# features.
|
||||
- Implement robust data access patterns, including EF Core and Dapper.
|
||||
- Incorporate caching strategies and performance optimization.
|
||||
|
||||
## Project Specific Standards
|
||||
|
||||
### Multi-Tenancy (Tenant Isolation)
|
||||
|
||||
- Every entity related to user data MUST have a `TenantId` property.
|
||||
- Every query MUST filter by `TenantId` to prevent data leakage.
|
||||
- Default `TenantId` is "global" for shared resources.
|
||||
|
||||
### Database Schema Changes
|
||||
|
||||
- Every change to a Domain entity or DbContext MUST be followed by the generation of a new EF Core migration.
|
||||
- **Mandatory Commands**:
|
||||
- `dotnet ef migrations add <MigrationName> --project src/NexusReader.Data --startup-project src/NexusReader.Web`
|
||||
- `dotnet ef database update --project src/NexusReader.Data --startup-project src/NexusReader.Web`
|
||||
- Ensure the migration is applied to all local development environments before proceeding with feature verification.
|
||||
|
||||
### Auditing & Verification
|
||||
|
||||
- **Audit Scripts:** Use `src/.agent/skills/nexus-architecture-standards/scripts/arch_check.sh` (or equivalent logic) to scan for illegal cross-layer imports. This script should be run regularly to maintain layer integrity.
|
||||
- **Reference Materials:** Refer to `src/.agent/skills/nexus-architecture-standards/artifacts/layer_matrix.md` for a clear definition of layer dependencies.
|
||||
|
||||
## Backend Development Patterns
|
||||
|
||||
### Architecture & Design
|
||||
|
||||
- **API Design:** Follow RESTful principles, use clear and consistent naming conventions.
|
||||
- **Microservices Principles:** Design for independent deployability, scalability, and fault isolation.
|
||||
- **Domain-Driven Design (DDD):** Apply DDD concepts where appropriate to model complex business domains.
|
||||
|
||||
### Dependency Injection
|
||||
|
||||
- Utilize the built-in .NET Core Dependency Injection container.
|
||||
- Register services with appropriate lifetimes (Scoped, Singleton, Transient).
|
||||
- Prefer constructor injection.
|
||||
|
||||
### Caching
|
||||
|
||||
- Implement distributed caching using **Redis** for improved performance and reduced database load.
|
||||
- Apply caching strategies judiciously (e.g., cache-aside, read-through, write-through).
|
||||
|
||||
### Database Optimization
|
||||
|
||||
- **Entity Framework Core (EF Core):** Optimize queries, use `AsNoTracking()`, leverage projections, and manage migrations effectively.
|
||||
- **Dapper:** Utilize Dapper for performance-critical queries where EF Core might be too slow.
|
||||
- **Connection Pooling:** Ensure database connections are managed efficiently.
|
||||
|
||||
### Resilience Patterns
|
||||
|
||||
- **Retry Policies:** Implement retry logic for transient failures (e.g., network issues, temporary service unavailability) using libraries like Polly.
|
||||
- **Circuit Breaker:** Protect against cascading failures by implementing circuit breaker patterns.
|
||||
- **Timeouts:** Configure appropriate timeouts for external service calls and database operations.
|
||||
|
||||
### Observability
|
||||
|
||||
- **Logging:** Implement structured logging using a robust logging framework (e.g., Serilog).
|
||||
- **Monitoring:** Integrate with monitoring solutions (e.g., Application Insights, Prometheus) for metrics and performance tracking.
|
||||
- **Distributed Tracing:** Enable distributed tracing to track requests across multiple services.
|
||||
|
||||
## Code Review & Quality Assurance
|
||||
|
||||
### Static Analysis
|
||||
|
||||
- Scan code for common bugs, anti-patterns, and style violations.
|
||||
- Ensure adherence to project coding standards.
|
||||
|
||||
### Security Review (OWASP)
|
||||
|
||||
- Identify potential security vulnerabilities based on OWASP Top 10 guidelines.
|
||||
- Check for common security flaws like injection vulnerabilities, broken authentication, etc.
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
- Analyze code for performance bottlenecks.
|
||||
- Suggest improvements for efficiency and resource utilization.
|
||||
|
||||
### Infrastructure-as-Code (IaC) Assessment
|
||||
|
||||
- Review IaC definitions (e.g., Terraform, Dockerfile) for security and best practices.
|
||||
|
||||
## Review Process
|
||||
|
||||
The code reviewer follows a structured, 10-step approach to provide feedback:
|
||||
|
||||
1. **Understand Context:** Analyze the code and its purpose.
|
||||
2. **Static Analysis:** Perform initial checks for common issues.
|
||||
3. **Security Scan:** Identify potential security vulnerabilities.
|
||||
4. **Performance Check:** Evaluate for performance bottlenecks.
|
||||
5. **IaC Review:** Assess infrastructure code if applicable.
|
||||
6. **Best Practices Check:** Verify adherence to established patterns.
|
||||
7. **Constructive Feedback:** Provide clear, actionable suggestions.
|
||||
8. **Prioritization:** Rank feedback by severity (critical, high, medium, low).
|
||||
9. **Educational Tone:** Explain *why* a change is recommended.
|
||||
10. **Final Summary:** Consolidate findings and recommendations.
|
||||
|
||||
## Resources
|
||||
|
||||
- **EF Core Best Practices:** See `references/ef-core-best-practices.md` for detailed guidance on optimizing EF Core usage.
|
||||
- **Implementation Playbook:** Refer to `resources/implementation-playbook.md` for detailed examples and implementation guidance.
|
||||
@@ -0,0 +1,355 @@
|
||||
# Entity Framework Core Best Practices
|
||||
|
||||
Performance optimization and best practices for EF Core in production applications.
|
||||
|
||||
## Query Optimization
|
||||
|
||||
### 1. Use AsNoTracking for Read-Only Queries
|
||||
|
||||
```csharp
|
||||
// ✅ Good - No change tracking overhead
|
||||
var products = await _context.Products
|
||||
.AsNoTracking()
|
||||
.Where(p => p.CategoryId == categoryId)
|
||||
.ToListAsync(ct);
|
||||
|
||||
// ❌ Bad - Unnecessary tracking for read-only data
|
||||
var products = await _context.Products
|
||||
.Where(p => p.CategoryId == categoryId)
|
||||
.ToListAsync(ct);
|
||||
```
|
||||
|
||||
### 2. Select Only Needed Columns
|
||||
|
||||
```csharp
|
||||
// ✅ Good - Project to DTO
|
||||
var products = await _context.Products
|
||||
.AsNoTracking()
|
||||
.Where(p => p.CategoryId == categoryId)
|
||||
.Select(p => new ProductDto
|
||||
{
|
||||
Id = p.Id,
|
||||
Name = p.Name,
|
||||
Price = p.Price
|
||||
})
|
||||
.ToListAsync(ct);
|
||||
|
||||
// ❌ Bad - Fetching all columns
|
||||
var products = await _context.Products
|
||||
.Where(p => p.CategoryId == categoryId)
|
||||
.ToListAsync(ct);
|
||||
```
|
||||
|
||||
### 3. Avoid N+1 Queries with Eager Loading
|
||||
|
||||
```csharp
|
||||
// ✅ Good - Single query with Include
|
||||
var orders = await _context.Orders
|
||||
.AsNoTracking()
|
||||
.Include(o => o.Items)
|
||||
.ThenInclude(i => i.Product)
|
||||
.Where(o => o.CustomerId == customerId)
|
||||
.ToListAsync(ct);
|
||||
|
||||
// ❌ Bad - N+1 queries (lazy loading)
|
||||
var orders = await _context.Orders
|
||||
.Where(o => o.CustomerId == customerId)
|
||||
.ToListAsync(ct);
|
||||
|
||||
foreach (var order in orders)
|
||||
{
|
||||
// Each iteration triggers a separate query!
|
||||
var items = order.Items.ToList();
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Use Split Queries for Large Includes
|
||||
|
||||
```csharp
|
||||
// ✅ Good - Prevents cartesian explosion
|
||||
var orders = await _context.Orders
|
||||
.AsNoTracking()
|
||||
.Include(o => o.Items)
|
||||
.Include(o => o.Payments)
|
||||
.Include(o => o.ShippingHistory)
|
||||
.AsSplitQuery() // Executes as multiple queries
|
||||
.Where(o => o.CustomerId == customerId)
|
||||
.ToListAsync(ct);
|
||||
```
|
||||
|
||||
### 5. Use Compiled Queries for Hot Paths
|
||||
|
||||
```csharp
|
||||
public class ProductRepository
|
||||
{
|
||||
// Compile once, reuse many times
|
||||
private static readonly Func<AppDbContext, string, Task<Product?>> GetByIdQuery =
|
||||
EF.CompileAsyncQuery((AppDbContext ctx, string id) =>
|
||||
ctx.Products.AsNoTracking().FirstOrDefault(p => p.Id == id));
|
||||
|
||||
private static readonly Func<AppDbContext, int, IAsyncEnumerable<Product>> GetByCategoryQuery =
|
||||
EF.CompileAsyncQuery((AppDbContext ctx, int categoryId) =>
|
||||
ctx.Products.AsNoTracking().Where(p => p.CategoryId == categoryId));
|
||||
|
||||
public Task<Product?> GetByIdAsync(string id, CancellationToken ct)
|
||||
=> GetByIdQuery(_context, id);
|
||||
|
||||
public IAsyncEnumerable<Product> GetByCategoryAsync(int categoryId)
|
||||
=> GetByCategoryQuery(_context, categoryId);
|
||||
}
|
||||
```
|
||||
|
||||
## Batch Operations
|
||||
|
||||
### 6. Use ExecuteUpdate/ExecuteDelete (.NET 7+)
|
||||
|
||||
```csharp
|
||||
// ✅ Good - Single SQL UPDATE
|
||||
await _context.Products
|
||||
.Where(p => p.CategoryId == oldCategoryId)
|
||||
.ExecuteUpdateAsync(s => s
|
||||
.SetProperty(p => p.CategoryId, newCategoryId)
|
||||
.SetProperty(p => p.UpdatedAt, DateTime.UtcNow),
|
||||
ct);
|
||||
|
||||
// ✅ Good - Single SQL DELETE
|
||||
await _context.Products
|
||||
.Where(p => p.IsDeleted && p.UpdatedAt < cutoffDate)
|
||||
.ExecuteDeleteAsync(ct);
|
||||
|
||||
// ❌ Bad - Loads all entities into memory
|
||||
var products = await _context.Products
|
||||
.Where(p => p.CategoryId == oldCategoryId)
|
||||
.ToListAsync(ct);
|
||||
|
||||
foreach (var product in products)
|
||||
{
|
||||
product.CategoryId = newCategoryId;
|
||||
}
|
||||
await _context.SaveChangesAsync(ct);
|
||||
```
|
||||
|
||||
### 7. Bulk Insert with EFCore.BulkExtensions
|
||||
|
||||
```csharp
|
||||
// Using EFCore.BulkExtensions package
|
||||
var products = GenerateLargeProductList();
|
||||
|
||||
// ✅ Good - Bulk insert (much faster for large datasets)
|
||||
await _context.BulkInsertAsync(products, ct);
|
||||
|
||||
// ❌ Bad - Individual inserts
|
||||
foreach (var product in products)
|
||||
{
|
||||
_context.Products.Add(product);
|
||||
}
|
||||
await _context.SaveChangesAsync(ct);
|
||||
```
|
||||
|
||||
## Connection Management
|
||||
|
||||
### 8. Configure Connection Pooling
|
||||
|
||||
```csharp
|
||||
services.AddDbContext<AppDbContext>(options =>
|
||||
{
|
||||
options.UseSqlServer(connectionString, sqlOptions =>
|
||||
{
|
||||
sqlOptions.EnableRetryOnFailure(
|
||||
maxRetryCount: 3,
|
||||
maxRetryDelay: TimeSpan.FromSeconds(10),
|
||||
errorNumbersToAdd: null);
|
||||
|
||||
sqlOptions.CommandTimeout(30);
|
||||
});
|
||||
|
||||
// Performance settings
|
||||
options.UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking);
|
||||
|
||||
// Development only
|
||||
if (env.IsDevelopment())
|
||||
{
|
||||
options.EnableSensitiveDataLogging();
|
||||
options.EnableDetailedErrors();
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 9. Use DbContext Pooling
|
||||
|
||||
```csharp
|
||||
// ✅ Good - Context pooling (reduces allocation overhead)
|
||||
services.AddDbContextPool<AppDbContext>(options =>
|
||||
{
|
||||
options.UseSqlServer(connectionString);
|
||||
}, poolSize: 128);
|
||||
|
||||
// Instead of AddDbContext
|
||||
```
|
||||
|
||||
## Concurrency and Transactions
|
||||
|
||||
### 10. Handle Concurrency with Row Versioning
|
||||
|
||||
```csharp
|
||||
public class Product
|
||||
{
|
||||
public string Id { get; set; }
|
||||
public string Name { get; set; }
|
||||
|
||||
[Timestamp]
|
||||
public byte[] RowVersion { get; set; } // SQL Server rowversion
|
||||
}
|
||||
|
||||
// Or with Fluent API
|
||||
builder.Property(p => p.RowVersion)
|
||||
.IsRowVersion();
|
||||
|
||||
// Handle concurrency conflicts
|
||||
try
|
||||
{
|
||||
await _context.SaveChangesAsync(ct);
|
||||
}
|
||||
catch (DbUpdateConcurrencyException ex)
|
||||
{
|
||||
var entry = ex.Entries.Single();
|
||||
var databaseValues = await entry.GetDatabaseValuesAsync(ct);
|
||||
|
||||
if (databaseValues == null)
|
||||
{
|
||||
// Entity was deleted
|
||||
throw new NotFoundException("Product was deleted by another user");
|
||||
}
|
||||
|
||||
// Client wins - overwrite database values
|
||||
entry.OriginalValues.SetValues(databaseValues);
|
||||
await _context.SaveChangesAsync(ct);
|
||||
}
|
||||
```
|
||||
|
||||
### 11. Use Explicit Transactions When Needed
|
||||
|
||||
```csharp
|
||||
await using var transaction = await _context.Database.BeginTransactionAsync(ct);
|
||||
|
||||
try
|
||||
{
|
||||
// Multiple operations
|
||||
_context.Orders.Add(order);
|
||||
await _context.SaveChangesAsync(ct);
|
||||
|
||||
await _context.OrderItems.AddRangeAsync(items, ct);
|
||||
await _context.SaveChangesAsync(ct);
|
||||
|
||||
await _paymentService.ProcessAsync(order.Id, ct);
|
||||
|
||||
await transaction.CommitAsync(ct);
|
||||
}
|
||||
catch
|
||||
{
|
||||
await transaction.RollbackAsync(ct);
|
||||
throw;
|
||||
}
|
||||
```
|
||||
|
||||
## Indexing Strategy
|
||||
|
||||
### 12. Create Indexes for Query Patterns
|
||||
|
||||
```csharp
|
||||
public class ProductConfiguration : IEntityTypeConfiguration<Product>
|
||||
{
|
||||
public void Configure(EntityTypeBuilder<Product> builder)
|
||||
{
|
||||
// Unique index
|
||||
builder.HasIndex(p => p.Sku)
|
||||
.IsUnique();
|
||||
|
||||
// Composite index for common query patterns
|
||||
builder.HasIndex(p => new { p.CategoryId, p.Name });
|
||||
|
||||
// Filtered index (SQL Server)
|
||||
builder.HasIndex(p => p.Price)
|
||||
.HasFilter("[IsDeleted] = 0");
|
||||
|
||||
// Include columns for covering index
|
||||
builder.HasIndex(p => p.CategoryId)
|
||||
.IncludeProperties(p => new { p.Name, p.Price });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Anti-Patterns to Avoid
|
||||
|
||||
### ❌ Calling ToList() Too Early
|
||||
|
||||
```csharp
|
||||
// ❌ Bad - Materializes all products then filters in memory
|
||||
var products = _context.Products.ToList()
|
||||
.Where(p => p.Price > 100);
|
||||
|
||||
// ✅ Good - Filter in SQL
|
||||
var products = await _context.Products
|
||||
.Where(p => p.Price > 100)
|
||||
.ToListAsync(ct);
|
||||
```
|
||||
|
||||
### ❌ Using Contains with Large Collections
|
||||
|
||||
```csharp
|
||||
// ❌ Bad - Generates massive IN clause
|
||||
var ids = GetThousandsOfIds();
|
||||
var products = await _context.Products
|
||||
.Where(p => ids.Contains(p.Id))
|
||||
.ToListAsync(ct);
|
||||
|
||||
// ✅ Good - Use temp table or batch queries
|
||||
var products = new List<Product>();
|
||||
foreach (var batch in ids.Chunk(100))
|
||||
{
|
||||
var batchResults = await _context.Products
|
||||
.Where(p => batch.Contains(p.Id))
|
||||
.ToListAsync(ct);
|
||||
products.AddRange(batchResults);
|
||||
}
|
||||
```
|
||||
|
||||
### ❌ String Concatenation in Queries
|
||||
|
||||
```csharp
|
||||
// ❌ Bad - Can't use index
|
||||
var products = await _context.Products
|
||||
.Where(p => (p.FirstName + " " + p.LastName).Contains(searchTerm))
|
||||
.ToListAsync(ct);
|
||||
|
||||
// ✅ Good - Use computed column with index
|
||||
builder.Property(p => p.FullName)
|
||||
.HasComputedColumnSql("[FirstName] + ' ' + [LastName]");
|
||||
builder.HasIndex(p => p.FullName);
|
||||
```
|
||||
|
||||
## Monitoring and Diagnostics
|
||||
|
||||
```csharp
|
||||
// Log slow queries
|
||||
services.AddDbContext<AppDbContext>(options =>
|
||||
{
|
||||
options.UseSqlServer(connectionString);
|
||||
|
||||
options.LogTo(
|
||||
filter: (eventId, level) => eventId.Id == CoreEventId.QueryExecutionPlanned.Id,
|
||||
logger: (eventData) =>
|
||||
{
|
||||
if (eventData is QueryExpressionEventData queryData)
|
||||
{
|
||||
var duration = queryData.Duration;
|
||||
if (duration > TimeSpan.FromSeconds(1))
|
||||
{
|
||||
_logger.LogWarning("Slow query detected: {Duration}ms - {Query}",
|
||||
duration.TotalMilliseconds,
|
||||
queryData.Expression);
|
||||
}
|
||||
}
|
||||
});
|
||||
});
|
||||
```
|
||||
@@ -0,0 +1,801 @@
|
||||
# .NET Backend Development Patterns Implementation Playbook
|
||||
|
||||
This file contains detailed patterns, checklists, and code samples referenced by the skill.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### 1. Project Structure (Clean Architecture)
|
||||
|
||||
```
|
||||
src/
|
||||
├── Domain/ # Core business logic (no dependencies)
|
||||
│ ├── Entities/
|
||||
│ ├── Interfaces/
|
||||
│ ├── Exceptions/
|
||||
│ └── ValueObjects/
|
||||
├── Application/ # Use cases, DTOs, validation
|
||||
│ ├── Services/
|
||||
│ ├── DTOs/
|
||||
│ ├── Validators/
|
||||
│ └── Interfaces/
|
||||
├── Infrastructure/ # External implementations
|
||||
│ ├── Data/ # EF Core, Dapper repositories
|
||||
│ ├── Caching/ # Redis, Memory cache
|
||||
│ ├── External/ # HTTP clients, third-party APIs
|
||||
│ └── DependencyInjection/ # Service registration
|
||||
└── Api/ # Entry point
|
||||
├── Controllers/ # Or MinimalAPI endpoints
|
||||
├── Middleware/
|
||||
├── Filters/
|
||||
└── Program.cs
|
||||
```
|
||||
|
||||
### 2. Dependency Injection Patterns
|
||||
|
||||
```csharp
|
||||
// Service registration by lifetime
|
||||
public static class ServiceCollectionExtensions
|
||||
{
|
||||
public static IServiceCollection AddApplicationServices(
|
||||
this IServiceCollection services,
|
||||
IConfiguration configuration)
|
||||
{
|
||||
// Scoped: One instance per HTTP request
|
||||
services.AddScoped<IProductService, ProductService>();
|
||||
services.AddScoped<IOrderService, OrderService>();
|
||||
|
||||
// Singleton: One instance for app lifetime
|
||||
services.AddSingleton<ICacheService, RedisCacheService>();
|
||||
services.AddSingleton<IConnectionMultiplexer>(_ =>
|
||||
ConnectionMultiplexer.Connect(configuration["Redis:Connection"]!));
|
||||
|
||||
// Transient: New instance every time
|
||||
services.AddTransient<IValidator<CreateOrderRequest>, CreateOrderValidator>();
|
||||
|
||||
// Options pattern for configuration
|
||||
services.Configure<CatalogOptions>(configuration.GetSection("Catalog"));
|
||||
services.Configure<RedisOptions>(configuration.GetSection("Redis"));
|
||||
|
||||
// Factory pattern for conditional creation
|
||||
services.AddScoped<IPriceCalculator>(sp =>
|
||||
{
|
||||
var options = sp.GetRequiredService<IOptions<PricingOptions>>().Value;
|
||||
return options.UseNewEngine
|
||||
? sp.GetRequiredService<NewPriceCalculator>()
|
||||
: sp.GetRequiredService<LegacyPriceCalculator>();
|
||||
});
|
||||
|
||||
// Keyed services (.NET 8+)
|
||||
services.AddKeyedScoped<IPaymentProcessor, StripeProcessor>("stripe");
|
||||
services.AddKeyedScoped<IPaymentProcessor, PayPalProcessor>("paypal");
|
||||
|
||||
return services;
|
||||
}
|
||||
}
|
||||
|
||||
// Usage with keyed services
|
||||
public class CheckoutService
|
||||
{
|
||||
public CheckoutService(
|
||||
[FromKeyedServices("stripe")] IPaymentProcessor stripeProcessor)
|
||||
{
|
||||
_processor = stripeProcessor;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Async/Await Patterns
|
||||
|
||||
```csharp
|
||||
// ✅ CORRECT: Async all the way down
|
||||
public async Task<Product> GetProductAsync(string id, CancellationToken ct = default)
|
||||
{
|
||||
return await _repository.GetByIdAsync(id, ct);
|
||||
}
|
||||
|
||||
// ✅ CORRECT: Parallel execution with WhenAll
|
||||
public async Task<(Stock, Price)> GetStockAndPriceAsync(
|
||||
string productId,
|
||||
CancellationToken ct = default)
|
||||
{
|
||||
var stockTask = _stockService.GetAsync(productId, ct);
|
||||
var priceTask = _priceService.GetAsync(productId, ct);
|
||||
|
||||
await Task.WhenAll(stockTask, priceTask);
|
||||
|
||||
return (await stockTask, await priceTask);
|
||||
}
|
||||
|
||||
// ✅ CORRECT: ConfigureAwait in libraries
|
||||
public async Task<T> LibraryMethodAsync<T>(CancellationToken ct = default)
|
||||
{
|
||||
var result = await _httpClient.GetAsync(url, ct).ConfigureAwait(false);
|
||||
return await result.Content.ReadFromJsonAsync<T>(ct).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
// ✅ CORRECT: ValueTask for hot paths with caching
|
||||
public ValueTask<Product?> GetCachedProductAsync(string id)
|
||||
{
|
||||
if (_cache.TryGetValue(id, out Product? product))
|
||||
return ValueTask.FromResult(product);
|
||||
|
||||
return new ValueTask<Product?>(GetFromDatabaseAsync(id));
|
||||
}
|
||||
|
||||
// ❌ WRONG: Blocking on async (deadlock risk)
|
||||
var result = GetProductAsync(id).Result; // NEVER do this
|
||||
var result2 = GetProductAsync(id).GetAwaiter().GetResult(); // Also bad
|
||||
|
||||
// ❌ WRONG: async void (except event handlers)
|
||||
public async void ProcessOrder() { } // Exceptions are lost
|
||||
|
||||
// ❌ WRONG: Unnecessary Task.Run for already async code
|
||||
await Task.Run(async () => await GetDataAsync()); // Wastes thread
|
||||
```
|
||||
|
||||
### 4. Configuration with IOptions
|
||||
|
||||
```csharp
|
||||
// Configuration classes
|
||||
public class CatalogOptions
|
||||
{
|
||||
public const string SectionName = "Catalog";
|
||||
|
||||
public int DefaultPageSize { get; set; } = 50;
|
||||
public int MaxPageSize { get; set; } = 200;
|
||||
public TimeSpan CacheDuration { get; set; } = TimeSpan.FromMinutes(15);
|
||||
public bool EnableEnrichment { get; set; } = true;
|
||||
}
|
||||
|
||||
public class RedisOptions
|
||||
{
|
||||
public const string SectionName = "Redis";
|
||||
|
||||
public string Connection { get; set; } = "localhost:6379";
|
||||
public string KeyPrefix { get; set; } = "mcp:";
|
||||
public int Database { get; set; } = 0;
|
||||
}
|
||||
|
||||
// appsettings.json
|
||||
{
|
||||
"Catalog": {
|
||||
"DefaultPageSize": 50,
|
||||
"MaxPageSize": 200,
|
||||
"CacheDuration": "00:15:00",
|
||||
"EnableEnrichment": true
|
||||
},
|
||||
"Redis": {
|
||||
"Connection": "localhost:6379",
|
||||
"KeyPrefix": "mcp:",
|
||||
"Database": 0
|
||||
}
|
||||
}
|
||||
|
||||
// Registration
|
||||
services.Configure<CatalogOptions>(configuration.GetSection(CatalogOptions.SectionName));
|
||||
services.Configure<RedisOptions>(configuration.GetSection(RedisOptions.SectionName));
|
||||
|
||||
// Usage with IOptions (singleton, read once at startup)
|
||||
public class CatalogService
|
||||
{
|
||||
private readonly CatalogOptions _options;
|
||||
|
||||
public CatalogService(IOptions<CatalogOptions> options)
|
||||
{
|
||||
_options = options.Value;
|
||||
}
|
||||
}
|
||||
|
||||
// Usage with IOptionsSnapshot (scoped, re-reads on each request)
|
||||
public class DynamicService
|
||||
{
|
||||
private readonly CatalogOptions _options;
|
||||
|
||||
public DynamicService(IOptionsSnapshot<CatalogOptions> options)
|
||||
{
|
||||
_options = options.Value; // Fresh value per request
|
||||
}
|
||||
}
|
||||
|
||||
// Usage with IOptionsMonitor (singleton, notified on changes)
|
||||
public class MonitoredService
|
||||
{
|
||||
private CatalogOptions _options;
|
||||
|
||||
public MonitoredService(IOptionsMonitor<CatalogOptions> monitor)
|
||||
{
|
||||
_options = monitor.CurrentValue;
|
||||
monitor.OnChange(newOptions => _options = newOptions);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Result Pattern (Avoiding Exceptions for Flow Control)
|
||||
|
||||
```csharp
|
||||
// Generic Result type
|
||||
public class Result<T>
|
||||
{
|
||||
public bool IsSuccess { get; }
|
||||
public T? Value { get; }
|
||||
public string? Error { get; }
|
||||
public string? ErrorCode { get; }
|
||||
|
||||
private Result(bool isSuccess, T? value, string? error, string? errorCode)
|
||||
{
|
||||
IsSuccess = isSuccess;
|
||||
Value = value;
|
||||
Error = error;
|
||||
ErrorCode = errorCode;
|
||||
}
|
||||
|
||||
public static Result<T> Success(T value) => new(true, value, null, null);
|
||||
public static Result<T> Failure(string error, string? code = null) => new(false, default, error, code);
|
||||
|
||||
public Result<TNew> Map<TNew>(Func<T, TNew> mapper) =>
|
||||
IsSuccess ? Result<TNew>.Success(mapper(Value!)) : Result<TNew>.Failure(Error!, ErrorCode);
|
||||
|
||||
public async Task<Result<TNew>> MapAsync<TNew>(Func<T, Task<TNew>> mapper) =>
|
||||
IsSuccess ? Result<TNew>.Success(await mapper(Value!)) : Result<TNew>.Failure(Error!, ErrorCode);
|
||||
}
|
||||
|
||||
// Usage in service
|
||||
public async Task<Result<Order>> CreateOrderAsync(CreateOrderRequest request, CancellationToken ct)
|
||||
{
|
||||
// Validation
|
||||
var validation = await _validator.ValidateAsync(request, ct);
|
||||
if (!validation.IsValid)
|
||||
return Result<Order>.Failure(
|
||||
validation.Errors.First().ErrorMessage,
|
||||
"VALIDATION_ERROR");
|
||||
|
||||
// Business rule check
|
||||
var stock = await _stockService.CheckAsync(request.ProductId, request.Quantity, ct);
|
||||
if (!stock.IsAvailable)
|
||||
return Result<Order>.Failure(
|
||||
$"Insufficient stock: {stock.Available} available, {request.Quantity} requested",
|
||||
"INSUFFICIENT_STOCK");
|
||||
|
||||
// Create order
|
||||
var order = await _repository.CreateAsync(request.ToEntity(), ct);
|
||||
|
||||
return Result<Order>.Success(order);
|
||||
}
|
||||
|
||||
// Usage in controller/endpoint
|
||||
app.MapPost("/orders", async (
|
||||
CreateOrderRequest request,
|
||||
IOrderService orderService,
|
||||
CancellationToken ct) =>
|
||||
{
|
||||
var result = await orderService.CreateOrderAsync(request, ct);
|
||||
|
||||
return result.IsSuccess
|
||||
? Results.Created($"/orders/{result.Value!.Id}", result.Value)
|
||||
: Results.BadRequest(new { error = result.Error, code = result.ErrorCode });
|
||||
});
|
||||
```
|
||||
|
||||
## Data Access Patterns
|
||||
|
||||
### Entity Framework Core
|
||||
|
||||
```csharp
|
||||
// DbContext configuration
|
||||
public class AppDbContext : DbContext
|
||||
{
|
||||
public DbSet<Product> Products => Set<Product>();
|
||||
public DbSet<Order> Orders => Set<Order>();
|
||||
|
||||
protected override void OnModelCreating(ModelBuilder modelBuilder)
|
||||
{
|
||||
// Apply all configurations from assembly
|
||||
modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);
|
||||
|
||||
// Global query filters
|
||||
modelBuilder.Entity<Product>().HasQueryFilter(p => !p.IsDeleted);
|
||||
}
|
||||
}
|
||||
|
||||
// Entity configuration
|
||||
public class ProductConfiguration : IEntityTypeConfiguration<Product>
|
||||
{
|
||||
public void Configure(EntityTypeBuilder<Product> builder)
|
||||
{
|
||||
builder.ToTable("Products");
|
||||
|
||||
builder.HasKey(p => p.Id);
|
||||
builder.Property(p => p.Id).HasMaxLength(40);
|
||||
builder.Property(p => p.Name).HasMaxLength(200).IsRequired();
|
||||
builder.Property(p => p.Price).HasPrecision(18, 2);
|
||||
|
||||
builder.HasIndex(p => p.Sku).IsUnique();
|
||||
builder.HasIndex(p => new { p.CategoryId, p.Name });
|
||||
|
||||
builder.HasMany(p => p.OrderItems)
|
||||
.WithOne(oi => oi.Product)
|
||||
.HasForeignKey(oi => oi.ProductId);
|
||||
}
|
||||
}
|
||||
|
||||
// Repository with EF Core
|
||||
public class ProductRepository : IProductRepository
|
||||
{
|
||||
private readonly AppDbContext _context;
|
||||
|
||||
public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)
|
||||
{
|
||||
return await _context.Products
|
||||
.AsNoTracking()
|
||||
.FirstOrDefaultAsync(p => p.Id == id, ct);
|
||||
}
|
||||
|
||||
public async Task<IReadOnlyList<Product>> SearchAsync(
|
||||
ProductSearchCriteria criteria,
|
||||
CancellationToken ct = default)
|
||||
{
|
||||
var query = _context.Products.AsNoTracking();
|
||||
|
||||
if (!string.IsNullOrWhiteSpace(criteria.SearchTerm))
|
||||
query = query.Where(p => EF.Functions.Like(p.Name, $"%{criteria.SearchTerm}%"));
|
||||
|
||||
if (criteria.CategoryId.HasValue)
|
||||
query = query.Where(p => p.CategoryId == criteria.CategoryId);
|
||||
|
||||
if (criteria.MinPrice.HasValue)
|
||||
query = query.Where(p => p.Price >= criteria.MinPrice);
|
||||
|
||||
if (criteria.MaxPrice.HasValue)
|
||||
query = query.Where(p => p.Price <= criteria.MaxPrice);
|
||||
|
||||
return await query
|
||||
.OrderBy(p => p.Name)
|
||||
.Skip((criteria.Page - 1) * criteria.PageSize)
|
||||
.Take(criteria.PageSize)
|
||||
.ToListAsync(ct);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Dapper for Performance
|
||||
|
||||
```csharp
|
||||
public class DapperProductRepository : IProductRepository
|
||||
{
|
||||
private readonly IDbConnection _connection;
|
||||
|
||||
public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)
|
||||
{
|
||||
const string sql = """
|
||||
SELECT Id, Name, Sku, Price, CategoryId, Stock, CreatedAt
|
||||
FROM Products
|
||||
WHERE Id = @Id AND IsDeleted = 0
|
||||
""";
|
||||
|
||||
return await _connection.QueryFirstOrDefaultAsync<Product>(
|
||||
new CommandDefinition(sql, new { Id = id }, cancellationToken: ct));
|
||||
}
|
||||
|
||||
public async Task<IReadOnlyList<Product>> SearchAsync(
|
||||
ProductSearchCriteria criteria,
|
||||
CancellationToken ct = default)
|
||||
{
|
||||
var sql = new StringBuilder("""
|
||||
SELECT Id, Name, Sku, Price, CategoryId, Stock, CreatedAt
|
||||
FROM Products
|
||||
WHERE IsDeleted = 0
|
||||
""");
|
||||
|
||||
var parameters = new DynamicParameters();
|
||||
|
||||
if (!string.IsNullOrWhiteSpace(criteria.SearchTerm))
|
||||
{
|
||||
sql.Append(" AND Name LIKE @SearchTerm");
|
||||
parameters.Add("SearchTerm", $"%{criteria.SearchTerm}%");
|
||||
}
|
||||
|
||||
if (criteria.CategoryId.HasValue)
|
||||
{
|
||||
sql.Append(" AND CategoryId = @CategoryId");
|
||||
parameters.Add("CategoryId", criteria.CategoryId);
|
||||
}
|
||||
|
||||
if (criteria.MinPrice.HasValue)
|
||||
{
|
||||
sql.Append(" AND Price >= @MinPrice");
|
||||
parameters.Add("MinPrice", criteria.MinPrice);
|
||||
}
|
||||
|
||||
if (criteria.MaxPrice.HasValue)
|
||||
{
|
||||
sql.Append(" AND Price <= @MaxPrice");
|
||||
parameters.Add("MaxPrice", criteria.MaxPrice);
|
||||
}
|
||||
|
||||
sql.Append(" ORDER BY Name OFFSET @Offset ROWS FETCH NEXT @PageSize ROWS ONLY");
|
||||
parameters.Add("Offset", (criteria.Page - 1) * criteria.PageSize);
|
||||
parameters.Add("PageSize", criteria.PageSize);
|
||||
|
||||
var results = await _connection.QueryAsync<Product>(
|
||||
new CommandDefinition(sql.ToString(), parameters, cancellationToken: ct));
|
||||
|
||||
return results.ToList();
|
||||
}
|
||||
|
||||
// Multi-mapping for related data
|
||||
public async Task<Order?> GetOrderWithItemsAsync(int orderId, CancellationToken ct = default)
|
||||
{
|
||||
const string sql = """
|
||||
SELECT o.*, oi.*, p.*
|
||||
FROM Orders o
|
||||
LEFT JOIN OrderItems oi ON o.Id = oi.OrderId
|
||||
LEFT JOIN Products p ON oi.ProductId = p.Id
|
||||
WHERE o.Id = @OrderId
|
||||
""";
|
||||
|
||||
var orderDictionary = new Dictionary<int, Order>();
|
||||
|
||||
await _connection.QueryAsync<Order, OrderItem, Product, Order>(
|
||||
new CommandDefinition(sql, new { OrderId = orderId }, cancellationToken: ct),
|
||||
(order, item, product) =>
|
||||
{
|
||||
if (!orderDictionary.TryGetValue(order.Id, out var existingOrder))
|
||||
{
|
||||
existingOrder = order;
|
||||
existingOrder.Items = new List<OrderItem>();
|
||||
orderDictionary.Add(order.Id, existingOrder);
|
||||
}
|
||||
|
||||
if (item != null)
|
||||
{
|
||||
item.Product = product;
|
||||
existingOrder.Items.Add(item);
|
||||
}
|
||||
|
||||
return existingOrder;
|
||||
},
|
||||
splitOn: "Id,Id");
|
||||
|
||||
return orderDictionary.Values.FirstOrDefault();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Caching Patterns
|
||||
|
||||
### Multi-Level Cache with Redis
|
||||
|
||||
```csharp
|
||||
public class CachedProductService : IProductService
|
||||
{
|
||||
private readonly IProductRepository _repository;
|
||||
private readonly IMemoryCache _memoryCache;
|
||||
private readonly IDistributedCache _distributedCache;
|
||||
private readonly ILogger<CachedProductService> _logger;
|
||||
|
||||
private static readonly TimeSpan MemoryCacheDuration = TimeSpan.FromMinutes(1);
|
||||
private static readonly TimeSpan DistributedCacheDuration = TimeSpan.FromMinutes(15);
|
||||
|
||||
public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)
|
||||
{
|
||||
var cacheKey = $"product:{id}";
|
||||
|
||||
// L1: Memory cache (in-process, fastest)
|
||||
if (_memoryCache.TryGetValue(cacheKey, out Product? cached))
|
||||
{
|
||||
_logger.LogDebug("L1 cache hit for {CacheKey}", cacheKey);
|
||||
return cached;
|
||||
}
|
||||
|
||||
// L2: Distributed cache (Redis)
|
||||
var distributed = await _distributedCache.GetStringAsync(cacheKey, ct);
|
||||
if (distributed != null)
|
||||
{
|
||||
_logger.LogDebug("L2 cache hit for {CacheKey}", cacheKey);
|
||||
var product = JsonSerializer.Deserialize<Product>(distributed);
|
||||
|
||||
// Populate L1
|
||||
_memoryCache.Set(cacheKey, product, MemoryCacheDuration);
|
||||
return product;
|
||||
}
|
||||
|
||||
// L3: Database
|
||||
_logger.LogDebug("Cache miss for {CacheKey}, fetching from database", cacheKey);
|
||||
var fromDb = await _repository.GetByIdAsync(id, ct);
|
||||
|
||||
if (fromDb != null)
|
||||
{
|
||||
var serialized = JsonSerializer.Serialize(fromDb);
|
||||
|
||||
// Populate both caches
|
||||
await _distributedCache.SetStringAsync(
|
||||
cacheKey,
|
||||
serialized,
|
||||
new DistributedCacheEntryOptions
|
||||
{
|
||||
AbsoluteExpirationRelativeToNow = DistributedCacheDuration
|
||||
},
|
||||
ct);
|
||||
|
||||
_memoryCache.Set(cacheKey, fromDb, MemoryCacheDuration);
|
||||
}
|
||||
|
||||
return fromDb;
|
||||
}
|
||||
|
||||
public async Task InvalidateAsync(string id, CancellationToken ct = default)
|
||||
{
|
||||
var cacheKey = $"product:{id}";
|
||||
|
||||
_memoryCache.Remove(cacheKey);
|
||||
await _distributedCache.RemoveAsync(cacheKey, ct);
|
||||
|
||||
_logger.LogInformation("Invalidated cache for {CacheKey}", cacheKey);
|
||||
}
|
||||
}
|
||||
|
||||
// Stale-while-revalidate pattern
|
||||
public class StaleWhileRevalidateCache<T>
|
||||
{
|
||||
private readonly IDistributedCache _cache;
|
||||
private readonly TimeSpan _freshDuration;
|
||||
private readonly TimeSpan _staleDuration;
|
||||
|
||||
public async Task<T?> GetOrCreateAsync(
|
||||
string key,
|
||||
Func<CancellationToken, Task<T>> factory,
|
||||
CancellationToken ct = default)
|
||||
{
|
||||
var cached = await _cache.GetStringAsync(key, ct);
|
||||
|
||||
if (cached != null)
|
||||
{
|
||||
var entry = JsonSerializer.Deserialize<CacheEntry<T>>(cached)!;
|
||||
|
||||
if (entry.IsStale && !entry.IsExpired)
|
||||
{
|
||||
// Return stale data immediately, refresh in background
|
||||
_ = Task.Run(async () =>
|
||||
{
|
||||
var fresh = await factory(CancellationToken.None);
|
||||
await SetAsync(key, fresh, CancellationToken.None);
|
||||
});
|
||||
}
|
||||
|
||||
if (!entry.IsExpired)
|
||||
return entry.Value;
|
||||
}
|
||||
|
||||
// Cache miss or expired
|
||||
var value = await factory(ct);
|
||||
await SetAsync(key, value, ct);
|
||||
return value;
|
||||
}
|
||||
|
||||
private record CacheEntry<TValue>(TValue Value, DateTime CreatedAt)
|
||||
{
|
||||
public bool IsStale => DateTime.UtcNow - CreatedAt > _freshDuration;
|
||||
public bool IsExpired => DateTime.UtcNow - CreatedAt > _staleDuration;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Patterns
|
||||
|
||||
### Unit Tests with xUnit and Moq
|
||||
|
||||
```csharp
|
||||
public class OrderServiceTests
|
||||
{
|
||||
private readonly Mock<IOrderRepository> _mockRepository;
|
||||
private readonly Mock<IStockService> _mockStockService;
|
||||
private readonly Mock<IValidator<CreateOrderRequest>> _mockValidator;
|
||||
private readonly OrderService _sut; // System Under Test
|
||||
|
||||
public OrderServiceTests()
|
||||
{
|
||||
_mockRepository = new Mock<IOrderRepository>();
|
||||
_mockStockService = new Mock<IStockService>();
|
||||
_mockValidator = new Mock<IValidator<CreateOrderRequest>>();
|
||||
|
||||
// Default: validation passes
|
||||
_mockValidator
|
||||
.Setup(v => v.ValidateAsync(It.IsAny<CreateOrderRequest>(), It.IsAny<CancellationToken>()))
|
||||
.ReturnsAsync(new ValidationResult());
|
||||
|
||||
_sut = new OrderService(
|
||||
_mockRepository.Object,
|
||||
_mockStockService.Object,
|
||||
_mockValidator.Object);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task CreateOrderAsync_WithValidRequest_ReturnsSuccess()
|
||||
{
|
||||
// Arrange
|
||||
var request = new CreateOrderRequest
|
||||
{
|
||||
ProductId = "PROD-001",
|
||||
Quantity = 5,
|
||||
CustomerOrderCode = "ORD-2024-001"
|
||||
};
|
||||
|
||||
_mockStockService
|
||||
.Setup(s => s.CheckAsync("PROD-001", 5, It.IsAny<CancellationToken>()))
|
||||
.ReturnsAsync(new StockResult { IsAvailable = true, Available = 10 });
|
||||
|
||||
_mockRepository
|
||||
.Setup(r => r.CreateAsync(It.IsAny<Order>(), It.IsAny<CancellationToken>()))
|
||||
.ReturnsAsync(new Order { Id = 1, CustomerOrderCode = "ORD-2024-001" });
|
||||
|
||||
// Act
|
||||
var result = await _sut.CreateOrderAsync(request);
|
||||
|
||||
// Assert
|
||||
Assert.True(result.IsSuccess);
|
||||
Assert.NotNull(result.Value);
|
||||
Assert.Equal(1, result.Value.Id);
|
||||
|
||||
_mockRepository.Verify(
|
||||
r => r.CreateAsync(It.Is<Order>(o => o.CustomerOrderCode == "ORD-2024-001"),
|
||||
It.IsAny<CancellationToken>()),
|
||||
Times.Once);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task CreateOrderAsync_WithInsufficientStock_ReturnsFailure()
|
||||
{
|
||||
// Arrange
|
||||
var request = new CreateOrderRequest { ProductId = "PROD-001", Quantity = 100 };
|
||||
|
||||
_mockStockService
|
||||
.Setup(s => s.CheckAsync(It.IsAny<string>(), It.IsAny<int>(), It.IsAny<CancellationToken>()))
|
||||
.ReturnsAsync(new StockResult { IsAvailable = false, Available = 5 });
|
||||
|
||||
// Act
|
||||
var result = await _sut.CreateOrderAsync(request);
|
||||
|
||||
// Assert
|
||||
Assert.False(result.IsSuccess);
|
||||
Assert.Equal("INSUFFICIENT_STOCK", result.ErrorCode);
|
||||
Assert.Contains("5 available", result.Error);
|
||||
|
||||
_mockRepository.Verify(
|
||||
r => r.CreateAsync(It.IsAny<Order>(), It.IsAny<CancellationToken>()),
|
||||
Times.Never);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData(0)]
|
||||
[InlineData(-1)]
|
||||
[InlineData(-100)]
|
||||
public async Task CreateOrderAsync_WithInvalidQuantity_ReturnsValidationError(int quantity)
|
||||
{
|
||||
// Arrange
|
||||
var request = new CreateOrderRequest { ProductId = "PROD-001", Quantity = quantity };
|
||||
|
||||
_mockValidator
|
||||
.Setup(v => v.ValidateAsync(request, It.IsAny<CancellationToken>()))
|
||||
.ReturnsAsync(new ValidationResult(new[]
|
||||
{
|
||||
new ValidationFailure("Quantity", "Quantity must be greater than 0")
|
||||
}));
|
||||
|
||||
// Act
|
||||
var result = await _sut.CreateOrderAsync(request);
|
||||
|
||||
// Assert
|
||||
Assert.False(result.IsSuccess);
|
||||
Assert.Equal("VALIDATION_ERROR", result.ErrorCode);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Integration Tests with WebApplicationFactory
|
||||
|
||||
```csharp
|
||||
public class ProductsApiTests : IClassFixture<WebApplicationFactory<Program>>
|
||||
{
|
||||
private readonly WebApplicationFactory<Program> _factory;
|
||||
private readonly HttpClient _client;
|
||||
|
||||
public ProductsApiTests(WebApplicationFactory<Program> factory)
|
||||
{
|
||||
_factory = factory.WithWebHostBuilder(builder =>
|
||||
{
|
||||
builder.ConfigureServices(services =>
|
||||
{
|
||||
// Replace real database with in-memory
|
||||
services.RemoveAll<DbContextOptions<AppDbContext>>();
|
||||
services.AddDbContext<AppDbContext>(options =>
|
||||
options.UseInMemoryDatabase("TestDb"));
|
||||
|
||||
// Replace Redis with memory cache
|
||||
services.RemoveAll<IDistributedCache>();
|
||||
services.AddDistributedMemoryCache();
|
||||
});
|
||||
});
|
||||
|
||||
_client = _factory.CreateClient();
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task GetProduct_WithValidId_ReturnsProduct()
|
||||
{
|
||||
// Arrange
|
||||
using var scope = _factory.Services.CreateScope();
|
||||
var context = scope.ServiceProvider.GetRequiredService<AppDbContext>();
|
||||
|
||||
context.Products.Add(new Product
|
||||
{
|
||||
Id = "TEST-001",
|
||||
Name = "Test Product",
|
||||
Price = 99.99m
|
||||
});
|
||||
await context.SaveChangesAsync();
|
||||
|
||||
// Act
|
||||
var response = await _client.GetAsync("/api/products/TEST-001");
|
||||
|
||||
// Assert
|
||||
response.EnsureSuccessStatusCode();
|
||||
var product = await response.Content.ReadFromJsonAsync<Product>();
|
||||
Assert.Equal("Test Product", product!.Name);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task GetProduct_WithInvalidId_Returns404()
|
||||
{
|
||||
// Act
|
||||
var response = await _client.GetAsync("/api/products/NONEXISTENT");
|
||||
|
||||
// Assert
|
||||
Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### DO
|
||||
|
||||
1. **Use async/await** all the way through the call stack
|
||||
2. **Inject dependencies** through constructor injection
|
||||
3. **Use IOptions<T>** for typed configuration
|
||||
4. **Return Result types** instead of throwing exceptions for business logic
|
||||
5. **Use CancellationToken** in all async methods
|
||||
6. **Prefer Dapper** for read-heavy, performance-critical queries
|
||||
7. **Use EF Core** for complex domain models with change tracking
|
||||
8. **Cache aggressively** with proper invalidation strategies
|
||||
9. **Write unit tests** for business logic, integration tests for APIs
|
||||
10. **Use record types** for DTOs and immutable data
|
||||
|
||||
### DON'T
|
||||
|
||||
1. **Don't block on async** with `.Result` or `.Wait()`
|
||||
2. **Don't use async void** except for event handlers
|
||||
3. **Don't catch generic Exception** without re-throwing or logging
|
||||
4. **Don't hardcode** configuration values
|
||||
5. **Don't expose EF entities** directly in APIs (use DTOs)
|
||||
6. **Don't forget** `AsNoTracking()` for read-only queries
|
||||
7. **Don't ignore** CancellationToken parameters
|
||||
8. **Don't create** `new HttpClient()` manually (use IHttpClientFactory)
|
||||
9. **Don't mix** sync and async code unnecessarily
|
||||
10. **Don't skip** validation at API boundaries
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **N+1 Queries**: Use `.Include()` or explicit joins
|
||||
- **Memory Leaks**: Dispose IDisposable resources, use `using`
|
||||
- **Deadlocks**: Don't mix sync and async, use ConfigureAwait(false) in libraries
|
||||
- **Over-fetching**: Select only needed columns, use projections
|
||||
- **Missing Indexes**: Check query plans, add indexes for common filters
|
||||
- **Timeout Issues**: Configure appropriate timeouts for HTTP clients
|
||||
- **Cache Stampede**: Use distributed locks for cache population
|
||||
|
||||
## Resources
|
||||
|
||||
- **assets/service-template.cs.template**: Complete service implementation template
|
||||
- **assets/repository-template.cs.template**: Repository pattern implementation
|
||||
- **references/ef-core-best-practices.md**: EF Core optimization guide
|
||||
- **references/dapper-patterns.md**: Advanced Dapper usage patterns
|
||||
Reference in New Issue
Block a user