AgentSkillsCN

aspnet-core

可用于构建 REST API、SignalR 集线器以及 ASP.NET Core Web API 应用程序。 适用于以下场景：创建控制器、配置中间件、设置依赖注入、实现后台服务，或在 API 层进行开发与调试。

SKILL.md
--- frontmatter
name: aspnet-core
description: |
  Builds REST APIs, SignalR hubs, and ASP.NET Core Web API applications.
  Use when: Creating controllers, configuring middleware, setting up dependency injection, implementing background services, or working with the API layer.
allowed-tools: Read, Edit, Write, Glob, Grep, Bash

ASP.NET Core Skill

ASP.NET Core Web API patterns for VanDaemon's backend. This project uses .NET 10 with thin controllers, singleton services, SignalR for real-time updates, and JSON file persistence. Controllers delegate to application services; business logic never lives in controllers.

Quick Start

Minimal Controller

csharp
[ApiController]
[Route("api/[controller]")]
public class TanksController : ControllerBase
{
    private readonly ITankService _tankService;

    public TanksController(ITankService tankService)
    {
        _tankService = tankService;
    }

    [HttpGet]
    public async Task<ActionResult<IEnumerable<Tank>>> GetAll(CancellationToken ct)
    {
        var tanks = await _tankService.GetAllTanksAsync(ct);
        return Ok(tanks);
    }

    [HttpPost("{id}/state")]
    public async Task<IActionResult> SetState(Guid id, [FromBody] object state, CancellationToken ct)
    {
        await _tankService.UpdateTankAsync(id, state, ct);
        return NoContent();
    }
}

Service Registration

csharp
// Program.cs - Register as singletons (VanDaemon pattern)
builder.Services.AddSingleton<ITankService, TankService>();
builder.Services.AddSingleton<IControlService, ControlService>();
builder.Services.AddSingleton<JsonFileStore>();

// SignalR
builder.Services.AddSignalR();

// After app.Build()
app.MapHub<TelemetryHub>("/hubs/telemetry");

Key Concepts

ConceptUsageExample
Thin ControllersDelegate to services immediatelyreturn Ok(await _service.GetAsync(ct))
CancellationTokenAccept in all async endpointsTask<T> Method(CancellationToken ct)
ActionResult<T>Return type for typed responsesActionResult<List<Tank>>
Background ServicesInherit BackgroundServiceTelemetryBackgroundService
Health ChecksMap /health endpointapp.MapGet("/health", ...)

Common Patterns

Background Service with Scope

csharp
public class TelemetryBackgroundService : BackgroundService
{
    private readonly IServiceProvider _provider;

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            using var scope = _provider.CreateScope();
            var tankService = scope.ServiceProvider.GetRequiredService<ITankService>();
            await tankService.RefreshAllAsync(ct);
            await Task.Delay(TimeSpan.FromSeconds(5), ct);
        }
    }
}

Health Endpoint

csharp
app.MapGet("/health", () => Results.Ok(new
{
    status = "healthy",
    timestamp = DateTime.UtcNow
}));

WARNING: Common Anti-Patterns

See patterns for detailed anti-pattern documentation including:

  • •Business logic in controllers
  • •Missing CancellationToken
  • •Blocking calls in async context
  • •Incorrect service lifetimes

See Also

  • •patterns - Controller patterns, DI, anti-patterns
  • •workflows - Adding endpoints, services, SignalR

Related Skills

  • •See the csharp skill for language patterns and async/await
  • •See the signalr skill for real-time hub implementation
  • •See the serilog skill for structured logging
  • •See the docker skill for containerized deployment
  • •See the xunit skill for controller testing