Enterprise ASP.NET Core Web API with Clean Architecture

namespace ECommerce.Infrastructure.Services
{
    public class JwtService : IJwtService
    {
        private readonly IConfiguration _configuration;
        private readonly ILogger<JwtService> _logger;
        
        public JwtService(IConfiguration configuration, ILogger<JwtService> logger)
        {
            _configuration = configuration;
            _logger = logger;
        }
        
        public string GenerateJwtToken(User user)
        {
            try
            {
                var tokenHandler = new JwtSecurityTokenHandler();
                var key = Encoding.ASCII.GetBytes(_configuration["Jwt:Secret"]);
                
                var claims = new List<Claim>
                {
                    new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()),
                    new Claim(ClaimTypes.Name, user.UserName),
                    new Claim(ClaimTypes.Email, user.Email)
                };
                
                var tokenDescriptor = new SecurityTokenDescriptor
                {
                    Subject = new ClaimsIdentity(claims),
                    Expires = DateTime.UtcNow.AddMinutes(Convert.ToDouble(_configuration["Jwt:ExpiryMinutes"])),
                    SigningCredentials = new SigningCredentials(
                        new SymmetricSecurityKey(key),
                        SecurityAlgorithms.HmacSha256Signature)
                };
                
                var token = tokenHandler.CreateToken(tokenDescriptor);
                return tokenHandler.WriteToken(token);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error generating JWT token");
                throw;
            }
        }
        
        public Guid? ValidateJwtToken(string token)
        {
            if (string.IsNullOrEmpty(token))
                return null;
                
            var tokenHandler = new JwtSecurityTokenHandler();
            var key = Encoding.ASCII.GetBytes(_configuration["Jwt:Secret"]);
            
            try
            {
                tokenHandler.ValidateToken(token, new TokenValidationParameters
                {
                    ValidateIssuerSigningKey = true,
                    IssuerSigningKey = new SymmetricSecurityKey(key),
                    ValidateIssuer = false,
                    ValidateAudience = false,
                    ClockSkew = TimeSpan.Zero
                }, out SecurityToken validatedToken);
                
                var jwtToken = (JwtSecurityToken)validatedToken;
                var userId = Guid.Parse(jwtToken.Claims.First(x => x.Type == ClaimTypes.NameIdentifier).Value);
                
                return userId;
            }
            catch
            {
                return null;
            }
        }
    }
}

6.2 Refresh Token Service

namespace ECommerce.Infrastructure.Services
{
    public class RefreshTokenService : IRefreshTokenService
    {
        private readonly IRefreshTokenRepository _refreshTokenRepository;
        private readonly IConfiguration _configuration;
        private readonly ILogger<RefreshTokenService> _logger;
        
        public RefreshTokenService(
            IRefreshTokenRepository refreshTokenRepository,
            IConfiguration configuration,
            ILogger<RefreshTokenService> logger)
        {
            _refreshTokenRepository = refreshTokenRepository;
            _configuration = configuration;
            _logger = logger;
        }
        
        public async Task<RefreshToken> GenerateRefreshToken(Guid userId, string ipAddress)
        {
            try
            {
                // Remove old refresh tokens
                await _refreshTokenRepository.RemoveOldRefreshTokensForUser(userId);
                
                // Generate new refresh token
                var refreshToken = new RefreshToken
                {
                    UserId = userId,
                    Token = generateRandomToken(),
                    Expires = DateTime.UtcNow.AddDays(Convert.ToDouble(_configuration["Jwt:RefreshTokenExpiryDays"])),
                    Created = DateTime.UtcNow,
                    CreatedByIp = ipAddress
                };
                
                await _refreshTokenRepository.AddAsync(refreshToken);
                
                return refreshToken;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error generating refresh token");
                throw;
            }
        }
        
