# What Is the Purpose of the `samples` Directory in ASP.NET Core? > Discover the purpose of the samples directory in the dotnet/aspnetcore repository. Learn how these examples aid in understanding framework features, integration testing, and reference implementation. - Repository: [.NET Platform/aspnetcore](https://github.com/dotnet/aspnetcore) - Tags: internals - Published: 2026-08-01 --- **The `samples` directory in the `dotnet/aspnetcore` repository contains self‑contained example applications that demonstrate how to use framework features for learning, integration testing, and reference implementation.** The `dotnet/aspnetcore` repository organizes its codebase into modular components, each containing a dedicated `samples` folder. These directories house runnable projects that illustrate proper API usage and configuration patterns. Understanding the purpose of the `samples` directory in ASP.NET Core helps developers quickly grasp implementation details through working code rather than documentation alone. ## Core Functions of the `samples` Directory ### Learning and Documentation Each sample serves as a practical tutorial that complements written documentation. The [`src/Servers/HttpSys/README.md`](https://github.com/dotnet/aspnetcore/blob/main/src/Servers/HttpSys/README.md) explicitly references this purpose: "[samples/](samples/): Contains samples showing how to use HTTP.sys." Similar references exist across SignalR, Kestrel, Security, and other components, providing developers with ready‑to‑run code that shows the correct way to configure and call ASP.NET Core APIs. ### Integration Testing Support Many integration tests reference sample projects via `` entries in solution files. These samples act as verification targets, ensuring that framework changes do not break real‑world usage patterns. By testing against actual sample applications rather than mock objects, the ASP.NET Core team validates end‑to‑end functionality. ### Reference Implementations Microsoft engineers and community contributors use these samples as canonical examples when building new features or diagnosing bugs. Located alongside the source code they demonstrate, these projects represent the authoritative "golden path" for implementing specific functionality such as HTTP/3 support or JWT‑Bearer authentication. ## Key Sample Locations and Projects Each major component maintains its own `samples` sub‑directory containing minimal, buildable projects: - **SignalR**: `src/SignalR/samples/ClientSample` contains `ClientSample.csproj`, demonstrating real‑time client connections. - **Kestrel**: `src/Servers/Kestrel/samples/Http3SampleApp` includes `Http3SampleApp.csproj` for HTTP/3 protocol scenarios. - **HTTP.sys**: `src/Servers/HttpSys/samples/HotAddSample` features `HotAddSample.csproj` showing server hot‑add capabilities. - **Authentication**: `src/Security/Authentication/JwtBearer/samples/JwtBearerSample` houses `JwtBearerSample.csproj` for token‑based security implementation. - **Identity**: `src/Identity/samples/IdentitySample.Mvc` contains `IdentitySample.Mvc.csproj`, illustrating user management patterns. - **WebSockets**: `src/Middleware/WebSockets/samples/EchoApp` includes `EchoApp.csproj` for WebSocket middleware usage. ## Running ASP.NET Core Samples Executing a sample requires only the .NET SDK. Navigate to the project folder and invoke `dotnet run` to launch the application. Run the SignalR client example: ```bash cd src/SignalR/samples/ClientSample dotnet run ``` Test HTTP/3 features with Kestrel: ```bash cd src/Servers/Kestrel/samples/Http3SampleApp dotnet run ``` Launch the JWT‑Bearer authentication demo: ```bash cd src/Security/Authentication/JwtBearer/samples/JwtBearerSample dotnet run ``` These commands compile and start the minimal web apps, allowing you to inspect [`Program.cs`](https://github.com/dotnet/aspnetcore/blob/main/Program.cs), review [`appsettings.json`](https://github.com/dotnet/aspnetcore/blob/main/appsettings.json) configurations, and test endpoints with a browser or command‑line client. ## Summary - The `samples` directory contains **self‑contained example applications** for each ASP.NET Core component according to the repository structure. - Samples serve three primary roles: **learning resources**, **integration test targets**, and **reference implementations** for the community and Microsoft engineers. - Each major component (SignalR, Kestrel, Security, Identity) maintains dedicated sample projects with runnable `.csproj` files. - Execute any sample using `dotnet run` after navigating to the specific project folder. ## Frequently Asked Questions ### What is the purpose of the samples folder in ASP.NET Core? The samples folder provides runnable example applications that demonstrate correct usage of framework APIs. According to the source code in `dotnet/aspnetcore`, these projects serve as living documentation, integration test references, and canonical implementations for developers learning the platform. ### How do I run a sample from the ASP.NET Core repository? Navigate to the specific sample directory—such as `src/SignalR/samples/ClientSample`—and execute `dotnet run` from the command line. This builds and launches the application, allowing you to interact with the feature implementation and inspect the startup configuration directly. ### Are ASP.NET Core samples used for automated testing? Yes. Many integration tests in the ASP.NET Core codebase reference sample projects through `` entries to verify real‑world behavior. These samples must compile and run correctly, serving as regression tests that ensure framework updates do not break existing usage patterns. ### Where are the authentication samples located in ASP.NET Core? Authentication samples reside in `src/Security/Authentication/[Scheme]/samples/` directories. For example, the JWT‑Bearer sample is located at `src/Security/Authentication/JwtBearer/samples/JwtBearerSample/JwtBearerSample.csproj`, while other schemes like Cookies or OAuth follow the same organizational pattern.