Picture an e-commerce application where a customer updates their shipping address. That simple action flows through your API controller, gets validated in your business logic layer, and finally saves to your database. Each tier has different concerns and needs to work with data in its own way.
Passing your database entities directly through all these layers creates tight coupling. When you change your database schema, your API breaks. When you add a navigation property to an entity, you might accidentally serialize your entire object graph. Data Transfer Objects solve these problems by creating clear boundaries between layers.
You'll learn how to structure data transfer between your presentation, business, and data layers using DTOs, view models, and mapping strategies. We'll cover manual mapping, AutoMapper integration, and patterns that scale from simple CRUD apps to complex distributed systems.
A Data Transfer Object is a simple container for moving data between layers. It has no behavior, just properties. DTOs give you control over what data crosses layer boundaries and let you shape that data differently than your domain models.
When your web API receives a request, it binds the JSON to a DTO. Your controller passes that DTO to your service layer, which maps it to a domain entity. The service performs business logic and returns another DTO back to the controller. This separation keeps each layer independent.
// Domain entity - lives in your data layer
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public string Description { get; set; }
public decimal Price { get; set; }
public int Stock { get; set; }
public DateTime CreatedAt { get; set; }
public DateTime? UpdatedAt { get; set; }
public bool IsActive { get; set; }
// Navigation properties
public Category Category { get; set; }
public List Reviews { get; set; }
}
// DTO for creating products - only what users can set
public class CreateProductDto
{
public string Name { get; set; }
public string Description { get; set; }
public decimal Price { get; set; }
public int CategoryId { get; set; }
}
// DTO for reading products - shaped for display
public class ProductDto
{
public int Id { get; set; }
public string Name { get; set; }
public string Description { get; set; }
public decimal Price { get; set; }
public string CategoryName { get; set; }
public int ReviewCount { get; set; }
public decimal AverageRating { get; set; }
}
// DTO for listing products - minimal data
public class ProductListDto
{
public int Id { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
public bool InStock { get; set; }
} Notice how each DTO serves a specific purpose. CreateProductDto only includes fields users can set, preventing them from manipulating Id or CreatedAt. ProductDto combines data from multiple entities for display. ProductListDto minimizes payload size for list views. This granularity gives you flexibility without exposing internal structures.
Manual mapping gives you complete control over how data transforms between types. You write explicit code that copies properties from one object to another. This approach is simple, performant, and easy to debug.
Many developers reach for AutoMapper immediately, but manual mapping often works better for small projects or when mappings involve complex logic. You'll see exactly what's happening without hidden conventions or reflection overhead.
public class ProductService
{
private readonly AppDbContext _context;
public ProductService(AppDbContext context)
{
_context = context;
}
public async Task GetProductByIdAsync(int id)
{
var product = await _context.Products
.Include(p => p.Category)
.Include(p => p.Reviews)
.FirstOrDefaultAsync(p => p.Id == id);
if (product == null)
return null;
// Manual mapping from entity to DTO
return new ProductDto
{
Id = product.Id,
Name = product.Name,
Description = product.Description,
Price = product.Price,
CategoryName = product.Category?.Name,
ReviewCount = product.Reviews?.Count ?? 0,
AverageRating = product.Reviews?.Any() == true
? product.Reviews.Average(r => r.Rating)
: 0
};
}
public async Task CreateProductAsync(CreateProductDto dto)
{
// Manual mapping from DTO to entity
var product = new Product
{
Name = dto.Name,
Description = dto.Description,
Price = dto.Price,
CategoryId = dto.CategoryId,
CreatedAt = DateTime.UtcNow,
IsActive = true,
Stock = 0
};
_context.Products.Add(product);
await _context.SaveChangesAsync();
return product.Id;
}
public async Task> GetProductsAsync()
{
return await _context.Products
.Where(p => p.IsActive)
.Select(p => new ProductListDto
{
Id = p.Id,
Name = p.Name,
Price = p.Price,
InStock = p.Stock > 0
})
.ToListAsync();
}
} This manual approach makes the mapping logic crystal clear. You can add calculations like AverageRating or set default values like IsActive without any configuration. The Select method projects directly to DTOs in the database query, reducing memory usage and improving performance.
AutoMapper shines when you have many entities with similar structures. Instead of writing repetitive mapping code, you configure conventions once and let AutoMapper handle the details. It automatically maps properties with matching names and provides hooks for custom transformations.
The trade-off is added complexity. You need to configure mappings, understand AutoMapper's conventions, and debug through reflection-based code when things go wrong. Use it when the benefit of reduced boilerplate outweighs these costs.
using AutoMapper;
public class MappingProfile : Profile
{
public MappingProfile()
{
// Simple mapping - properties match by name
CreateMap()
.ForMember(dest => dest.CreatedAt, opt => opt.MapFrom(_ => DateTime.UtcNow))
.ForMember(dest => dest.IsActive, opt => opt.MapFrom(_ => true))
.ForMember(dest => dest.Stock, opt => opt.MapFrom(_ => 0));
// Complex mapping - custom transformations
CreateMap()
.ForMember(dest => dest.CategoryName,
opt => opt.MapFrom(src => src.Category.Name))
.ForMember(dest => dest.ReviewCount,
opt => opt.MapFrom(src => src.Reviews.Count))
.ForMember(dest => dest.AverageRating,
opt => opt.MapFrom(src => src.Reviews.Any()
? src.Reviews.Average(r => r.Rating)
: 0));
CreateMap()
.ForMember(dest => dest.InStock, opt => opt.MapFrom(src => src.Stock > 0));
}
}
// Service using AutoMapper
public class ProductService
{
private readonly AppDbContext _context;
private readonly IMapper _mapper;
public ProductService(AppDbContext context, IMapper mapper)
{
_context = context;
_mapper = mapper;
}
public async Task GetProductByIdAsync(int id)
{
var product = await _context.Products
.Include(p => p.Category)
.Include(p => p.Reviews)
.FirstOrDefaultAsync(p => p.Id == id);
return _mapper.Map(product);
}
public async Task CreateProductAsync(CreateProductDto dto)
{
var product = _mapper.Map(dto);
_context.Products.Add(product);
await _context.SaveChangesAsync();
return product.Id;
}
} AutoMapper reduces repetitive code significantly. The Map method handles the tedious property copying, and ForMember configurations specify custom logic. This centralized approach makes it easier to change how mappings work across your application.
Your controllers act as the boundary between the outside world and your application. They receive DTOs from HTTP requests, pass them to services, and return DTOs in responses. This keeps your controllers thin and focused on HTTP concerns.
ASP.NET Core's model binding automatically deserializes JSON into your DTOs. Built-in validation runs before your action method executes. The controller remains unaware of your domain entities, working exclusively with DTOs.
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
private readonly ProductService _productService;
public ProductsController(ProductService productService)
{
_productService = productService;
}
[HttpGet]
public async Task>> GetProducts()
{
var products = await _productService.GetProductsAsync();
return Ok(products);
}
[HttpGet("{id}")]
public async Task> GetProduct(int id)
{
var product = await _productService.GetProductByIdAsync(id);
if (product == null)
return NotFound();
return Ok(product);
}
[HttpPost]
public async Task> CreateProduct(
CreateProductDto dto)
{
if (!ModelState.IsValid)
return BadRequest(ModelState);
var productId = await _productService.CreateProductAsync(dto);
var product = await _productService.GetProductByIdAsync(productId);
return CreatedAtAction(
nameof(GetProduct),
new { id = productId },
product);
}
[HttpPut("{id}")]
public async Task UpdateProduct(
int id,
UpdateProductDto dto)
{
if (!ModelState.IsValid)
return BadRequest(ModelState);
var updated = await _productService.UpdateProductAsync(id, dto);
if (!updated)
return NotFound();
return NoContent();
}
} The controller knows nothing about Product entities or database concerns. It receives CreateProductDto, passes it to the service, and returns ProductDto. This separation makes testing easier and lets you change your database structure without touching your API contract.
Here's a minimal working example you can run. This demonstrates the complete flow from controller through service to data layer using DTOs.
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="8.0.0" />
</ItemGroup>
</Project>using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext(options =>
options.UseInMemoryDatabase("Demo"));
builder.Services.AddScoped();
builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
}
public class CreateProductDto
{
public string Name { get; set; }
public decimal Price { get; set; }
}
public class ProductDto
{
public int Id { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
}
public class AppDbContext : DbContext
{
public AppDbContext(DbContextOptions options)
: base(options) { }
public DbSet Products { get; set; }
}
// Output when you POST to /api/products:
// {"id":1,"name":"Laptop","price":999.99} Run this with dotnet run and test with curl or Postman. POST a CreateProductDto to create a product, then GET to retrieve it as a ProductDto. The data transforms through each layer while maintaining clean separation.
The most common mistake is exposing domain entities directly in your API. When you return an entity from a controller, EF Core's navigation properties can cause circular references during JSON serialization. Even if you configure the serializer to handle this, you're coupling your API contract to your database schema.
Another pitfall is creating one DTO for all operations. A ProductDto used for both creating and updating products forces you to handle null values and make properties optional when they shouldn't be. Separate DTOs for create, update, and read operations provide better validation and clearer intent.
Over-mapping causes performance problems. If you query an entity with Include statements just to map three properties to a DTO, you're loading unnecessary data. Use Select to project directly to DTOs in your queries when possible.
AutoMapper configuration errors fail at runtime, not compile time. Forgetting to configure a mapping or misconfiguring a complex property transformation won't surface until that code path executes. Always validate your AutoMapper configuration during startup and write tests for critical mappings.
Passing domain entities directly couples your presentation layer to your data model. When the database schema changes, your API contracts break. DTOs create a stable boundary that lets you evolve each layer independently and control exactly what data gets exposed.
Use AutoMapper when you have many similar mappings with mostly one-to-one property relationships. Manual mapping works better for complex transformations, performance-critical paths, or when you want explicit control. Simple projects often don't need AutoMapper's added complexity.
DTOs transfer data between architectural layers or services. View models are presentation-specific types shaped for UI needs. A DTO might map directly to a database entity, while a view model combines data from multiple sources and includes display logic.
Validate input in the presentation layer using data annotations or FluentValidation. Perform business rule validation in the service layer. Keep domain entities responsible for maintaining their invariants. Each layer validates what it owns.
Not necessarily. Create DTOs based on use cases, not entities. You might have CreateProductDto, UpdateProductDto, and ProductListDto for one Product entity. Or combine multiple entities into a single DTO when they're always used together.
Use separate DTOs for create and update operations that only include properties users should modify. Never bind directly to domain entities. Your DTO acts as a whitelist, accepting only expected properties and preventing users from modifying protected fields.