        public async Task<RefreshToken> RotateRefreshToken(string token, string ipAddress)
        {
            try
            {
                var refreshToken = await _refreshTokenRepository.GetByTokenAsync(token);
                
                if (refreshToken == null || !refreshToken.IsActive)
                    throw new AuthenticationException("Invalid token");
                
                // Revoke current token
                refreshToken.Revoked = DateTime.UtcNow;
                refreshToken.RevokedByIp = ipAddress;
                
                // Generate new token
                var newRefreshToken = new RefreshToken
                {
                    UserId = refreshToken.UserId,
                    Token = generateRandomToken(),
                    Expires = DateTime.UtcNow.AddDays(Convert.ToDouble(_configuration["Jwt:RefreshTokenExpiryDays"])),
                    Created = DateTime.UtcNow,
                    CreatedByIp = ipAddress,
                    ReplacedByToken = refreshToken.Token
                };
                
                await _refreshTokenRepository.UpdateAsync(refreshToken);
                await _refreshTokenRepository.AddAsync(newRefreshToken);
                
                return newRefreshToken;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error rotating refresh token");
                throw;
            }
        }
        
        private string generateRandomToken()
        {
            var randomNumber = new byte[32];
            using var rng = RandomNumberGenerator.Create();
            rng.GetBytes(randomNumber);
            return Convert.ToBase64String(randomNumber);
        }
    }
}

7. Transaction Management

7.1 Transaction Behavior for MediatR

namespace ECommerce.Application.Common.Behaviors
{
    public class TransactionBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
        where TRequest : IRequest<TResponse>
    {
        private readonly IDapperContext _context;
        private readonly ILogger<TransactionBehavior<TRequest, TResponse>> _logger;
        
        public TransactionBehavior(
            IDapperContext context,
            ILogger<TransactionBehavior<TRequest, TResponse>> logger)
        {
            _context = context;
            _logger = logger;
        }
        
        public async Task<TResponse> Handle(
            TRequest request,
            RequestHandlerDelegate<TResponse> next,
            CancellationToken cancellationToken)
        {
            if (request is not ITransactional)
            {
                return await next();
            }
            
            await using var connection = _context.CreateConnection();
            await connection.OpenAsync(cancellationToken);
            
            await using var transaction = await connection.BeginTransactionAsync(cancellationToken);
            
            try
            {
                _logger.LogInformation("Begin transaction for {RequestName}", typeof(TRequest).Name);
                
                var response = await next();
                
                await transaction.CommitAsync(cancellationToken);
                
                _logger.LogInformation("Transaction committed for {RequestName}", typeof(TRequest).Name);
                
                return response;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error handling transaction for {RequestName}", typeof(TRequest).Name);
                
                await transaction.RollbackAsync(cancellationToken);
                
                throw;
            }
        }
    }
}

7.2 Using Transactions with Dapper

namespace ECommerce.Infrastructure.Data.Repositories
{
    public class InvoiceRepository : IInvoiceRepository
    {
        // ... other methods
        
        public async Task<Invoice> CreateInvoiceWithTransactionAsync(
            string invoiceNumber,
            Guid customerId,
            DateTime invoiceDate,
            DateTime dueDate,
            string notes,
            Guid createdBy,
            DataTable items)
        {
            const string headerSql = @"
                INSERT INTO Invoices (...) VALUES (...);
                SELECT SCOPE_IDENTITY();";
                
            const string itemsSql = @"
                INSERT INTO InvoiceItems (...) VALUES (...);";
                
            try
            {
                return await _context.WithConnection(async conn =>
                {
                    await using var transaction = await conn.BeginTransactionAsync();
                    
                    try
                    {
                        // Insert header
                        var invoiceId = await conn.ExecuteScalarAsync<Guid>(headerSql, new
                        {
                            InvoiceNumber = invoiceNumber,
                            CustomerId = customerId,
                            // ... other parameters
                        }, transaction: transaction);
                        
                        // Insert items
                        foreach (DataRow row in items.Rows)
                        {
                            await conn.ExecuteAsync(itemsSql, new
                            {
                                InvoiceId = invoiceId,
                                ItemName = row["ItemName"],
                                // ... other parameters
                            }, transaction: transaction);
                        }
                        
                        await transaction.CommitAsync();
                        
                        return await GetInvoiceByIdAsync(invoiceId);
                    }
                    catch
                    {
                        await transaction.RollbackAsync();
                        throw;
                    }
                });
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error creating invoice with transaction");
                throw;
            }
        }
    }
}

8. Large Data Handling

8.1 Pagination with Dapper

namespace ECommerce.Infrastructure.Data.Repositories
{
    public class InvoiceRepository : IInvoiceRepository
    {
        // ... other methods
        
