ASP.NET Core Project Structure: A Complete Guide to the dotnet/aspnetcore Repository

The ASP.NET Core repository organizes its modular framework components into a layered architecture under the src/ directory, with separate folders for servers, hosting, HTTP abstractions, routing, MVC, SignalR, and tooling, alongside docs/ for documentation and eng/ for build infrastructure.

The dotnet/aspnetcore repository contains the complete source code for Microsoft's cross-platform web framework. Understanding this project structure reveals how discrete, version-aligned components are composed to support everything from minimal APIs to complex MVC applications, with each functional area isolated into its own buildable project under the src/ tree.

Top-Level Repository Layout

The repository root separates concerns into four primary areas:

• src/ – Contains all production framework code, including servers, middleware, security, and extensions. Every NuGet package shipped by the framework originates here.
• docs/ – Markdown documentation that powers the official Microsoft Learn site, including architecture guides, build instructions, and API references.
• eng/ – Build infrastructure, MSBuild targets, CI/CD scripts, and engineering tooling used to compile and test the entire stack.
• README.md, CONTRIBUTING.md, LICENSE.txt – Repository metadata and contribution guidelines.

Sample applications and test suites typically reside within the relevant src/* subdirectories (e.g., src/Mvc/samples/ and src/Mvc/test/) rather than in a single top-level test folder.

The src/ Directory: Modular Framework Components

All runtime libraries live under src/, grouped by functional domain. Each folder represents a distinct subsystem that publishes one or more NuGet packages:

• Servers/ – Web server implementations including Kestrel (Microsoft.AspNetCore.Server.Kestrel), IIS integration, and HTTP.sys.
• Hosting/ – The generic host abstraction (Microsoft.AspNetCore.Hosting), managing application lifetime, dependency injection, configuration, and environment.
• Http/ – Core HTTP primitives such as HttpContext, request/response abstractions, and the middleware pipeline foundation.
• Routing/ – Endpoint routing and route-template parsing (Microsoft.AspNetCore.Routing), unified across MVC, Razor Pages, and Minimal APIs.
• Mvc/ – The Model-View-Controller framework (Microsoft.AspNetCore.Mvc), including controllers, action filters, and model binding.
• Razor/ – The Razor view engine and runtime compilation (Microsoft.AspNetCore.Razor.Runtime).
• SignalR/ – Real-time communication hubs and clients (Microsoft.AspNetCore.SignalR).
• Components/ – Blazor WebAssembly and Server components (Microsoft.AspNetCore.Components.Server), plus related UI tooling.
• Security/ – Authentication, authorization, antiforgery, and Identity services.
• DataProtection/ – Cryptographic data-protection extensions (Microsoft.AspNetCore.DataProtection.Extensions).
• Caching/ – In-memory, distributed, and StackExchangeRedis caching implementations.
• Grpc/ – gRPC host and client integration for ASP.NET Core.
• Localization/ – Resource-based localization and globalization services.
• Tools/ – Developer CLI tools such as dotnet-user-secrets and dotnet-dev-certs.

Each folder contains its own src/, test/, and samples/ subdirectories, enabling isolated development and testing of individual components.

Layered Runtime Architecture from Source to Endpoint

The repository structure mirrors a six-layer runtime stack that processes HTTP requests:

1. Server Layer – Concrete implementations in src/Servers/ (Kestrel, IIS, HttpSys) expose low-level socket APIs and forward requests to the hosting layer. The core Kestrel project resides at src/Servers/Kestrel/src/Microsoft.AspNetCore.Server.Kestrel.Core.csproj.

2. Hosting Layer – src/Hosting/ provides IHost and IWebHost abstractions, managing the DI container, logging, and configuration. Primary source is src/Hosting/src/Microsoft.AspNetCore.Hosting.csproj.

3. HTTP Middleware Pipeline – src/Http/ defines the HttpContext and request delegate chain. Middleware components for static files, error handling, and authentication extend this pipeline. Entry point: src/Http/src/Microsoft.AspNetCore.Http.csproj.

4. Routing & Endpoint Layer – src/Http/Routing/ matches URLs to endpoints using the shared routing abstractions in src/Http/Routing.Abstractions/src/Microsoft.AspNetCore.Routing.Abstractions.csproj.

5. Feature Layers – Higher-level frameworks like MVC (src/Mvc/src/Microsoft.AspNetCore.Mvc.csproj), Razor (src/Razor/Razor.Runtime/src/Microsoft.AspNetCore.Razor.Runtime.csproj), SignalR (src/SignalR/src/Microsoft.AspNetCore.SignalR.csproj), and Blazor (src/Components/Server/src/Microsoft.AspNetCore.Components.Server.csproj) extend the pipeline with their own APIs while remaining loosely coupled.

6. Extensions & Tools – Cross-cutting concerns like data protection (src/DataProtection/Extensions/src/Microsoft.AspNetCore.DataProtection.Extensions.csproj), distributed caching (src/Caching/StackExchangeRedis/src/Microsoft.Extensions.Caching.StackExchangeRedis.csproj), and developer tools (src/Tools/dotnet-user-secrets/src/dotnet-user-secrets.csproj) provide ancillary services.

Key Source Files and Project Entry Points

The following table maps major framework features to their primary project files in the src/ tree:

Component	Primary Project File
Kestrel Server Core	src/Servers/Kestrel/src/Microsoft.AspNetCore.Server.Kestrel.Core.csproj
Hosting Abstractions	src/Hosting/src/Microsoft.AspNetCore.Hosting.csproj
HTTP Primitives	src/Http/src/Microsoft.AspNetCore.Http.csproj
Routing Abstractions	src/Http/Routing.Abstractions/src/Microsoft.AspNetCore.Routing.Abstractions.csproj
MVC Framework	src/Mvc/src/Microsoft.AspNetCore.Mvc.csproj
Razor Runtime	src/Razor/Razor.Runtime/src/Microsoft.AspNetCore.Razor.Runtime.csproj
SignalR Core	src/SignalR/src/Microsoft.AspNetCore.SignalR.csproj
Data Protection	src/DataProtection/Extensions/src/Microsoft.AspNetCore.DataProtection.Extensions.csproj
Distributed Caching (Redis)	src/Caching/StackExchangeRedis/src/Microsoft.Extensions.Caching.StackExchangeRedis.csproj
Blazor Server	src/Components/Server/src/Microsoft.AspNetCore.Components.Server.csproj
User Secrets CLI Tool	src/Tools/dotnet-user-secrets/src/dotnet-user-secrets.csproj

Practical Implementation Examples

The repository structure directly supports three common application patterns:

Minimal API (No MVC)

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello from ASP.NET Core minimal API!");

app.Run();

This uses Microsoft.AspNetCore.App, which aggregates the Hosting, Routing, and Kestrel projects from src/Hosting/, src/Routing/, and src/Servers/.

MVC Controller

public class HomeController : Controller
{
    public IActionResult Index() => View();
}

Relevant sources: src/Mvc/src/Microsoft.AspNetCore.Mvc.csproj for the controller infrastructure and src/Razor/Razor.Runtime/src/Microsoft.AspNetCore.Razor.Runtime.csproj for view resolution.

SignalR Hub

public class ChatHub : Hub
{
    public async Task SendMessage(string user, string message) =>
        await Clients.All.SendAsync("ReceiveMessage", user, message);
}

Source implementation: src/SignalR/src/Microsoft.AspNetCore.SignalR.csproj.

Summary

• The dotnet/aspnetcore repository separates production code (src/), documentation (docs/), and build engineering (eng/) at the root level.
• The src/ directory contains modular subsystems—Servers, Hosting, Http, Routing, Mvc, SignalR, Components, Security, and others—each publishable as independent NuGet packages.
• Architecture follows a six-layer stack: Servers → Hosting → HTTP Middleware → Routing → Feature Layers (MVC/SignalR/Blazor) → Extensions.
• Key project files like Microsoft.AspNetCore.Server.Kestrel.Core.csproj and Microsoft.AspNetCore.Mvc.csproj map directly to the folders described, confirming the modular design.
• Code examples compile against specific src/ paths, demonstrating how developers consume these libraries in minimal APIs, MVC applications, and real-time services.

Frequently Asked Questions

What is the purpose of the eng/ folder in the aspnetcore repository?

The eng/ folder contains MSBuild targets, CI/CD pipeline definitions, and engineering scripts required to build, test, and package the entire framework. It centralizes versioning logic and build configuration that spans across all src/ components, ensuring consistent compilation flags and output formats across the repository.

How does the repository separate server implementations from framework logic?

Server implementations reside in src/Servers/ (Kestrel, IIS, HttpSys), which handle low-level HTTP protocol and socket management. These implement abstractions defined in src/Hosting/ and src/Http/, allowing the higher-level framework (routing, MVC, etc.) to remain agnostic of the specific server technology processing the request.

Where are Blazor components located in the project structure?

Blazor Server and WebAssembly components are located under src/Components/. Specifically, src/Components/Server/src/Microsoft.AspNetCore.Components.Server.csproj contains the server-side Blazor implementation, while WebAssembly-specific code resides in related subdirectories within src/Components/.

What is the relationship between the src/Http and src/Routing directories?

The src/Http directory provides fundamental HTTP abstractions like HttpContext and the middleware pipeline, while src/Routing (which extends src/Http/Routing/) provides endpoint matching and dispatch logic. Routing builds upon the HTTP primitives, allowing the framework to map incoming requests to specific endpoints using the shared HttpContext defined in src/Http/src/Microsoft.AspNetCore.Http.csproj.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}