@ngxtm/devkit 3.11.0 → 3.12.0

package/templates/dotnet/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/templates/dotnet/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
+```

package/templates/dotnet/rules/dotnet/blazor/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: Blazor
+description: Blazor component patterns for interactive web UIs.
+metadata:
+  labels: [blazor, components, wasm, server]
+  triggers:
+    files: ['**/*.razor', '**/*.razor.cs']
+    keywords: [Component, Parameter, CascadingParameter, EventCallback, StateHasChanged]
+---
+
+# Blazor
+
+## **Priority: P1 (OPERATIONAL)**
+
+Blazor component patterns for interactive web UIs.
+
+## Implementation Guidelines
+
+- **Components**: Keep components focused. Split large components into smaller ones.
+- **Parameters**: Use `[Parameter]` for one-way, `EventCallback` for two-way binding.
+- **Cascading Values**: Use for app-wide state (theme, user context).
+- **State Management**: Component state for local, Fluxor/custom service for global.
+- **Forms**: `EditForm` with `DataAnnotationsValidator` or FluentValidation.
+- **JS Interop**: Use `IJSRuntime` sparingly. Prefer Blazor bindings.
+- **Render Modes**: Choose based on requirements (Server, WASM, Auto in .NET 8+).
+- **Streaming**: Use `[StreamRendering]` for long-loading components.
+
+## Anti-Patterns
+
+- **No direct DOM manipulation**: Use Blazor bindings and refs.
+- **No `StateHasChanged()` in lifecycle**: Called automatically after lifecycle methods.
+- **No heavy computation in render**: Move to `OnInitialized` or background task.
+- **No sync JS interop in Server mode**: Causes UI blocking.
+
+## Code
+
+```razor
+@* UserList.razor *@
+@page "/users"
+@attribute [StreamRendering]
+@inject IUserService UserService
+
+<PageTitle>Users</PageTitle>
+
+<h3>Users</h3>
+
+@if (_users is null)
+{
+    <p><em>Loading...</em></p>
+}
+else if (_users.Count == 0)
+{
+    <p>No users found.</p>
+}
+else
+{
+    <div class="user-grid">
+        @foreach (var user in _users)
+        {
+            <UserCard User="user" OnDelete="HandleDelete" />
+        }
+    </div>
+}
+
+@code {
+    private List<User>? _users;
+
+    protected override async Task OnInitializedAsync()
+    {
+        _users = await UserService.GetAllAsync();
+    }
+
+    private async Task HandleDelete(int userId)
+    {
+        await UserService.DeleteAsync(userId);
+        _users = await UserService.GetAllAsync();
+    }
+}
+```
+
+```razor
+@* UserCard.razor - Reusable component *@
+<div class="card">
+    <h5>@User.Name</h5>
+    <p>@User.Email</p>
+    <button @onclick="() => OnDelete.InvokeAsync(User.Id)">Delete</button>
+</div>
+
+@code {
+    [Parameter, EditorRequired]
+    public User User { get; set; } = default!;
+
+    [Parameter]
+    public EventCallback<int> OnDelete { get; set; }
+}
+```
+
+```razor
+@* EditForm with validation *@
+<EditForm Model="@_model" OnValidSubmit="HandleSubmit" FormName="CreateUser">
+    <DataAnnotationsValidator />
+    <ValidationSummary class="text-danger" />
+
+    <div class="mb-3">
+        <label class="form-label">Name</label>
+        <InputText @bind-Value="_model.Name" class="form-control" />
+        <ValidationMessage For="@(() => _model.Name)" />
+    </div>
+
+    <div class="mb-3">
+        <label class="form-label">Email</label>
+        <InputText @bind-Value="_model.Email" class="form-control" type="email" />
+        <ValidationMessage For="@(() => _model.Email)" />
+    </div>
+
+    <button type="submit" class="btn btn-primary" disabled="@_isSubmitting">
+        @if (_isSubmitting)
+        {
+            <span class="spinner-border spinner-border-sm"></span>
+        }
+        Submit
+    </button>
+</EditForm>
+
+@code {
+    private CreateUserModel _model = new();
+    private bool _isSubmitting;
+
+    private async Task HandleSubmit()
+    {
+        _isSubmitting = true;
+        await UserService.CreateAsync(_model);
+        _isSubmitting = false;
+        NavigationManager.NavigateTo("/users");
+    }
+}
+```
+
+## Reference & Examples
+
+For lifecycle, state management, and JS interop:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+aspnet-core | razor-pages | security