        public async Task<PagedList<Invoice>> GetInvoicesPagedAsync(
            int pageNumber,
            int pageSize,
            string searchTerm = null,
            string sortColumn = null,
            string sortOrder = "asc")
        {
            const string baseSql = @"
                SELECT * FROM Invoices
                WHERE (@SearchTerm IS NULL OR 
                      InvoiceNumber LIKE '%' + @SearchTerm + '%' OR
                      Notes LIKE '%' + @SearchTerm + '%')";
                      
            const string countSql = @"
                SELECT COUNT(*) FROM Invoices
                WHERE (@SearchTerm IS NULL OR 
                      InvoiceNumber LIKE '%' + @SearchTerm + '%' OR
                      Notes LIKE '%' + @SearchTerm + '%')";
                      
            var orderBy = !string.IsNullOrWhiteSpace(sortColumn)
                ? $"ORDER BY {sortColumn} {(sortOrder == "desc" ? "DESC" : "ASC")}"
                : "ORDER BY InvoiceDate DESC";
                
            var sql = $@"
                {baseSql}
                {orderBy}
                OFFSET @Offset ROWS FETCH NEXT @PageSize ROWS ONLY";
                
            try
            {
                return await _context.WithConnection(async conn =>
                {
                    var offset = (pageNumber - 1) * pageSize;
                    
                    var parameters = new DynamicParameters();
                    parameters.Add("@SearchTerm", searchTerm);
                    parameters.Add("@Offset", offset);
                    parameters.Add("@PageSize", pageSize);
                    
                    var count = await conn.ExecuteScalarAsync<int>(countSql, parameters);
                    
                    var items = await conn.QueryAsync<Invoice>(sql, parameters);
                    
                    return new PagedList<Invoice>(
                        items.ToList(),
                        count,
                        pageNumber,
                        pageSize);
                });
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error getting paged invoices");
                throw;
            }
        }
    }
}

8.2 Bulk Operations with Table-Valued Parameters

namespace ECommerce.Infrastructure.Data.Repositories
{
    public class BulkOperationsRepository : IBulkOperationsRepository
    {
        private readonly IDapperContext _context;
        private readonly ILogger<BulkOperationsRepository> _logger;
        
        public BulkOperationsRepository(
            IDapperContext context,
            ILogger<BulkOperationsRepository> logger)
        {
            _context = context;
            _logger = logger;
        }
        
        public async Task BulkInsertInvoicesAsync(IEnumerable<Invoice> invoices)
        {
            const string sql = "EXEC [dbo].[usp_BulkInsertInvoices] @Invoices";
            
            try
            {
                var invoiceTable = new DataTable();
                invoiceTable.Columns.Add("InvoiceNumber", typeof(string));
                invoiceTable.Columns.Add("CustomerId", typeof(Guid));
                // ... other columns
                
                foreach (var invoice in invoices)
                {
                    invoiceTable.Rows.Add(
                        invoice.InvoiceNumber,
                        invoice.CustomerId
                        // ... other values
                    );
                }
                
                await _context.WithConnection(async conn =>
                {
                    var parameters = new DynamicParameters();
                    parameters.Add("@Invoices", invoiceTable.AsTableValuedParameter("dbo.InvoiceBulkType"));
                    
                    await conn.ExecuteAsync(sql, parameters);
                });
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error in bulk insert of invoices");
                throw;
            }
        }
    }
}

9. Caching Strategy

9.1 Distributed Cache Implementation

namespace ECommerce.Infrastructure.Caching
{
    public class DistributedCacheService : ICacheService
    {
        private readonly IDistributedCache _cache;
        private readonly ILogger<DistributedCacheService> _logger;
        private readonly DistributedCacheEntryOptions _defaultOptions;
        
        public DistributedCacheService(
            IDistributedCache cache,
            ILogger<DistributedCacheService> logger,
            IConfiguration configuration)
        {
            _cache = cache;
            _logger = logger;
            
            _defaultOptions = new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(
                    configuration.GetValue<int>("Cache:DefaultExpirationMinutes"))
            };
        }
        
        public async Task<T> GetAsync<T>(string key, CancellationToken cancellationToken = default)
        {
            try
            {
                var cachedData = await _cache.GetStringAsync(key, cancellationToken);
                
                if (string.IsNullOrEmpty(cachedData))
                    return default;
                    
                return JsonSerializer.Deserialize<T>(cachedData);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error getting cached data for key {Key}", key);
                return default;
            }
        }
        
