starter ASP.NET Core Web API project with example

Starter ASP.NET Core Web API project that follows all the best practices listed above.

🛠️ Starter Project Overview

We’ll build a Product Catalog API with the following features:

🔧 Tech Stack:

ASP.NET Core 8
Entity Framework Core (In-Memory for now)
DTOs and Services
Validation
API Versioning
Swagger (OpenAPI)
Global Exception Handling
Logging
Async support
Dependency Injection
Clean architecture (Controllers → Services → Repository)

📁 Project Structure:

mathematica

ProductCatalogApi/
├── Controllers/
│   └── v1/
│       └── ProductsController.cs
├── Dtos/
│   └── ProductDto.cs
├── Entities/
│   └── Product.cs
├── Interfaces/
│   └── IProductService.cs
│   └── IProductRepository.cs
├── Repositories/
│   └── ProductRepository.cs
├── Services/
│   └── ProductService.cs
├── Middlewares/
│   └── ExceptionMiddleware.cs
├── Data/
│   └── ApplicationDbContext.cs
├── Program.cs
└── ProductCatalogApi.csproj

✅ 1. Initialize Project

Create the project:

bash

dotnet new webapi -n ProductCatalogApi
cd ProductCatalogApi

Enable nullable and implicit usings in csproj (optional):

xml

<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>

✅ 2. Create `Product` Entity

Entities/Product.cs

csharp

namespace ProductCatalogApi.Entities;

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
}

✅ 3. Create DTO

Dtos/ProductDto.cs

csharp

using System.ComponentModel.DataAnnotations;

namespace ProductCatalogApi.Dtos;

public class ProductDto
{
    public int Id { get; set; }

    [Required]
    [StringLength(100)]
    public string Name { get; set; } = string.Empty;

    [Range(0.01, 10000)]
    public decimal Price { get; set; }
}

✅ 4. ApplicationDbContext

Data/ApplicationDbContext.cs

csharp

using Microsoft.EntityFrameworkCore;
using ProductCatalogApi.Entities;

namespace ProductCatalogApi.Data;

public class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options) { }

    public DbSet<Product> Products => Set<Product>();
}

✅ 5. Repository

Interfaces/IProductRepository.cs

csharp

using ProductCatalogApi.Entities;

namespace ProductCatalogApi.Interfaces;

public interface IProductRepository
{
    Task<IEnumerable<Product>> GetAllAsync();
    Task<Product?> GetByIdAsync(int id);
    Task<Product> AddAsync(Product product);
    Task UpdateAsync(Product product);
    Task DeleteAsync(Product product);
}

Repositories/ProductRepository.cs

csharp

using Microsoft.EntityFrameworkCore;
using ProductCatalogApi.Data;
using ProductCatalogApi.Entities;
using ProductCatalogApi.Interfaces;

namespace ProductCatalogApi.Repositories;

public class ProductRepository : IProductRepository
{
    private readonly ApplicationDbContext _context;

    public ProductRepository(ApplicationDbContext context)
    {
        _context = context;
    }

    public async Task<IEnumerable<Product>> GetAllAsync() => await _context.Products.ToListAsync();
    public async Task<Product?> GetByIdAsync(int id) => await _context.Products.FindAsync(id);
    public async Task<Product> AddAsync(Product product)
    {
        _context.Products.Add(product);
        await _context.SaveChangesAsync();
        return product;
    }

    public async Task UpdateAsync(Product product)
    {
        _context.Products.Update(product);
        await _context.SaveChangesAsync();
    }

    public async Task DeleteAsync(Product product)
    {
        _context.Products.Remove(product);
        await _context.SaveChangesAsync();
    }
}

✅ 6. Service Layer

Interfaces/IProductService.cs

csharp

using ProductCatalogApi.Dtos;

namespace ProductCatalogApi.Interfaces;

public interface IProductService
{
    Task<IEnumerable<ProductDto>> GetAllAsync();
    Task<ProductDto?> GetByIdAsync(int id);
    Task<ProductDto> CreateAsync(ProductDto dto);
    Task<bool> UpdateAsync(int id, ProductDto dto);
    Task<bool> DeleteAsync(int id);
}

Services/ProductService.cs

csharp

using ProductCatalogApi.Dtos;
using ProductCatalogApi.Entities;
using ProductCatalogApi.Interfaces;

