Table of Contents

Getting Started

This guide walks you through installing MapCrud and registering your first CRUD endpoints.

Prerequisites

  • .NET 8, 9, or 10
  • An ASP.NET Core Minimal API project
  • (Optional) Entity Framework Core if using EF Core storage

Installation

Install MapCrud and one storage provider:

# Core package (required)
dotnet add package MapCrud

# Choose one storage backend:
dotnet add package MapCrud.InMemory            # in-memory (testing / prototyping)
dotnet add package MapCrud.EntityFrameworkCore # EF Core (production)

# Optional: Mapperly source-generated mappers
dotnet add package MapCrud.Mapperly

Minimal Setup (In-Memory)

var builder = WebApplication.CreateBuilder(args);

// Register MapCrud with the in-memory storage provider
builder.Services.AddMapCrud();

var app = builder.Build();

// Register all five CRUD endpoints for the Product entity
app.MapCrud<Product>("products");

app.Run();

public class Product
{
    public Guid Id { get; set; }
    public string Name { get; set; } = "";
    public decimal Price { get; set; }
}

This registers five endpoints:

Method Route Description
GET /products List with pagination, sorting, filtering
GET /products/{id} Get by ID
POST /products Create new
PUT /products/{id} Replace existing
DELETE /products/{id} Delete (hard delete or soft delete for ISoftDeletable)

Setup with Entity Framework Core

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

// Register MapCrud with EF Core
builder.Services.AddMapCrud<AppDbContext>(options =>
    options.UseEnvelope()            // wrap responses in { success, data, errors }
           .UsePagination(20));      // paginate by default with 20 items per page

var app = builder.Build();

app.MapCrud<Product>("products");
app.MapCrud<Order>("orders", o => o.OnlyGet());  // read-only

app.Run();

Setup with DTO Mapping

// Use separate request/response types
app.MapCrud<Product>("products", o => o
    .WithRequest<CreateProductDto>()
    .WithResponse<ProductDto>());

MapCrud uses ReflectionMapper by default to map between entity and DTO types, supporting:

  • Exact property name matching
  • Convention-based flattening (dto.CustomerName ← entity.Customer.Name)
  • [MapFrom("path")] attribute for explicit nested paths
  • .MapProperty() fluent overrides

See DTO Mapping for full details.

Query Parameters

All GET list endpoints support these built-in query parameters:

Parameter Description Example
page Page number (1-based) ?page=2
pagesize Items per page (max 1000) ?pagesize=50
sortby Sort field(s), prefix - for descending ?sortby=-createdAt,name
include Navigation properties to eager-load ?include=Category,Tags
includeDeleted Include soft-deleted entities ?includeDeleted=true
{propertyName} Filter by any public DTO property ?name=Widget&price=9.99

Next Steps

Edit this page