        public async Task SetAsync<T>(
            string key,
            T value,
            DistributedCacheEntryOptions options = null,
            CancellationToken cancellationToken = default)
        {
            try
            {
                var serializedValue = JsonSerializer.Serialize(value);
                await _cache.SetStringAsync(
                    key,
                    serializedValue,
                    options ?? _defaultOptions,
                    cancellationToken);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error setting cached data for key {Key}", key);
            }
        }
        
        public async Task RemoveAsync(string key, CancellationToken cancellationToken = default)
        {
            try
            {
                await _cache.RemoveAsync(key, cancellationToken);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error removing cached data for key {Key}", key);
            }
        }
    }
}

9.2 Cache Invalidation with MediatR Notifications

namespace ECommerce.Application.Common.Behaviors
{
    public class CacheInvalidationBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
        where TRequest : IRequest<TResponse>
    {
        private readonly ICacheService _cache;
        private readonly ILogger<CacheInvalidationBehavior<TRequest, TResponse>> _logger;
        
        public CacheInvalidationBehavior(
            ICacheService cache,
            ILogger<CacheInvalidationBehavior<TRequest, TResponse>> logger)
        {
            _cache = cache;
            _logger = logger;
        }
        
        public async Task<TResponse> Handle(
            TRequest request,
            RequestHandlerDelegate<TResponse> next,
            CancellationToken cancellationToken)
        {
            var response = await next();
            
            if (request is ICacheInvalidator invalidator)
            {
                try
                {
                    foreach (var key in invalidator.CacheKeys)
                    {
                        await _cache.RemoveAsync(key, cancellationToken);
                        _logger.LogDebug("Cache invalidated for key {Key}", key);
                    }
                }
                catch (Exception ex)
                {
                    _logger.LogError(ex, "Error invalidating cache for request {Request}", typeof(TRequest).Name);
                }
            }
            
            return response;
        }
    }
}

10. Swagger Configuration with JWT Support

namespace ECommerce.API.Extensions
{
    public static class SwaggerExtensions
    {
        public static IServiceCollection AddCustomSwagger(this IServiceCollection services, IConfiguration configuration)
        {
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Title = "ECommerce API",
                    Version = "v1",
                    Description = "ECommerce API with JWT Authentication",
                    Contact = new OpenApiContact
                    {
                        Name = "Your Name",
                        Email = "[email protected]"
                    }
                });
                
                // Add JWT Authentication support in Swagger
                var securityScheme = new OpenApiSecurityScheme
                {
                    Name = "JWT Authentication",
                    Description = "Enter JWT Bearer token **_only_**",
                    In = ParameterLocation.Header,
                    Type = SecuritySchemeType.Http,
                    Scheme = "bearer",
                    BearerFormat = "JWT",
                    Reference = new OpenApiReference
                    {
                        Id = JwtBearerDefaults.AuthenticationScheme,
                        Type = ReferenceType.SecurityScheme
                    }
                };
                
                c.AddSecurityDefinition(securityScheme.Reference.Id, securityScheme);
                c.AddSecurityRequirement(new OpenApiSecurityRequirement
                {
                    { securityScheme, Array.Empty<string>() }
                });
                
                // Enable annotations
                c.EnableAnnotations();
                
                // Include XML comments
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                if (File.Exists(xmlPath))
                {
                    c.IncludeXmlComments(xmlPath);
                }
            });
            
            return services;
        }
        
        public static IApplicationBuilder UseCustomSwagger(this IApplicationBuilder app)
        {
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "ECommerce API V1");
                c.RoutePrefix = "api-docs";
                c.DocumentTitle = "ECommerce API Documentation";
                c.DisplayRequestDuration();
                c.EnableDeepLinking();
                c.DefaultModelsExpandDepth(-1); // Hide schemas by default
            });
            
            return app;
        }
    }
}

11. Complete Startup Configuration

