@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/dotnet/aspnet-core/references/REFERENCE.md

@@ -0,0 +1,335 @@
+# ASP.NET Core Web API Reference
+
+Middleware, exception handling, and advanced patterns.
+
+## References
+
+- [**Middleware**](middleware.md) - Custom middleware patterns.
+- [**Exception Handling**](exception-handling.md) - Global error handling.
+- [**HttpClientFactory**](httpclient-factory.md) - Typed HTTP clients.
+
+## Global Exception Handling Middleware
+
+```csharp
+public class ExceptionMiddleware(
+    RequestDelegate next,
+    ILogger<ExceptionMiddleware> logger,
+    IHostEnvironment env)
+{
+    public async Task InvokeAsync(HttpContext context)
+    {
+        try
+        {
+            await next(context);
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Unhandled exception: {Message}", ex.Message);
+            await HandleExceptionAsync(context, ex);
+        }
+    }
+
+    private async Task HandleExceptionAsync(HttpContext context, Exception exception)
+    {
+        context.Response.ContentType = "application/problem+json";
+
+        var (statusCode, title) = exception switch
+        {
+            NotFoundException => (StatusCodes.Status404NotFound, "Not Found"),
+            ValidationException => (StatusCodes.Status400BadRequest, "Validation Error"),
+            UnauthorizedAccessException => (StatusCodes.Status401Unauthorized, "Unauthorized"),
+            ForbiddenException => (StatusCodes.Status403Forbidden, "Forbidden"),
+            _ => (StatusCodes.Status500InternalServerError, "Internal Server Error")
+        };
+
+        context.Response.StatusCode = statusCode;
+
+        var problem = new ProblemDetails
+        {
+            Status = statusCode,
+            Title = title,
+            Detail = env.IsDevelopment() ? exception.Message : null,
+            Instance = context.Request.Path
+        };
+
+        if (exception is ValidationException validationEx)
+        {
+            problem.Extensions["errors"] = validationEx.Errors;
+        }
+
+        await context.Response.WriteAsJsonAsync(problem);
+    }
+}
+
+// Registration
+app.UseMiddleware<ExceptionMiddleware>();
+```
+
+## Minimal API Endpoint Filters
+
+```csharp
+// Validation filter
+public class ValidationFilter<T> : IEndpointFilter where T : class
+{
+    public async ValueTask<object?> InvokeAsync(
+        EndpointFilterInvocationContext context,
+        EndpointFilterDelegate next)
+    {
+        var model = context.Arguments.OfType<T>().FirstOrDefault();
+
+        if (model is null)
+            return TypedResults.BadRequest("Request body is required");
+
+        var validator = context.HttpContext.RequestServices.GetService<IValidator<T>>();
+
+        if (validator is not null)
+        {
+            var result = await validator.ValidateAsync(model);
+            if (!result.IsValid)
+            {
+                return TypedResults.ValidationProblem(
+                    result.ToDictionary());
+            }
+        }
+
+        return await next(context);
+    }
+}
+
+// Logging filter
+public class LoggingFilter(ILogger<LoggingFilter> logger) : IEndpointFilter
+{
+    public async ValueTask<object?> InvokeAsync(
+        EndpointFilterInvocationContext context,
+        EndpointFilterDelegate next)
+    {
+        var path = context.HttpContext.Request.Path;
+        logger.LogInformation("Request started: {Path}", path);
+
+        var sw = Stopwatch.StartNew();
+        var result = await next(context);
+        sw.Stop();
+
+        logger.LogInformation("Request completed: {Path} in {ElapsedMs}ms",
+            path, sw.ElapsedMilliseconds);
+
+        return result;
+    }
+}
+
+// Usage
+app.MapPost("/api/users", handler)
+   .AddEndpointFilter<ValidationFilter<CreateUserDto>>()
+   .AddEndpointFilter<LoggingFilter>();
+```
+
+## IHttpClientFactory Typed Clients
+
+```csharp
+// Typed client
+public class PaymentClient(HttpClient httpClient)
+{
+    public async Task<PaymentResult?> ProcessPaymentAsync(PaymentRequest request)
+    {
+        var response = await httpClient.PostAsJsonAsync("/payments", request);
+        response.EnsureSuccessStatusCode();
+        return await response.Content.ReadFromJsonAsync<PaymentResult>();
+    }
+
+    public async Task<PaymentStatus?> GetStatusAsync(string paymentId)
+    {
+        return await httpClient.GetFromJsonAsync<PaymentStatus>($"/payments/{paymentId}");
+    }
+}
+
+// Registration with resilience
+builder.Services.AddHttpClient<PaymentClient>(client =>
+{
+    client.BaseAddress = new Uri(builder.Configuration["Payment:BaseUrl"]!);
+    client.DefaultRequestHeaders.Add("X-Api-Key",
+        builder.Configuration["Payment:ApiKey"]);
+    client.Timeout = TimeSpan.FromSeconds(30);
+})
+.AddStandardResilienceHandler(); // Polly retry, circuit breaker
+
+// Manual resilience configuration
+builder.Services.AddHttpClient<PaymentClient>()
+    .AddResilienceHandler("payment-pipeline", builder =>
+    {
+        builder
+            .AddRetry(new HttpRetryStrategyOptions
+            {
+                MaxRetryAttempts = 3,
+                Delay = TimeSpan.FromSeconds(1),
+                BackoffType = DelayBackoffType.Exponential
+            })
+            .AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions
+            {
+                SamplingDuration = TimeSpan.FromSeconds(30),
+                FailureRatio = 0.5,
+                MinimumThroughput = 10,
+                BreakDuration = TimeSpan.FromSeconds(30)
+            })
+            .AddTimeout(TimeSpan.FromSeconds(10));
+    });
+```
+
+## Background Services
+
+```csharp
+public class OrderProcessingService(
+    IServiceScopeFactory scopeFactory,
+    ILogger<OrderProcessingService> logger) : BackgroundService
+{
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        logger.LogInformation("Order processing service started");
+
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            try
+            {
+                await ProcessPendingOrdersAsync(stoppingToken);
+            }
+            catch (Exception ex)
+            {
+                logger.LogError(ex, "Error processing orders");
+            }
+
+            await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
+        }
+    }
+
+    private async Task ProcessPendingOrdersAsync(CancellationToken ct)
+    {
+        using var scope = scopeFactory.CreateScope();
+        var orderService = scope.ServiceProvider.GetRequiredService<IOrderService>();
+
+        var pendingOrders = await orderService.GetPendingOrdersAsync(ct);
+
+        foreach (var order in pendingOrders)
+        {
+            await orderService.ProcessAsync(order.Id, ct);
+            logger.LogInformation("Processed order {OrderId}", order.Id);
+        }
+    }
+}
+
+// Registration
+builder.Services.AddHostedService<OrderProcessingService>();
+```
+
+## Health Checks
+
+```csharp
+// Registration
+builder.Services.AddHealthChecks()
+    .AddDbContextCheck<AppDbContext>("database")
+    .AddRedis(builder.Configuration.GetConnectionString("Redis")!, "redis")
+    .AddUrlGroup(new Uri("https://api.external.com/health"), "external-api")
+    .AddCheck<CustomHealthCheck>("custom");
+
+// Custom health check
+public class CustomHealthCheck(IOrderService orderService) : IHealthCheck
+{
+    public async Task<HealthCheckResult> CheckHealthAsync(
+        HealthCheckContext context,
+        CancellationToken ct = default)
+    {
+        try
+        {
+            var count = await orderService.GetPendingCountAsync(ct);
+
+            if (count > 1000)
+            {
+                return HealthCheckResult.Degraded(
+                    $"High pending orders: {count}");
+            }
+
+            return HealthCheckResult.Healthy();
+        }
+        catch (Exception ex)
+        {
+            return HealthCheckResult.Unhealthy("Order service unavailable", ex);
+        }
+    }
+}
+
+// Endpoints
+app.MapHealthChecks("/health", new HealthCheckOptions
+{
+    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
+});
+
+app.MapHealthChecks("/health/ready", new HealthCheckOptions
+{
+    Predicate = check => check.Tags.Contains("ready")
+});
+
+app.MapHealthChecks("/health/live", new HealthCheckOptions
+{
+    Predicate = _ => false // Just checks if app is running
+});
+```
+
+## Model Binding and Validation
+
+```csharp
+// FluentValidation
+public class CreateOrderDtoValidator : AbstractValidator<CreateOrderDto>
+{
+    public CreateOrderDtoValidator()
+    {
+        RuleFor(x => x.CustomerId)
+            .NotEmpty()
+            .WithMessage("Customer ID is required");
+
+        RuleFor(x => x.Items)
+            .NotEmpty()
+            .WithMessage("Order must have at least one item");
+
+        RuleForEach(x => x.Items).ChildRules(item =>
+        {
+            item.RuleFor(x => x.ProductId).NotEmpty();
+            item.RuleFor(x => x.Quantity).GreaterThan(0);
+        });
+
+        RuleFor(x => x.ShippingAddress)
+            .NotNull()
+            .SetValidator(new AddressValidator());
+    }
+}
+
+// Registration
+builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderDtoValidator>();
+
+// Pipeline behavior for MediatR
+public class ValidationBehavior<TRequest, TResponse>(
+    IEnumerable<IValidator<TRequest>> validators)
+    : IPipelineBehavior<TRequest, TResponse>
+    where TRequest : notnull
+{
+    public async Task<TResponse> Handle(
+        TRequest request,
+        RequestHandlerDelegate<TResponse> next,
+        CancellationToken ct)
+    {
+        if (!validators.Any())
+            return await next();
+
+        var context = new ValidationContext<TRequest>(request);
+        var results = await Task.WhenAll(
+            validators.Select(v => v.ValidateAsync(context, ct)));
+
+        var failures = results
+            .SelectMany(r => r.Errors)
+            .Where(f => f != null)
+            .ToList();
+
+        if (failures.Count != 0)
+            throw new ValidationException(failures);
+
+        return await next();
+    }
+}
+```

