What Is the `src` Directory in ASP.NET Core? Purpose and Architecture Explained

The src directory in the dotnet/aspnetcore repository contains the actual source code for every ASP.NET Core framework component, organized by functional concern into modular libraries such as Http, Hosting, Mvc, SignalR, and Security.

The src folder serves as the architectural backbone of ASP.NET Core. Located at the root of the dotnet/aspnetcore repository, this directory houses all production code, tests, samples, and documentation for the entire framework. Understanding its structure is essential for contributors, advanced users, and anyone seeking to extend or debug ASP.NET Core applications.

Modular Design by Functional Concern

Each sub-directory under src/ corresponds to a distinct, independently versioned library. This design enables selective dependency consumption—developers reference only the components they need without pulling in unnecessary functionality.

Key top-level directories include:

• src/Http/ – HTTP abstractions, server implementations, routing, and middleware infrastructure
• src/Hosting/ – Generic host, web host builders, and application startup lifecycle
• src/Mvc/ – Model-View-Controller framework, Razor pages, and view engines
• src/SignalR/ – Real-time bidirectional communication library
• src/Security/ – Authentication, authorization, and identity middleware

Each component follows consistent conventions: a README.md describing purpose and usage, project files (.csproj), implementation source, dedicated test/ folders, and sample applications.

Consistent Build and Test Structure

The src directory enforces uniform patterns that enable both holistic and granular builds. According to the ASP.NET Core source code, every component contains:

• Implementation projects – The actual library code shipped as NuGet packages
• Test projects – Unit and integration tests co-located with source
• README documentation – Immediate context without leaving the codebase
• Sample applications – Working demonstrations of component capabilities

This structure allows the repository to build entirely via build.cmd or build.sh, while individual components can be developed in isolation using dotnet build within their respective folders.

Cross-Component Dependencies and Layering

Higher-level libraries depend on lower-level ones through NuGet package references that mirror the physical folder hierarchy. The dependency flow starts with foundational abstractions and builds upward:

src/Http/Http.Abstractions          (lowest level: IHttpContext, request/response)
    ↓
src/Http/Routing                    (endpoint routing, URL matching)
    ↓
src/Mvc/Mvc.Core                    (controller infrastructure, model binding)
    ↓
src/Mvc/Mvc                         (complete MVC framework with views)

For example, Microsoft.AspNetCore.Mvc packages reference Microsoft.AspNetCore.Routing, which in turn references Microsoft.AspNetCore.Http.Abstractions—all originating from their corresponding src/ locations.

Runtime Composition from src Components

The following minimal ASP.NET Core application demonstrates how runtime objects map directly to src directory sources:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

var builder = WebApplication.CreateBuilder(args);

// Services from src/Mvc and src/Http/Routing
builder.Services.AddControllers();
builder.Services.AddRouting();

var app = builder.Build();

// Middleware pipeline using src/Hosting and src/Http components
app.UseRouting();
app.UseEndpoints(endpoints =>
{
    endpoints.MapGet("/", async ctx =>
    {
        // HttpContext defined in src/Http/Http.Abstractions
        await ctx.Response.WriteAsync("Hello from ASP.NET Core!");
    });
    
    endpoints.MapControllers();
});

app.Run();

In this snippet:

• WebApplication and WebApplication.CreateBuilder originate from src/Hosting/
• AddRouting() and UseRouting() implement endpoint routing from src/Http/Routing/
• HttpContext and response writing use abstractions from src/Http/Http.Abstractions/
• AddControllers() and MapControllers() invoke the MVC framework from src/Mvc/

Key Source Files and Documentation

The src directory places documentation adjacent to implementation for immediate reference:

Component	Source Location	Purpose
HTTP fundamentals	src/Http/README.md	HTTP abstractions, servers, and middleware
Application hosting	src/Hosting/README.md	Host builders and startup patterns
MVC framework	src/Mvc/README.md	Controllers, views, and Razor Pages
Real-time messaging	src/SignalR/README.md	WebSocket-based persistent connections
Security middleware	src/Security/README.md	Authentication and authorization
Resilient HTTP clients	src/HttpClientFactory/Polly/src/PolicyHttpMessageHandler.cs	Polly integration for transient-fault handling

Summary

• The src directory contains all production source code for ASP.NET Core, organized by functional component rather than by project type
• Modular architecture enables selective package references and independent component evolution
• Consistent conventions across all sub-directors facilitate both monolithic and isolated development workflows
• Dependency layering follows physical folder structure, with src/Http/ as the foundation and higher-level frameworks building upward
• Co-located documentation in README.md files keeps contextual information immediately accessible to contributors and advanced users

Frequently Asked Questions

What is the difference between src/ and other root directories in aspnetcore?

The repository root contains supporting infrastructure: eng/ for build engineering, docs/ for high-level documentation, artifacts/ for build outputs, and src/ exclusively for framework source code. Only src/ produces the NuGet packages consumed by applications. As implemented in dotnet/aspnetcore, this separation ensures build tooling remains independent from shipping code.

How do I find the implementation of a specific ASP.NET Core feature?

Navigate by functional concern: routing logic lives in src/Http/Routing/, authentication in src/Security/Authentication/, and MVC model binding in src/Mvc/Mvc.Core/ModelBinding/. Each directory contains a README.md with architectural overview, and source files follow the namespace hierarchy (e.g., Microsoft.AspNetCore.Routing maps to src/Http/Routing/src/).

Can I build individual components from src/ without compiling everything?

Yes. Each sub-directory contains standalone .slnf solution filter files or can be built directly via dotnet build on its .csproj files. The src/ structure supports component-isolated development, though full build validation requires the root build scripts to verify cross-component integration.

Where are the tests for code in src/ located?

Tests reside in test/ subdirectories within each component folder (e.g., src/Http/Http/test/ for unit tests of Microsoft.AspNetCore.Http). This co-location follows the repository-wide convention that every src/ project has a corresponding test project nearby, enabling focused test execution during component development.

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