namespace ECommerce.API
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }
        
        public IConfiguration Configuration { get; }
        
        public void ConfigureServices(IServiceCollection services)
        {
            // Base services
            services.AddControllers()
                .AddJsonOptions(options =>
                {
                    options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
                    options.JsonSerializerOptions.DictionaryKeyPolicy = JsonNamingPolicy.CamelCase;
                    options.JsonSerializerOptions.WriteIndented = true;
                });
                
            // Database
            services.AddDatabase(Configuration);
            
            // Authentication
            services.AddAuthentication(Configuration);
            
            // Application services
            services.AddApplicationServices();
            
            // Infrastructure services
            services.AddInfrastructureServices(Configuration);
            
            // Swagger
            services.AddCustomSwagger(Configuration);
            
            // Caching
            services.AddDistributedMemoryCache(); // Or Redis for production
            services.AddSingleton<ICacheService, DistributedCacheService>();
            
            // Performance monitoring
            services.AddPerformanceMonitoring();
            
            // Logging
            services.AddCustomLogging(Configuration);
            
            // Health checks
            services.AddHealthChecks()
                .AddSqlServer(Configuration.GetConnectionString("DefaultConnection"))
                .AddDbContextCheck<ApplicationDbContext>();
                
            // Cross-Origin Resource Sharing (CORS)
            services.AddCors(options =>
            {
                options.AddPolicy("AllowAll", builder =>
                {
                    builder.AllowAnyOrigin()
                           .AllowAnyMethod()
                           .AllowAnyHeader();
                });
            });
        }
        
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                app.UsePerformanceMonitoring();
            }
            else
            {
                app.UseExceptionHandler("/error");
                app.UseHsts();
            }
            
            app.UseMiddleware<ErrorHandlingMiddleware>();
            
            app.UseHttpsRedirection();
            app.UseRouting();
            
            app.UseCors("AllowAll");
            
            app.UseAuthentication();
            app.UseAuthorization();
            
            app.UseCustomSwagger();
            
            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
                endpoints.MapHealthChecks("/health");
            });
        }
    }
}

12. Deployment Considerations

12.1 Docker Configuration

# Dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["ECommerce.API/ECommerce.API.csproj", "ECommerce.API/"]
COPY ["ECommerce.Application/ECommerce.Application.csproj", "ECommerce.Application/"]
COPY ["ECommerce.Core/ECommerce.Core.csproj", "ECommerce.Core/"]
COPY ["ECommerce.Infrastructure/ECommerce.Infrastructure.csproj", "ECommerce.Infrastructure/"]
RUN dotnet restore "ECommerce.API/ECommerce.API.csproj"
COPY . .
WORKDIR "/src/ECommerce.API"
RUN dotnet build "ECommerce.API.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "ECommerce.API.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "ECommerce.API.dll"]

12.2 Kubernetes Deployment

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ecommerce-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: ecommerce-api
  template:
    metadata:
      labels:
        app: ecommerce-api
    spec:
      containers:
      - name: ecommerce-api
        image: yourregistry/ecommerce-api:latest
        ports:
        - containerPort: 80
        envFrom:
        - configMapRef:
            name: ecommerce-config
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        readinessProbe:
          httpGet:
            path: /health
            port: 80
          initialDelaySeconds: 10
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /health
            port: 80
          initialDelaySeconds: 30
          periodSeconds: 10
---
# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: ecommerce-api
spec:
  selector:
    app: ecommerce-api
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: LoadBalancer

13. Testing Strategy

13.1 Unit Tests Example

namespace ECommerce.UnitTests.Application.Features.Authentication.Commands
{
    public class LoginCommandHandlerTests
    {
        private readonly Mock<IUserRepository> _userRepositoryMock;
        private readonly Mock<IJwtService> _jwtServiceMock;
        private readonly Mock<IRefreshTokenService> _refreshTokenServiceMock;
        private readonly Mock<IPasswordService> _passwordServiceMock;
        private readonly LoginCommandHandler _handler;
        
        public LoginCommandHandlerTests()
        {
            _userRepositoryMock = new Mock<IUserRepository>();
            _jwtServiceMock = new Mock<IJwtService>();
            _refreshTokenServiceMock = new Mock<IRefreshTokenService>();
            _passwordServiceMock = new Mock<IPasswordService>();
            
            _handler = new LoginCommandHandler(
                _userRepositoryMock.Object,
                _jwtServiceMock.Object,
                _refreshTokenServiceMock.Object,
                _passwordServiceMock.Object);
        }
        