package/rules/dotnet/best-practices/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: C# Best Practices
+description: Idiomatic C# patterns for clean, maintainable code.
+metadata:
+  labels: [csharp, conventions, naming, structure, di]
+  triggers:
+    files: ['**/*.cs']
+    keywords: [class, namespace, using, public, private, internal]
+---
+
+# C# Best Practices
+
+## **Priority: P1 (OPERATIONAL)**
+
+Idiomatic patterns for clean, maintainable C# code.
+
+## Implementation Guidelines
+
+- **Naming Conventions**:
+  - `PascalCase`: Types, methods, properties, events, namespaces
+  - `camelCase`: Parameters, local variables
+  - `_camelCase`: Private fields
+  - `IPascalCase`: Interfaces (prefix with `I`)
+  - `TPascalCase`: Type parameters (prefix with `T`)
+- **Project Structure**: Clean/Onion architecture. Feature folders over layer folders.
+- **Dependency Injection**: Constructor injection only. Register in `IServiceCollection`.
+- **Logging**: `ILogger<T>` with structured logging. Use appropriate log levels.
+- **Configuration**: `IOptions<T>` pattern with validation. Never hardcode settings.
+- **File Organization**: One type per file. Use `global using` for common namespaces.
+- **Immutability**: Prefer `readonly`, `init`, `record` for data integrity.
+- **Expression-bodied Members**: Use for simple single-line methods/properties.
+
+## Anti-Patterns
+
+- **No static services**: Use DI instead of `static class ServiceHelper`.
+- **No service locator**: Avoid `IServiceProvider.GetService()` in business logic.
+- **No `new()` for dependencies**: Inject via constructor.
+- **No magic strings**: Use `nameof()`, constants, or configuration.
+- **No God classes**: Split large classes by responsibility.
+- **No regions**: Use partial classes or extract types instead.
+
+## Code
+
+```csharp
+// Proper DI registration
+public static class ServiceCollectionExtensions
+{
+    public static IServiceCollection AddApplicationServices(this IServiceCollection services)
+    {
+        services.AddScoped<IUserService, UserService>();
+        services.AddScoped<IOrderService, OrderService>();
+
+        services.AddOptions<EmailSettings>()
+            .BindConfiguration("Email")
+            .ValidateDataAnnotations()
+            .ValidateOnStart();
+
+        return services;
+    }
+}
+
+// Structured logging with semantic names
+public class OrderService(IOrderRepository repo, ILogger<OrderService> logger)
+{
+    public async Task<Order?> GetOrderAsync(int orderId, CancellationToken ct)
+    {
+        logger.LogDebug("Fetching order {OrderId}", orderId);
+
+        var order = await repo.GetByIdAsync(orderId, ct);
+
+        if (order is null)
+            logger.LogWarning("Order {OrderId} not found", orderId);
+
+        return order;
+    }
+}
+
+// Options pattern with validation
+public class EmailSettings
+{
+    public const string SectionName = "Email";
+
+    [Required]
+    public string SmtpHost { get; init; } = string.Empty;
+
+    [Range(1, 65535)]
+    public int SmtpPort { get; init; } = 587;
+
+    [Required, EmailAddress]
+    public string FromAddress { get; init; } = string.Empty;
+}
+```
+
+## Reference & Examples
+
+For project structure templates and DI patterns:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+language | security | tooling

