Neo Dotnet Minimal Apis

.NET Minimal APIs Expert Skill

Trigger On

• The user requests to create, debug, refactor, or review .NET Minimal APIs.
• The project's Program.cs contains WebApplication.CreateBuilder(args) and is not configured with a Controllers directory.
• The target framework is .NET 6.0 (LTS) and above.
• There is a need to optimize API performance or simplify Web API architecture.

Workflow

1. Perceive (Architecture Awareness):

• Check .csproj to identify TargetFramework.
• Analyze Program.cs to distinguish whether it uses simple endpoints or adopts a Module-based or Vertical Slice organization.
• Identify whether OpenAPI (Swagger) support has been configured.

1. Reason (Planning Phase):

• Evaluate whether "Route Groups" need to be introduced to optimize organizational structure.
• Determine whether to use "Endpoint Filters" to handle cross-cutting concerns (such as parameter validation).
• Choose the most appropriate syntax based on the .NET version (e.g., TypedResults in .NET 7+).

1. Act (Execution Phase):

• Write clean, high-performance Minimal API code, prioritizing Lambdas or extension methods.
• Implement strong typing and DTOs (prioritize using record).
• Integrate dependency injection, avoiding the Service Locator pattern.

1. Validate (Standard Validation):

• Validate whether the endpoints correctly return expected HTTP status codes.
• Check whether the generated OpenAPI documentation is complete.
• Ensure asynchronous operations correctly pass the CancellationToken.

Feature Roadmap (.NET 6 - 10)

.NET 6 & 7 (Foundation)

• Minimal Hosting: Simplified startup process and top-level statements.
• Route Groups: Use MapGroup to consolidate prefixes and authentication.
• Endpoint Filters: Implement interception logic within Minimal APIs.
• Typed Results: Improved unit testing and Swagger support.

.NET 8 & 9 (Productivity)

• Antiforgery: Built-in anti-forgery token support.
• Form Binding: Support for [FromForm] parameter binding.
• HybridCache: High-performance multi-level caching support.
• OpenAPI Improvements: Better OpenAPI code generation.

.NET 10+ (Version-Specific Features)

• Native AOT Optimization: AOT-optimized compilation tailored for Minimal APIs.
• Enhanced Middleware Patterns: New middleware designed for lightweight architectures.

Coding Standards

• Clean Routing: Prioritize using extension methods to modularize routes.
• Strong Typing: Prioritize using TypedResults and Results.
• Async Safety: Always accept and pass down CancellationToken.
• DI Best Practices: Services should be defined directly in the Handler parameters.

Deliver

• Version-Optimized API Code: Provide the most appropriate modern API code based on the target .NET version.
• Modular Architecture: Provide structural suggestions for extracting Program.cs routes into extension methods.
• OpenAPI Configuration: Provide comprehensive Swagger/OpenAPI configuration suggestions.

Validate

• Ensure the provided code executes correctly in a .NET 6+ environment.
• Validate endpoint security (authentication, authorization, Antiforgery).
• Check if the code complies with high-performance best practices for Minimal APIs (e.g., avoiding closures, reducing allocations).

Documentation

Official References

• Minimal APIs Overview
• Route groups and filters
• Typed responses in Minimal APIs

Internal References

• [Minimal APIs Coding Style and Naming Conventions](reference/coding-style.md)
• [Minimal APIs Anti-Patterns and Best Practices](reference/anti-patterns.md)
• [Minimal APIs Modern Patterns Guide](reference/patterns.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Benknightdark
• Source: Benknightdark/neo-skills
• License: MIT
• Homepage: https://neo-blog-iota.vercel.app/

Install and usage instructions live in the source repository linked above.