neo-dotnet-webapi

name	neo-dotnet-webapi
description	Use this skill when building, debugging, refactoring, or reviewing controller-based ASP.NET Core Web APIs, including ControllerBase, ActionResult<T>, Problem Details, API versioning, global exception handling, DTOs, and OpenAPI behavior.
compatibility	Supports .NET 6.0 through 10.0 environments. Requires .NET SDK installed locally.
metadata	{"version":"1.0.0","category":"Framework"}

.NET Web API Expert Skill

Trigger On

• The user requests to create, debug, refactor, or review ASP.NET Core Web APIs.
• The project contains a Controllers directory and inherits from ControllerBase.
• The target framework is .NET 6.0 (LTS) and above.
• There is a need for API code modernization (e.g., migrating from Middleware exception handling to .NET 8+ IExceptionHandler).

Workflow

1. Perceive (Architecture Awareness):
   • Check .csproj to identify TargetFramework.
   • Analyze project structure to confirm whether it uses N-Tier architecture or Vertical Slice.
   • Identify existing cross-cutting concern handling methods (filters, middleware).
2. Reason (Planning Phase):
   • Evaluate whether to introduce the "Problem Details" standard.
   • Determine whether to use the .NET 8+ global exception handling mechanism.
   • Choose an appropriate versioning strategy based on project scale.
3. Act (Execution Phase):
   • Write high-quality controllers compliant with [ApiController] conventions.
   • Implement strongly-typed and immutable DTOs (prioritize record).
   • Integrate dependency injection, prioritizing Primary Constructors (C# 12+).
4. Validate (Standard Validation):
   • Validate whether Action return types comply with ActionResult<T> specifications.
   • Check NRT (Nullable Reference Types) safety.
   • Ensure asynchronous operations correctly pass down CancellationToken.

Feature Roadmap (.NET 6 - 10)

.NET 6 & 7 (Foundation)

• Controllers Architecture: Traditional controller patterns and attribute routing.
• Problem Details: Unified error response standards.
• Output Caching: High-performance server-side caching.
• Nullable Reference Types: Comprehensive null safety support.

.NET 8 & 9 (Productivity)

• IExceptionHandler: More elegant centralized exception handling.
• Antiforgery: Built-in anti-forgery support for Web APIs.
• Keyed Services: More flexible dependency injection options.
• HybridCache: Multi-level caching optimization.

.NET 10+ (Version-Specific Features)

• Extension Members for Controllers: Extending base controller functionality.
• Enhanced Serialization: JSON optimization for large payloads.

Coding Standards

• Strong Typing: Prioritize ActionResult<T> to improve Swagger support.
• NRT Compliance: Strictly enforce Null safety to reduce runtime errors.
• Async Best Practices: Always accept and pass CancellationToken.
• Naming: Controller names must end with Controller, async methods must end with Async.

Deliver

• Version-Optimized Web API Code: Provide modernized controllers and configurations suitable for the target version.
• Architectural Insights: Provide refactoring suggestions for N-Tier or Clean Architecture.
• Security Recommendations: Provide security suggestions regarding Problem Details and exception handling.

Validate

• Ensure the code complies with C# 10+ modern syntax standards.
• Validate endpoints correctly return error formats compliant with RFC 7807.
• Confirm the code has no resource leaks in the tested environment (correct use of using and async).

Documentation

Official References

• ASP.NET Core Web API Overview
• Handle errors in ASP.NET Core web APIs (Problem Details)
• Controller action return types in ASP.NET Core web API

Internal References

• Web API Coding Style and Naming Conventions
• Web API Anti-Patterns and Best Practices
• Web API Modern Patterns Guide