        [Fact]
        public async Task Handle_WithValidCredentials_ReturnsAuthenticationResponse()
        {
            // Arrange
            var userId = Guid.NewGuid();
            var password = "Test@123";
            var passwordHash = new byte[] { 1, 2, 3 };
            var passwordSalt = new byte[] { 4, 5, 6 };
            
            var user = new User
            {
                Id = userId,
                UserName = "testuser",
                Email = "[email protected]",
                PasswordHash = passwordHash,
                PasswordSalt = passwordSalt,
                IsActive = true
            };
            
            var command = new LoginCommand
            {
                UserName = "testuser",
                Password = password,
                IpAddress = "127.0.0.1"
            };
            
            _userRepositoryMock.Setup(x => x.GetByUserNameAsync(command.UserName))
                .ReturnsAsync(user);
                
            _passwordServiceMock.Setup(x => x.VerifyPasswordHash(
                command.Password, passwordHash, passwordSalt))
                .Returns(true);
                
            _jwtServiceMock.Setup(x => x.GenerateJwtToken(user))
                .Returns("jwt_token");
                
            _refreshTokenServiceMock.Setup(x => x.GenerateRefreshToken(
                user.Id, command.IpAddress))
                .ReturnsAsync(new RefreshToken { Token = "refresh_token" });
                
            _userRepositoryMock.Setup(x => x.GetUserRolesAsync(user.Id))
                .ReturnsAsync(new List<string> { "User" });
                
            // Act
            var result = await _handler.Handle(command, CancellationToken.None);
            
            // Assert
            result.Should().NotBeNull();
            result.Token.Should().Be("jwt_token");
            result.RefreshToken.Should().Be("refresh_token");
            result.Roles.Should().Contain("User");
        }
    }
}

13.2 Integration Tests Example

namespace ECommerce.IntegrationTests.Controllers
{
    public class AuthenticationControllerTests : IClassFixture<CustomWebApplicationFactory<Startup>>
    {
        private readonly CustomWebApplicationFactory<Startup> _factory;
        private readonly HttpClient _client;
        
        public AuthenticationControllerTests(CustomWebApplicationFactory<Startup> factory)
        {
            _factory = factory;
            _client = _factory.CreateClient();
        }
        
        [Fact]
        public async Task Login_WithValidCredentials_ReturnsToken()
        {
            // Arrange
            var request = new LoginRequest
            {
                UserName = "admin",
                Password = "Admin@123"
            };
            
            var content = new StringContent(
                JsonSerializer.Serialize(request),
                Encoding.UTF8,
                "application/json");
                
            // Act
            var response = await _client.PostAsync("/api/authentication/login", content);
            
            // Assert
            response.EnsureSuccessStatusCode();
            
            var responseString = await response.Content.ReadAsStringAsync();
            var result = JsonSerializer.Deserialize<AuthenticationResponse>(
                responseString,
                new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
                
            result.Should().NotBeNull();
            result.Token.Should().NotBeNullOrEmpty();
            result.RefreshToken.Should().NotBeNullOrEmpty();
        }
    }
}

14. Monitoring and Observability

14.1 Application Insights Configuration

namespace ECommerce.API.Extensions
{
    public static class MonitoringExtensions
    {
        public static IServiceCollection AddApplicationMonitoring(this IServiceCollection services, IConfiguration configuration)
        {
            if (!string.IsNullOrEmpty(configuration["ApplicationInsights:ConnectionString"]))
            {
                services.AddApplicationInsightsTelemetry(options =>
                {
                    options.ConnectionString = configuration["ApplicationInsights:ConnectionString"];
                    options.EnableAdaptiveSampling = false;
                });
                
                services.AddApplicationInsightsKubernetesEnricher();
                
                services.AddSingleton<ITelemetryInitializer, CloudRoleNameTelemetryInitializer>();
            }
            
            return services;
        }
    }
    
    public class CloudRoleNameTelemetryInitializer : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {
            telemetry.Context.Cloud.RoleName = "ECommerce.API";
        }
    }
}

14.2 Health Checks with UI