package/rules/dotnet/best-practices/references/REFERENCE.md

@@ -0,0 +1,256 @@
+# C# Best Practices Reference
+
+Project structure, dependency injection, and configuration patterns.
+
+## References
+
+- [**Project Structure**](project-structure.md) - Clean Architecture layout.
+- [**DI Lifetimes**](di-lifetimes.md) - Transient, Scoped, Singleton comparison.
+- [**Logging**](logging.md) - Structured logging best practices.
+
+## Project Structure (Clean Architecture)
+
+```
+src/
+├── Domain/                        # Core business logic (no dependencies)
+│   ├── Entities/
+│   │   ├── User.cs
+│   │   └── Order.cs
+│   ├── ValueObjects/
+│   │   └── Money.cs
+│   ├── Enums/
+│   │   └── OrderStatus.cs
+│   └── Interfaces/
+│       ├── IUserRepository.cs
+│       └── IOrderRepository.cs
+│
+├── Application/                   # Use cases (depends on Domain)
+│   ├── Common/
+│   │   ├── Interfaces/
+│   │   │   └── IEmailService.cs
+│   │   └── Behaviors/
+│   │       └── ValidationBehavior.cs
+│   ├── Users/
+│   │   ├── Commands/
+│   │   │   └── CreateUserCommand.cs
+│   │   └── Queries/
+│   │       └── GetUserQuery.cs
+│   └── DependencyInjection.cs
+│
+├── Infrastructure/                # External concerns (DB, Email, etc.)
+│   ├── Data/
+│   │   ├── AppDbContext.cs
+│   │   └── Repositories/
+│   │       └── UserRepository.cs
+│   ├── Services/
+│   │   └── EmailService.cs
+│   └── DependencyInjection.cs
+│
+└── WebApi/                        # Presentation layer
+    ├── Controllers/
+    │   └── UsersController.cs
+    ├── Middleware/
+    │   └── ExceptionMiddleware.cs
+    └── Program.cs
+```
+
+## DI Lifetime Comparison
+
+| Lifetime | Created | Disposed | Use Case |
+|----------|---------|----------|----------|
+| **Transient** | Every request | After use | Lightweight, stateless services |
+| **Scoped** | Once per HTTP request | End of request | DbContext, UnitOfWork |
+| **Singleton** | Once per app | App shutdown | Caches, HttpClientFactory |
+
+```csharp
+// Registration examples
+services.AddTransient<IEmailSender, EmailSender>();      // New instance each time
+services.AddScoped<IUserRepository, UserRepository>();   // Per HTTP request
+services.AddSingleton<ICacheService, MemoryCacheService>(); // App lifetime
+
+// Common mistake: Scoped in Singleton (captive dependency)
+// ❌ DON'T: Singleton depending on Scoped
+public class SingletonService(IScopedService scoped) { } // Runtime error!
+
+// ✅ DO: Use IServiceScopeFactory for scoped in singleton
+public class SingletonService(IServiceScopeFactory scopeFactory)
+{
+    public async Task DoWork()
+    {
+        using var scope = scopeFactory.CreateScope();
+        var scoped = scope.ServiceProvider.GetRequiredService<IScopedService>();
+        await scoped.ProcessAsync();
+    }
+}
+```
+
+## Logging Best Practices
+
+```csharp
+// Log levels usage
+public class OrderProcessor(ILogger<OrderProcessor> logger)
+{
+    public async Task ProcessAsync(Order order)
+    {
+        // Trace: Very detailed, only for debugging specific issues
+        logger.LogTrace("Processing order with data: {@Order}", order);
+
+        // Debug: Development diagnostics
+        logger.LogDebug("Starting order processing for {OrderId}", order.Id);
+
+        // Information: Normal operation milestones
+        logger.LogInformation("Order {OrderId} processed successfully", order.Id);
+
+        // Warning: Unexpected but handled situations
+        if (order.Items.Count == 0)
+            logger.LogWarning("Order {OrderId} has no items", order.Id);
+
+        // Error: Failures that need attention
+        try { await SendEmailAsync(order); }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Failed to send email for order {OrderId}", order.Id);
+        }
+
+        // Critical: App-breaking failures
+        // logger.LogCritical("Database connection lost");
+    }
+}
+
+// High-performance logging with source generators
+public static partial class LogMessages
+{
+    [LoggerMessage(Level = LogLevel.Information, Message = "Order {OrderId} created by {UserId}")]
+    public static partial void OrderCreated(this ILogger logger, int orderId, int userId);
+
+    [LoggerMessage(Level = LogLevel.Error, Message = "Payment failed for order {OrderId}")]
+    public static partial void PaymentFailed(this ILogger logger, int orderId, Exception ex);
+}
+
+// Usage
+logger.OrderCreated(order.Id, user.Id);
+```
+
+## Configuration Patterns
+
+```csharp
+// appsettings.json structure
+{
+  "Database": {
+    "ConnectionString": "...",
+    "CommandTimeout": 30
+  },
+  "Email": {
+    "SmtpHost": "smtp.example.com",
+    "SmtpPort": 587,
+    "FromAddress": "noreply@example.com"
+  },
+  "Features": {
+    "EnableNewDashboard": true
+  }
+}
+
+// Strongly-typed options
+public class DatabaseSettings
+{
+    public const string SectionName = "Database";
+
+    [Required]
+    public string ConnectionString { get; init; } = string.Empty;
+
+    [Range(1, 300)]
+    public int CommandTimeout { get; init; } = 30;
+}
+
+// Registration with validation
+builder.Services.AddOptions<DatabaseSettings>()
+    .BindConfiguration(DatabaseSettings.SectionName)
+    .ValidateDataAnnotations()
+    .ValidateOnStart(); // Fail fast at startup
+
+// Usage patterns
+public class DataService(IOptions<DatabaseSettings> options)
+{
+    // IOptions<T> - Singleton, read once at startup
+    private readonly DatabaseSettings _settings = options.Value;
+}
+
+public class FeatureService(IOptionsSnapshot<DatabaseSettings> options)
+{
+    // IOptionsSnapshot<T> - Scoped, re-reads on each request
+    public void DoWork() => Console.WriteLine(options.Value.CommandTimeout);
+}
+
+public class BackgroundService(IOptionsMonitor<DatabaseSettings> options)
+{
+    // IOptionsMonitor<T> - Singleton with change notifications
+    public BackgroundService()
+    {
+        options.OnChange(settings => Console.WriteLine("Config changed!"));
+    }
+}
+```
+
+## Extension Method Patterns
+
+```csharp
+// Service registration extensions
+public static class ServiceCollectionExtensions
+{
+    public static IServiceCollection AddInfrastructure(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        // Database
+        services.AddDbContext<AppDbContext>(options =>
+            options.UseSqlServer(configuration.GetConnectionString("Default")));
+
+        // Repositories
+        services.AddScoped<IUserRepository, UserRepository>();
+        services.AddScoped<IOrderRepository, OrderRepository>();
+
+        // External services
+        services.AddHttpClient<IPaymentClient, PaymentClient>(client =>
+        {
+            client.BaseAddress = new Uri(configuration["Payment:BaseUrl"]!);
+            client.Timeout = TimeSpan.FromSeconds(30);
+        });
+
+        return services;
+    }
+}
+
+// Usage in Program.cs
+builder.Services
+    .AddInfrastructure(builder.Configuration)
+    .AddApplication();
+```
+
+## Naming Convention Examples
+
+```csharp
+// ✅ Correct naming
+public interface IUserRepository { }           // Interface: IPascalCase
+public class UserRepository : IUserRepository  // Class: PascalCase
+{
+    private readonly DbContext _context;       // Private field: _camelCase
+    private readonly ILogger<UserRepository> _logger;
+
+    public string ConnectionString { get; }    // Property: PascalCase
+    public event EventHandler? UserCreated;    // Event: PascalCase
+
+    public async Task<User?> GetByIdAsync(     // Method: PascalCase
+        int userId,                            // Parameter: camelCase
+        CancellationToken cancellationToken)
+    {
+        var user = await _context.Users        // Local: camelCase
+            .FindAsync(userId, cancellationToken);
+        return user;
+    }
+}
+
+public class Repository<TEntity>               // Type parameter: TPascalCase
+    where TEntity : class { }
+
+public const string DefaultRole = "User";      // Constant: PascalCase
+```