Introduction to Carter

If you’ve ever found your Program.cs file cluttered with endpoint mappings, you’re not alone. As your API grows, this approach can become unwieldy, making your code harder to maintain.

Carter is a lightweight and flexible routing library for ASP.NET Core that simplifies the creation of RESTful APIs. It provides a straightforward way to define routes and handle HTTP requests, enabling developers to build APIs with less boilerplate code and improved maintainability.

Advantages of Carter

• Simplified Routing: Carter streamlines route definitions, making it easier to manage and understand routing in your application. You can define routes using simple and intuitive syntax.
• Reduced Boilerplate Code: It minimizes the amount of boilerplate code required for setting up routes and handling HTTP requests, allowing you to focus more on your application’s core logic.
• Convention-Based Routing: Carter uses convention-based routing, which simplifies the process of mapping endpoints to handlers. This reduces the need for repetitive code and promotes consistency.
• Enhanced Readability: The code structure is cleaner and more readable compared to traditional ASP.NET Core routing, thanks to its concise syntax and organizational patterns.
• Built-In Support for Middleware: Carter integrates seamlessly with ASP.NET Core middleware, allowing you to leverage the full power of the ASP.NET Core pipeline, including authentication, authorization, and error handling.
• Strong Typing and Validation: It provides strong typing for routes and parameters, which helps catch errors at compile time and improves code quality. Additionally, it supports model validation out of the box.
• Scalability: Carter is designed to scale with your application. Its modular approach allows you to manage and extend routes easily as your project grows.
• Enhanced Testing: The clear separation of route definitions and handlers makes it easier to write unit tests and integration tests for your API endpoints.
• Integration with ASP.NET Core Features: Carter works well with other ASP.NET Core features, such as dependency injection and configuration, allowing for a cohesive development experience.
• Community and Support: As an open-source project, Carter benefits from community contributions and support, providing access to a range of resources and solutions.

Examples of Usage

1. Install the nuget package

Begin by adding Carter to your project via NuGet. You can do this through Visual Studio: Right-click on your project -> Manage NuGet Packages… -> Browse, search for “Carter,” select it, and click Install.

2. Review Your Current Endpoints

Your endpoints are likely mapped directly in your Program.cs file, resembling something like this:

public class Program
{
    public static void Main(string[] args)
    {
        // Services injection and other stuff

        app.MapGet("api/task", (HttpContext httpContext) =>
        {
            // .................... Logic
            return task;
        })
        .WithName("GetTask")
        .WithOpenApi();

        app.MapPost("api/task", (HttpContext httpContext) =>
        {
            // .................... Logic
            return task;
        })
        .WithName("PostTask")
        .WithOpenApi();
        // ....................................................................
    }
}

3. Create a Carter Module for each Endpoint

Replace your inline endpoints with modular Carter modules:

public class GetTaskModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapGet("api/task", (HttpContext httpContext) =>
        {
            // .................... Logic
            return task;
        })
        .WithName("GetTask")
        .WithOpenApi();
    }
}

public class AddTaskModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPost("api/task", (HttpContext httpContext) =>
        {
            // .................... Logic
            return task;
        })
        .WithName("PostTask")
        .WithOpenApi();
    }
}

4. Remove the endpoints from program.cs

To avoid conflicts, delete the old endpoint mappings from your Program.cs file.

5. Register carter in program.cs

public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);

    
    builder.Services.AddCarter();
    // ....................

6. Map carter modules

Finally, map Carter modules in your Program.cs to register all implementations of ICarterModule.

public static void Main(string[] args)
{
    // ....................
    app.MapCarter();
    // ....................

    app.Run();
}    

Now, your endpoints are cleanly separated into modules, making your API easier to maintain and scale. Enjoy your streamlined development with Carter!