namespace ECommerce.API.Extensions
{
    public static class HealthCheckExtensions
    {
        public static IServiceCollection AddCustomHealthChecks(this IServiceCollection services, IConfiguration configuration)
        {
            services.AddHealthChecks()
                .AddSqlServer(
                    configuration.GetConnectionString("DefaultConnection"),
                    name: "SQL Server",
                    tags: new[] { "database", "sql" })
                .AddRedis(
                    configuration.GetConnectionString("Redis"),
                    name: "Redis",
                    tags: new[] { "cache", "redis" })
                .AddApplicationInsightsPublisher();
                
            services.AddHealthChecksUI(setup =>
                {
                    setup.AddHealthCheckEndpoint("API", "/health");
                    setup.SetEvaluationTimeInSeconds(60);
                    setup.SetMinimumSecondsBetweenFailureNotifications(300);
                })
                .AddInMemoryStorage();
                
            return services;
        }
        
        public static IApplicationBuilder UseCustomHealthChecks(this IApplicationBuilder app)
        {
            app.UseHealthChecks("/health", new HealthCheckOptions
            {
                Predicate = _ => true,
                ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
            });
            
            app.UseHealthChecksUI(options =>
            {
                options.UIPath = "/health-ui";
                options.ApiPath = "/health-api";
            });
            
            return app;
        }
    }
}

15. Security Best Practices

15.1 Security Headers Middleware

namespace ECommerce.API.Middleware
{
    public class SecurityHeadersMiddleware
    {
        private readonly RequestDelegate _next;
        
        public SecurityHeadersMiddleware(RequestDelegate next)
        {
            _next = next;
        }
        
        public async Task Invoke(HttpContext context)
        {
            // Add security headers
            context.Response.Headers.Add("X-Frame-Options", "DENY");
            context.Response.Headers.Add("X-Content-Type-Options", "nosniff");
            context.Response.Headers.Add("X-XSS-Protection", "1; mode=block");
            context.Response.Headers.Add("Referrer-Policy", "no-referrer");
            context.Response.Headers.Add("Content-Security-Policy", 
                "default-src 'self'; " +
                "script-src 'self' 'unsafe-inline' 'unsafe-eval'; " +
                "style-src 'self' 'unsafe-inline'; " +
                "img-src 'self' data:; " +
                "font-src 'self'; " +
                "connect-src 'self'; " +
                "media-src 'self'; " +
                "object-src 'none'; " +
                "frame-src 'none'; " +
                "base-uri 'self'; " +
                "form-action 'self'; " +
                "frame-ancestors 'none';");
                
            await _next(context);
        }
    }
}

15.2 Rate Limiting

namespace ECommerce.API.Extensions
{
    public static class RateLimitingExtensions
    {
        public static IServiceCollection AddCustomRateLimiting(this IServiceCollection services)
        {
            services.AddRateLimiter(options =>
            {
                options.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(context =>
                {
                    return RateLimitPartition.GetFixedWindowLimiter(
                        partitionKey: context.Request.Headers.Host.ToString(),
                        factory: partition => new FixedWindowRateLimiterOptions
                        {
                            AutoReplenishment = true,
                            PermitLimit = 100,
                            QueueLimit = 10,
                            Window = TimeSpan.FromMinutes(1)
                        });
                });
                
                options.OnRejected = async (context, token) =>
                {
                    context.HttpContext.Response.StatusCode = StatusCodes.Status429TooManyRequests;
                    await context.HttpContext.Response.WriteAsync(
                        "Too many requests. Please try again later.", 
                        cancellationToken: token);
                };
            });
            
            return services;
        }
    }
}

Conclusion

This comprehensive architecture provides a solid foundation for building scalable ASP.NET Core Web APIs with:

1. Clean Architecture separation of concerns
2. Database-first approach with SQL Server stored procedures
3. Dapper for efficient data access
4. CQRS pattern with MediatR
5. JWT authentication with refresh tokens
6. Transaction management for data integrity
7. Large data handling techniques
8. Comprehensive logging and monitoring
9. Robust error handling
10. API documentation with Swagger
11. Security best practices
12. Testing strategies

The implementation demonstrates key scenarios like user authentication and master-detail invoice operations while following enterprise-grade patterns and practices.

To complete your solution, you would:

1. Implement the remaining repositories and services
2. Add more domain entities and features
3. Configure deployment pipelines
4. Set up monitoring dashboards
5. Implement frontend integration (Angular/React/Flutter)

This architecture is designed to handle large-scale applications with complex business requirements while maintaining performance, scalability, and maintainability.