namespace ProductCatalogApi.Services;

public class ProductService : IProductService
{
    private readonly IProductRepository _repo;

    public ProductService(IProductRepository repo)
    {
        _repo = repo;
    }

    public async Task<IEnumerable<ProductDto>> GetAllAsync()
    {
        var products = await _repo.GetAllAsync();
        return products.Select(p => new ProductDto { Id = p.Id, Name = p.Name, Price = p.Price });
    }

    public async Task<ProductDto?> GetByIdAsync(int id)
    {
        var product = await _repo.GetByIdAsync(id);
        if (product == null) return null;
        return new ProductDto { Id = product.Id, Name = product.Name, Price = product.Price };
    }

    public async Task<ProductDto> CreateAsync(ProductDto dto)
    {
        var product = new Product { Name = dto.Name, Price = dto.Price };
        var result = await _repo.AddAsync(product);
        return new ProductDto { Id = result.Id, Name = result.Name, Price = result.Price };
    }

    public async Task<bool> UpdateAsync(int id, ProductDto dto)
    {
        var existing = await _repo.GetByIdAsync(id);
        if (existing == null) return false;

        existing.Name = dto.Name;
        existing.Price = dto.Price;
        await _repo.UpdateAsync(existing);
        return true;
    }

    public async Task<bool> DeleteAsync(int id)
    {
        var existing = await _repo.GetByIdAsync(id);
        if (existing == null) return false;

        await _repo.DeleteAsync(existing);
        return true;
    }
}

✅ 7. Controller

Controllers/v1/ProductsController.cs

csharp

using Microsoft.AspNetCore.Mvc;
using ProductCatalogApi.Dtos;
using ProductCatalogApi.Interfaces;

namespace ProductCatalogApi.Controllers.v1;

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly IProductService _service;

    public ProductsController(IProductService service)
    {
        _service = service;
    }

    [HttpGet]
    public async Task<IActionResult> GetAll() =>
        Ok(await _service.GetAllAsync());

    [HttpGet("{id}")]
    public async Task<IActionResult> Get(int id)
    {
        var product = await _service.GetByIdAsync(id);
        if (product == null) return NotFound();
        return Ok(product);
    }

    [HttpPost]
    public async Task<IActionResult> Create(ProductDto dto)
    {
        if (!ModelState.IsValid) return BadRequest(ModelState);
        var product = await _service.CreateAsync(dto);
        return CreatedAtAction(nameof(Get), new { id = product.Id }, product);
    }

    [HttpPut("{id}")]
    public async Task<IActionResult> Update(int id, ProductDto dto)
    {
        if (!ModelState.IsValid) return BadRequest(ModelState);
        var updated = await _service.UpdateAsync(id, dto);
        return updated ? NoContent() : NotFound();
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> Delete(int id)
    {
        var deleted = await _service.DeleteAsync(id);
        return deleted ? NoContent() : NotFound();
    }
}

✅ 8. Middleware for Error Handling

Middlewares/ExceptionMiddleware.cs

csharp

namespace ProductCatalogApi.Middlewares;

public class ExceptionMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionMiddleware> _logger;

    public ExceptionMiddleware(RequestDelegate next, ILogger<ExceptionMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Unhandled Exception");
            context.Response.StatusCode = 500;
            await context.Response.WriteAsJsonAsync(new { error = "An unexpected error occurred." });
        }
    }
}

✅ 9. Configure Program.cs

Program.cs

csharp

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using ProductCatalogApi.Data;
using ProductCatalogApi.Interfaces;
using ProductCatalogApi.Middlewares;
using ProductCatalogApi.Repositories;
using ProductCatalogApi.Services;

var builder = WebApplication.CreateBuilder(args);

// DB
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseInMemoryDatabase("ProductDb"));

// Services
builder.Services.AddScoped<IProductService, ProductService>();
builder.Services.AddScoped<IProductRepository, ProductRepository>();

// Swagger
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Versioning
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});

// Controllers
builder.Services.AddControllers();

var app = builder.Build();

// Middlewares
app.UseMiddleware<ExceptionMiddleware>();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

✅ 10. Run the App


dotnet run

Visit:

Swagger: https://localhost:{port}/swagger
Try endpoints like:
- GET /api/v1/products
- POST /api/v1/products

People Who Code | Blog