If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dodyg/practical-aspnetcore shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 3w ago
• 3 active contributors
• MIT licensed
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 96% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dodyg/practical-aspnetcore repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dodyg/practical-aspnetcore.

What it runs against: a local clone of dodyg/practical-aspnetcore — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dodyg/practical-aspnetcore | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch net10.0 exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 52 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dodyg/practical-aspnetcore. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dodyg/practical-aspnetcore.git
#   cd practical-aspnetcore
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dodyg/practical-aspnetcore and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dodyg/practical-aspnetcore(\\.git)?\\b" \\
  && ok "origin remote is dodyg/practical-aspnetcore" \\
  || miss "origin remote is not dodyg/practical-aspnetcore (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify net10.0 >/dev/null 2>&1 \\
  && ok "default branch net10.0 exists" \\
  || miss "default branch net10.0 no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "STRUCTURE.md" \\
  && ok "STRUCTURE.md" \\
  || miss "missing critical file: STRUCTURE.md"
test -f "global.json" \\
  && ok "global.json" \\
  || miss "missing critical file: global.json"
test -f "projects/authentication/readme.md" \\
  && ok "projects/authentication/readme.md" \\
  || miss "missing critical file: projects/authentication/readme.md"
test -f "projects/blazor-ss/ChatR/Program.cs" \\
  && ok "projects/blazor-ss/ChatR/Program.cs" \\
  || miss "missing critical file: projects/blazor-ss/ChatR/Program.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 52 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~22d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dodyg/practical-aspnetcore"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A comprehensive collection of runnable ASP.NET Core samples across versions 2.1 through 10, organized by feature area (authentication, Blazor, caching, dependency injection, etc.). It solves the problem of learning ASP.NET Core patterns through concrete, working code examples rather than documentation alone—each project in /projects/* is a self-contained, buildable demonstration of a specific capability. Monorepo structure: /projects/* contains 40+ feature-scoped folders (authentication, blazor-wasm, caching, etc.), each with independent .csproj files and Program.cs entries. /exercises/pathway-1/ holds 9 numbered learning modules with markdown instructions. Top-level /STRUCTURE.md documents the layout; migration and deprecation guidance in MIGRATION-PLAN.md and OUT-OF-DATE.md.

C# developers and teams adopting or migrating between ASP.NET Core versions who need practical, tested examples before building production features. Specifically: learners working through /exercises/pathway-1, maintainers upgrading codebases, and framework contributors validating new features in /projects/net10 and /projects/net9.

Actively maintained and production-grade: the repo tracks ASP.NET Core release cycles (now at .NET 10), includes structured exercises, and maintains backward compatibility branches (net6.0, net5.0, 3.1-LTS available). Single author (dodyg) with sponsorship model suggests stable long-term commitment. Build logs present (build-log.txt, build-log-after-prune.txt) indicate CI awareness.

Single-maintainer risk is the primary concern—dodyg is the sole contributor shown. No CI/CD pipeline visible in file list (no .github/workflows), so automated testing/building is unclear. Out-of-date tracking (OUT-OF-DATE.md) suggests some samples may lag behind .NET releases. Dependency on multiple .NET SDK versions (2.1–10) means environment setup complexity and potential version conflicts during local testing.

Active focus on ASP.NET Core 10 samples (/projects/net10 with 12 examples) and Datastar integration (/projects/datastar with 20 examples). Blazor SSR (/projects/blazor-ssr) expanded to 22 samples. Hydro Framework (Razor Pages compatible) receiving updates. Migration guidance being refined (MIGRATION-PLAN.md present), suggesting ongoing effort to keep samples current with .NET release cycles.

Clone: git clone https://github.com/dodyg/practical-aspnetcore.git && cd practical-aspnetcore. Check /global.json for required .NET SDK version. Pick a project folder (e.g., cd projects/authentication/authentication-1) and run dotnet run directly (no npm, no additional install step needed for most samples).

Daily commands: From a project subdirectory (e.g., projects/authentication/authentication-1): dotnet run. Most samples listen on http://localhost:5000 or https://localhost:5001 by default. For Blazor WASM projects, dotnet run starts dev server with hot reload. Check individual project README.md files (e.g., /projects/authentication/authentication-1/Readme.md) for port overrides.

• README.md — Master index listing all samples across ASP.NET Core versions 10, 9, 8, 7, 6, 5, 3.1, 2.2, 2.1 with navigation to feature-specific projects.
• STRUCTURE.md — Documents the organizational layout of the entire repository—essential for understanding how projects are categorized and named.
• global.json — Defines the target .NET version and build settings applied across all projects in the monorepo.
• projects/authentication/readme.md — Central overview of all authentication sample projects (1–5) showing progression from basic to Identity framework usage.
• projects/blazor-ss/ChatR/Program.cs — Entry point for Blazor Server example demonstrating service registration, middleware configuration, and SignalR integration.
• .vscode/launch.json — Debugging configuration for running and attaching to ASP.NET Core projects in VS Code—required for local development.
• MIGRATION-PLAN.md — Documents upgrade path and breaking changes between ASP.NET Core versions, crucial for understanding version-specific samples.

Add a new Authentication Sample Project

1. Create new folder under projects/authentication/ following naming convention (e.g., authentication-6) (projects/authentication/)
2. Create .csproj file referencing ASP.NET Core packages, following pattern in authentication-5.csproj (projects/authentication/authentication-6/authentication-6.csproj)
3. Create Program.cs with service registration and middleware pipeline following authentication-5/Program.cs template (projects/authentication/authentication-6/Program.cs)
4. Add Readme.md documenting the authentication approach and running instructions (projects/authentication/authentication-6/Readme.md)
5. Update projects/authentication/readme.md to list new sample with brief description (projects/authentication/readme.md)

Add a new Blazor Component with State Management

1. Create new folder under projects/blazor-ss/ with project name (e.g., NewFeature) (projects/blazor-ss/NewFeature/)
2. Create .csproj with Blazor Web App SDK and required packages (projects/blazor-ss/NewFeature/NewFeature.csproj)
3. Create AppState.cs service for state management, following ComponentEvents-2/AppState.cs pattern (projects/blazor-ss/NewFeature/AppState.cs)
4. Create .razor component in Components/Pages/, following Index.razor template with @inject AppState (projects/blazor-ss/NewFeature/Components/Pages/Feature.razor)
5. Register AppState service in Program.cs using builder.Services.AddScoped<AppState>() (projects/blazor-ss/NewFeature/Program.cs)

Add a new EF Core-backed Feature Module

1. Create new folder under projects/authentication/ or similar with domain name (projects/authentication/feature-name/)
2. Create Data/FeatureDbContext.cs extending DbContext, referencing authentication-5/Data/ApplicationDBContext.cs (projects/authentication/feature-name/Data/FeatureDbContext.cs)
3. Create Entities/ folder with domain entity classes (e.g., Entities/Item.cs) (projects/authentication/feature-name/Entities/Item.cs)
4. Run 'dotnet ef migrations add InitialCreate' to generate Migration files in Migrations/ (projects/authentication/feature-name/Migrations/)
5. Register DbContext in Program.cs and configure appsettings.json with connection string (projects/authentication/feature-name/Program.cs)

• ASP.NET Core (versions 10.0 down to 2.1) — Multi-version sample repository demonstrating evolution and backward compatibility across major framework releases
• Entity Framework Core — Primary ORM for data access samples, especially in authentication and identity scenarios requiring database integration
• Blazor Server & Blazor SSR — Interactive UI samples showing server-side rendering and real-time component state management with SignalR
• ASP.NET Core Identity — Built-in authentication and authorization framework used across authentication-5 and higher samples
• SignalR — Real-time bidirectional communication for Blazor and chat application examples

• Single large monorepo with 600+ files across multiple feature categories

  • Why: Simplifies discovery and cross-referencing of related samples; enables single clone for all ASP.NET Core versions and features
  • Consequence: Repository is large; contributors must carefully organize new samples in appropriate subdirectories to avoid structure decay

• Support 8+ ASP.NET Core versions (10.0, 9, 8, 7, 6, 5, 3.1, 2.2, 2.1) on separate branches

  • Why: Preserves historical samples and allows learners to study version-specific features and migration paths
  • Consequence: High maintenance burden; breaking changes must be propagated across multiple branches; requires clear MIGRATION-PLAN.md documentation

• No unit test files included in core samples

  • Why: Keeps sample code focused on feature demonstration rather than testing patterns
  • Consequence: Learners must infer best practices for testing; encourages external references to testing frameworks

• Readme-first documentation approach with inline comments in samples

  • Why: Makes samples self-documenting and approachable for beginners
  • Consequence: Code can become verbose with explanatory comments; complex patterns may lack depth

• Production-ready applications: samples are intentionally minimal for educational clarity
• Performance optimization: samples prioritize readability over throughput or latency benchmarks
• Comprehensive testing coverage: unit, integration, and end-to-end tests are left as exercises for learners
• Windows-only tooling: repository explicitly supports .NET Core cross-platform (Linux, macOS) via .sh build scripts
• Advanced distributed systems: samples do not cover microservices, Kubernetes, or distributed tracing
• Real-time machine learning integration: AGENTS.md references AI samples but they are separate from core ASP.NET samples

1. Multiple .NET SDK versions required: /global.json pins a version, but projects/net5.0, projects/net6.0 etc. may need different SDKs installed alongside. 2) Port conflicts: many samples default to 5000/5001; running multiple samples simultaneously requires port reassignment. 3) Authentication samples (projects/authentication/) often use in-memory credential stores; not production-safe without swapping to real identity providers. 4) Blazor WASM samples compile C# to WebAssembly—first build is slow (~1–2 min) due to IL trimming. 5) No Docker Compose setup visible despite Dockerfile presence; Docker samples must be built individually.

• Minimal APIs — Modern ASP.NET Core samples use Program.cs-centric endpoint definition instead of Controllers; understanding this paradigm shift is essential for reading current /projects/* examples
• Dependency Injection Container — ASP.NET Core's built-in DI (Microsoft.Extensions.DependencyInjection) is central to all samples; /projects/dependency-injection/ explores its patterns and lifetimes
• Blazor Component Lifecycle — Blazor samples (WASM, Server, SSR) heavily depend on understanding OnInitializedAsync, OnParametersSet, and rendering batching; critical for the 60 Blazor-focused projects in /projects/
• Middleware Pipeline — ASP.NET Core request handling is middleware-centric; authentication, caching, and diagnostics samples all rely on correct middleware ordering in Program.cs
• Configuration Providers — The /projects/configurations/ folder demonstrates IConfiguration and appsettings.json binding; understanding provider layering (JSON, environment, secrets) is foundational
• Claims-Based Authorization — Authentication samples (/projects/authentication/) use ClaimsPrincipal and policy-based authorization; essential for securing real applications beyond cookie/token auth
• Server-Sent Events (SSE) — Real-time communication in ASP.NET Core Blazor Server and Datastar samples; understanding response streaming and IAsyncEnumerable is needed for these projects

• dotnet/samples — Official .NET team samples repository; covers framework fundamentals and sometimes overlaps with dodyg's repo on baseline features
• dotnet/aspire-samples — Companion repo for .NET Aspire (cloud-native orchestration); relevant for developers building microservices atop the ASP.NET Core patterns shown here
• Grauenwolf/DotNet-ORM-Cookbook — Data access companion cookbook; dodyg's repo links to it for EF Core and ORM patterns, filling the gap in database layer samples
• dodyg/bluenile — Author's ATProtocol/Bluesky samples; sibling project for developers combining ASP.NET Core backends with decentralized social protocol clients
• ardalis/CleanArchitecture — Industry-standard clean architecture template for .NET; complements practical-aspnetcore by showing how to structure larger, production-grade projects from the building blocks demonstrated here

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Create comprehensive HTTP request files for all authentication samples

Currently only authentication-5 has a Requests/Authentication.http file for testing endpoints. All other authentication projects (authentication-1 through authentication-4) lack .http files for easy testing in VS Code REST Client. This would significantly improve the developer experience for contributors testing these samples without requiring external tools.

• [ ] Create projects/authentication/authentication-1/Requests/Authentication.http with endpoints for authentication-1 sample
• [ ] Create projects/authentication/authentication-2/Requests/Authentication.http with endpoints for authentication-2 sample
• [ ] Create projects/authentication/authentication-3/Requests/Authentication.http with endpoints for authentication-3 sample
• [ ] Create projects/authentication/authentication-4/Requests/Authentication.http with endpoints for authentication-4 sample
• [ ] Update each authentication project's Readme.md to reference the .http file for testing instructions

Add build verification workflow for projects/authentication samples

The repo has build-log.txt and build-log-after-prune.txt files indicating manual build testing occurs, but no GitHub Actions workflow exists to automatically verify all authentication projects compile and run correctly on pull requests. This would catch breaking changes early across multiple ASP.NET Core versions.

• [ ] Create .github/workflows/authentication-build.yml that builds and tests all projects in projects/authentication/ on push and PR
• [ ] Include matrix strategy for different .NET SDK versions used in authentication projects
• [ ] Add step to verify all authentication-*.csproj files compile without warnings
• [ ] Document in CONTRIBUTING.md that authentication samples must pass this workflow before PR merge

Create missing README.md files for authentication sub-projects and document their progression

While authentication-1 through authentication-5 have individual Readme.md files, there's no parent README.md in projects/authentication/ that explains the progression, differences, and learning path through these samples. This would help new contributors and learners understand the purpose of each authentication project and when to use which approach.

• [ ] Create projects/authentication/README.md with overview of all 5 authentication samples
• [ ] Document the progression: from basic setup (auth-1) to database integration (auth-5)
• [ ] Create a table showing which ASP.NET Core versions each authentication sample targets
• [ ] Add links to external resources (Microsoft Identity docs, OAuth 2.0 specs) relevant to each sample
• [ ] Include prerequisites and setup instructions for running the authentication samples locally

• Add automated CI/CD pipeline (.github/workflows/*.yml) to build and test all projects on PR; currently no visible GitHub Actions workflow despite .github/ folder existing
• Expand test coverage for /projects/authentication/* samples: add xUnit or NUnit projects in each authentication-N folder validating claim extraction and policy enforcement
• Document environment setup for mixed .NET version development: create a SETUP.md guide with sdkman or .NET version manager commands for developers juggling 2.1–10 locally

• Medium · Potential Hardcoded Credentials in appsettings Files — projects/authentication/authentication-4/appsettings.json, projects/authentication/authentication-4/appsettings.Development.json, projects/authentication/authentication-5/appsettings.json, projects/authentication/authentication-5/appsettings.Development.json. The codebase contains appsettings.json and appsettings.Development.json files in multiple projects (e.g., authentication-4, authentication-5). These configuration files may contain sensitive information like database connection strings, API keys, or credentials that could be committed to version control. Fix: Store sensitive configuration in environment variables or secure secret management systems (e.g., Azure Key Vault, AWS Secrets Manager). Never commit appsettings files with secrets. Use appsettings.Development.json only locally and add it to .gitignore.
• Medium · Missing Security Headers Configuration — projects/authentication/authentication-*/Program.cs, projects/blazor-ss/ChatR/Program.cs, projects/application-environment/Program.cs. No evidence of security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.) configuration in the Program.cs files or middleware setup visible in the file structure. This leaves the application vulnerable to common web attacks like clickjacking and XSS. Fix: Implement security headers middleware. Add middleware to set security headers: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, X-XSS-Protection, Strict-Transport-Security.
• Medium · Potential SQL Injection Risk in Entity Framework — projects/authentication/authentication-5/Data/ApplicationDBContext.cs, projects/authentication/authentication-5/Migrations/. The presence of ApplicationDBContext.cs suggests Entity Framework usage. Without visibility into query implementation, there's potential risk if raw SQL queries are used without parameterization, particularly in the migration files and data access patterns. Fix: Use Entity Framework's LINQ queries exclusively. If raw SQL is necessary, always use parameterized queries with EF Core's FromSqlInterpolated() or parametrized methods. Never concatenate user input into SQL queries.
• Medium · Authentication and Authorization Not Verified — projects/authentication/authentication-*/Program.cs. While authentication projects exist, without reviewing the actual implementation in Program.cs files, it's unclear if proper authentication schemes (JWT, OAuth2, etc.) and authorization policies are correctly implemented. Missing or weak authentication configuration could allow unauthorized access. Fix: Ensure proper authentication middleware is configured (AddAuthentication, AddAuthorization). Implement strong default policies. Use JWT with proper signing and validation. Apply [Authorize] attributes to sensitive endpoints.
• Low · Blazor Server-Side Rendering Security Considerations — projects/blazor-ss/ChatR/Components/Pages/Index.razor, projects/blazor-ss/ChatR/NotificationHub.cs. The Blazor Server-Side (blazor-ss) project with ChatR and NotificationHub components may be vulnerable to XSS attacks if user input is rendered without proper encoding, particularly in real-time communication scenarios. Fix: Ensure all user input in Razor components is properly HTML-encoded. Use Blazor's built-in encoding. Validate and sanitize all SignalR hub messages. Implement message rate limiting in NotificationHub to prevent abuse.
• Low · Missing CSRF Protection Configuration — projects/authentication/authentication-4/Controllers/WeatherForecastController.cs. No explicit evidence of CSRF token validation setup in the visible configuration files. ASP.NET Core should have built-in CSRF protection, but it needs proper configuration, especially for form submissions and API endpoints. Fix: Ensure [ValidateAntiForgeryToken] is applied to POST/PUT/DELETE endpoints. Use @Html.AntiForgeryToken() in Razor views. Configure CORS policies with proper origin restrictions.
• Low · Dependency Vulnerabilities Not Verified — projects/*/**.csproj. No NuGet package lock files or dependency manifests were provided for analysis. Without seeing .csproj files content or package.lock.json equivalents, potential outdated or vulnerable NuGet packages cannot be verified. Fix: Regularly audit NuGet dependencies using 'dotnet list package

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.