What Is the Purpose of the `samples` Directory in ASP.NET Core?

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 explicitly references this purpose: "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 <ProjectReference> 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:

cd src/SignalR/samples/ClientSample
dotnet run

Test HTTP/3 features with Kestrel:

cd src/Servers/Kestrel/samples/Http3SampleApp
dotnet run

Launch the JWT‑Bearer authentication demo:

cd src/Security/Authentication/JwtBearer/samples/JwtBearerSample
dotnet run

These commands compile and start the minimal web apps, allowing you to inspect Program.cs, review 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 <ProjectReference> 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.

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