Why should you care?

Exposing EF entities in JSON ties your API to database columns forever. DTOs let you rename tables without breaking mobile apps.

See it live — copy this example

Create a Web API project (dotnet new webapi), paste the code, then run dotnet run.

public record OrderLineDto(int ProductId, int Qty, decimal UnitPrice);

public record CreateOrderDto(Guid CustomerId, List<OrderLineDto> Lines);

public static class OrderMappings
{
    public static Order ToEntity(CreateOrderDto dto) => new()
    {
        CustomerId = dto.CustomerId,
        Lines = dto.Lines.Select(l => new OrderLine
        {
            ProductId = l.ProductId,
            Qty = l.Qty,
            UnitPrice = l.UnitPrice
        }).ToList()
    };

    public static OrderSummaryDto ToSummary(Order o) => new(o.Id, o.Status, o.Total);
}

Run Example »

Edit the code and click Run — like W3Schools Try it Yourself.

What happened?

• CreateOrderDto comes from HTTP.
• ToEntity builds domain Order.
• ToSummary returns safe fields to client — no internal navigation properties.

Try it yourself

1. Create DTOs in Order.Api/Dtos/ folder.
2. Add OrderMappings static class.
3. MapPost uses ToEntity before SaveChanges.
4. Change a string or number in the example and run again — predict the output first.
5. Break the code on purpose (remove a semicolon), read the compiler error, then fix it.

Remember

DTOs = API shape; entities = database/domain shape. Map in one place per direction. Do not leak EF entities over HTTP.

Real-world: Mobile app versioning

App v1 uses OrderSummaryDto with three fields. v2 adds EstimatedDelivery — new DTO or optional field without breaking v1.

Outcome: Backend evolves; old apps keep working until users upgrade.