@@ -1,30 +1,171 @@
+<div align="center">
+
 # Code Maze Guides
-Code Maze is a blog about simplicity and pragmatism. We tend to write clear and simple articles, easily understandable by everyone.
 
-We run a primarily C#/.NET (Core) blog, with some accent on web development and web applications. Besides trying to implement best practices and use the newest technologies available, we are focusing on the entire lifecycle of .NET (Core) applications.
+**The source code for 800+ C# and .NET articles from [code-maze.com](https://code-maze.com/?source=github).**<br>Every article gets its own runnable solution, most with tests.
+
+[![Stars](https://img.shields.io/github/stars/CodeMazeBlog/CodeMazeGuides?style=flat&logo=github)](https://github.com/CodeMazeBlog/CodeMazeGuides/stargazers) [![Forks](https://img.shields.io/github/forks/CodeMazeBlog/CodeMazeGuides?style=flat&logo=github)](https://github.com/CodeMazeBlog/CodeMazeGuides/network/members) [![PR Build](https://github.com/CodeMazeBlog/CodeMazeGuides/actions/workflows/pr-build.yml/badge.svg)](https://github.com/CodeMazeBlog/CodeMazeGuides/actions/workflows/pr-build.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![.NET](https://img.shields.io/badge/.NET-512BD4?logo=dotnet&logoColor=white)](https://dotnet.microsoft.com/)
+
+[Blog](https://code-maze.com/?source=github) · [Courses](https://courses.code-maze.com/courses/?source=github) · [YouTube](https://www.youtube.com/@CodeMaze) · [Report an issue](https://github.com/CodeMazeBlog/CodeMazeGuides/issues)
+
+</div>
+
+---
+
+## Contents
+
+- [About](#about)
+- [Quick start](#quick-start)
+- [Browse by topic](#browse-by-topic)
+- [Repository layout](#repository-layout)
+- [Contributing](#contributing)
+- [Support Code Maze](#support-code-maze)
+- [License](#license)
+
+## About
+
+Code Maze is a blog about C# and .NET, written with simplicity and pragmatism in mind. The articles are hands-on. They focus on the core of each topic and show working code, not theory alone.
+
+This repository holds that code. If you came here from an article, the article links to its exact folder. If you are just browsing, pick a topic below.
+
+## Quick start
+
+You need the [.NET SDK](https://dotnet.microsoft.com/download). Each project states its target framework in its `.csproj` file, so install the version that project asks for.
+
+```bash
+git clone https://github.com/CodeMazeBlog/CodeMazeGuides.git
+cd CodeMazeGuides/<topic>/<article-folder>
+dotnet build
+dotnet run
+dotnet test
+```
+
+> [!TIP]
+> The full repository is large. To get only one article, use a sparse checkout:
+>
+> ```bash
+> git clone --filter=blob:none --sparse https://github.com/CodeMazeBlog/CodeMazeGuides.git
+> cd CodeMazeGuides
+> git sparse-checkout set <topic>/<article-folder>
+> ```
+
+## Browse by topic
+
+The numbers show how many article projects each folder holds.
+
+### C# language
+
+| Topic | Projects |
+| --- | ---: |
+| [C# basics](csharp-basic-topics) | 45 |
+| [C# intermediate](csharp-intermediate-topics) | 48 |
+| [C# advanced](csharp-advanced-topics) | 28 |
+| [Classes, structs and records](csharp-classes-struct-record) | 11 |
+| [Methods](csharp-methods) | 9 |
+| [Operators](csharp-operators) | 5 |
+| [Strings](strings-csharp) | 39 |
+| [Numbers](numbers-csharp) | 19 |
+| [LINQ](csharp-linq) | 20 |
+| [Async programming](async-csharp) | 11 |
+| [Threads](threads-csharp) | 7 |
+| [Exception handling](exception-handling) | 10 |
+| [Refactoring](csharp-refactoring) | 5 |
+
+### Collections
+
+| Topic | Projects |
+| --- | ---: |
+| [Collections](collections-csharp) | 24 |
+| [Arrays](collections-arrays) | 24 |
+| [Lists](collections-lists) | 16 |
+| [Dictionaries](collections-dictionary) | 9 |
+
+### ASP.NET Core and Blazor
+
+| Topic | Projects |
+| --- | ---: |
+| [ASP.NET Core Web API](aspnetcore-webapi) | 56 |
+| [ASP.NET Core features](aspnetcore-features) | 52 |
+| [Authentication and authorization](authorization-dotnet) | 23 |
+| [Query strings](dotnet-querystrings) | 6 |
+| [Blazor features](blazor-features) | 11 |
+| [Blazor libraries](blazor-libraries) | 2 |
+| [Angular](angular) | 1 |
+
+### Data and serialization
+
+| Topic | Projects |
+| --- | ---: |
+| [Entity Framework Core](dotnet-efcore) | 28 |
+| [Dapper](dotnet-dapper) | 4 |
+| [MongoDB](dotnet-mongo-db) | 3 |
+| [JSON](json-csharp) | 29 |
+| [XML](xml-csharp) | 6 |
+| [Files and streams](files-csharp) | 23 |
+| [Date and time](dotnet-datetime) | 22 |
+| [Searching](dotnet-searching) | 1 |
+
+### Architecture and design
+
+| Topic | Projects |
+| --- | ---: |
+| [Design patterns](csharp-design-patterns) | 12 |
+| [Architectural patterns](csharp-architectural-patterns) | 13 |
+| [Domain-driven design](domain-driven%20design) | 1 |
+| [Dependency injection](dotnet-dependency-injection) | 11 |
+| [DI tools](dependency-injection-tools) | 3 |
+| [Microservices](dotnet-microservices) | 2 |
+
+### Libraries, tooling and operations
+
+| Topic | Projects |
+| --- | ---: |
+| [Client libraries](dotnet-client-libraries) | 60 |
+| [Base libraries](dotnet-base-libraries) | 3 |
+| [Testing](dotnet-testing) | 32 |
+| [Logging](dotnet-logging) | 13 |
+| [Performance](dotnet-performance) | 9 |
+| [.NET CLI](dotnet-cli) | 2 |
+| [Visual Studio](visual-studio) | 5 |
+| [Deployment](dotnet-deployment) | 2 |
+| [Platform-specific code](dotnet-platform-specific) | 3 |
+| [Projects](dotnet-projects) | 13 |
+
+### Algorithms, AI and more
+
+| Topic | Projects |
+| --- | ---: |
+| [Algorithms](csharp-algorithms) | 13 |
+| [Machine learning](csharp-machine-learning) | 5 |
+| [AI](csharp-ai) | 1 |
+| [Images](csharp-images) | 3 |
+
+## Repository layout
+
+```text
+CodeMazeGuides/
+├── <topic>/                  # one folder per topic, e.g. aspnetcore-webapi
+│   └── <article-folder>/     # one folder per article
+│       ├── <Project>.sln     # its own solution
+│       ├── <Project>/        # the example code
+│       └── Tests/            # tests, in most articles
+└── .github/workflows/        # PR build: builds and tests changed projects
+```
 
-We think that the combination of a hands-on approach and focusing on the essence of the topic in our articles is what makes our blog unique. Hopefully, this approach will be something that helps you learn quicker and achieve the best results possible.
+Each article is self-contained. You never need to build the whole repository.
 
-This repository contains most of the code from our blog.
+## Contributing
 
-The Materials
-==============================
-If you like what you've learned and would like to support us, you can check some of our materials:
+Found a bug in an example, or does a project not build on a newer .NET version? [Open an issue](https://github.com/CodeMazeBlog/CodeMazeGuides/issues) or send a pull request. The PR build checks every changed project automatically.
 
-Here's the "Ultimate ASP.NET Core WEB API - Second Edition": <br/>
-**[ULTIMATE ASP.NET CORE WEB API](https://code-maze.com/ultimate-aspnetcore-webapi-second-edition/?source=github)**
+## Support Code Maze
 
-Here's the "Blazor WebAssembly (.NET 7)" Video Course: <br/>
-**[BLAZOR WEBASSEMBLY VIDEO COURSE](https://code-maze.com/blazor-webassembly-course/?source=github)**
+The blog is free. Our courses keep it that way. If the articles helped you, have a look:
 
-| Ultimate Web API  | Blazor WebAssembly |
-| - | - |
-| [<img src="https://code-maze.com/wp-content/uploads/2022/08/ultimate-aspnet-core-banner-v3-690-min.webp"  width="500">](https://code-maze.com/ultimate-aspnetcore-webapi-second-edition/?source=github) | [<img src="https://code-maze.com/wp-content/uploads/2021/04/banner-blog-final-min.png"  width="500">](https://code-maze.com/blazor-webassembly-course/?source=github) |
+<a href="https://courses.code-maze.com/courses/?source=github"><strong>Browse all Code Maze courses →</strong></a>
 
-We appreciate your support. It helps us provide even more free materials on the blog.
+A ⭐ on this repository also helps other developers find it.
 
-Running the Examples
-================
-Each article is separated into its own folder on the repository and has its own solution. Whether you came from the article or just browsing the repository, each solution can be built separately with `dotnet build` or run with `dotnet run`.
+## License
 
-On top of that, most of the solutions contain additional tests you can browse and run with `dotnet test`. Tests usually serve to verify the solution, but you can often find some useful ideas and additional examples.
+[MIT](LICENSE). Use the code freely in your own projects.
@@ -1,16 +1,14 @@
 <Project Sdk="Microsoft.NET.Sdk.Web">
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
-    <Nullable>disable</Nullable>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
     <UserSecretsId>d0d8591a-b364-4f96-921f-d24a0e638079</UserSecretsId>
-    <DockerDefaultTargetOS>Linux</DockerDefaultTargetOS>
-    <DockerfileContext>.</DockerfileContext>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" Version="1.19.6" />
+    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="10.10.0" />
   </ItemGroup>
 
 	<ItemGroup>
 
@@ -1,14 +1,5 @@
-using Microsoft.AspNetCore.Builder;
-using Microsoft.AspNetCore.Mvc;
-using System.Net.Http;
-using System.Threading;
-
 var builder = WebApplication.CreateBuilder(args);
 
-// Add services to the container.
-
-builder.Services.AddControllers();
-
 builder.Services.AddHttpClient("TestClient", (sp, httpClient) =>
 {
     var configuration = sp.GetRequiredService<IConfiguration>();
@@ -18,15 +9,17 @@
     httpClient.Timeout = TimeSpan.FromSeconds(timeoutSeconds);
 });
 
-var app = builder.Build();
-
-// Configure the HTTP request pipeline.
-
-app.UseHttpsRedirection();
-
-app.UseAuthorization();
+builder.Services.AddHttpClient("ResilientClient", httpClient =>
+{
+    httpClient.BaseAddress = new Uri("http://localhost:5000");
+})
+.AddStandardResilienceHandler(options =>
+{
+    options.AttemptTimeout.Timeout = TimeSpan.FromSeconds(2);
+    options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(8);
+});
 
-app.MapControllers();
+var app = builder.Build();
 
 app.MapGet("/api/delay-4-seconds", async (CancellationToken cancellationToken) => await Task.Delay(TimeSpan.FromSeconds(4), cancellationToken));
 
@@ -36,7 +29,7 @@
 
     try
     {
-        var response = await httpClient.GetAsync("/api/delay-4-seconds");
+        using var response = await httpClient.GetAsync("/api/delay-4-seconds");
 
         return Results.Ok();
     }
@@ -53,7 +46,7 @@
 
     try
     {
-        var response = await httpClient.GetAsync($"/api/delay-4-seconds", cancellationToken);
+        using var response = await httpClient.GetAsync($"/api/delay-4-seconds", cancellationToken);
 
         return Results.Ok();
     }
@@ -71,7 +64,7 @@
 
     try
     {
-        var response = await httpClient.GetAsync("/api/delay-4-seconds", tokenSource.Token);
+        using var response = await httpClient.GetAsync("/api/delay-4-seconds", tokenSource.Token);
 
         return Results.Ok();
     }
@@ -83,4 +76,40 @@
     }
 });
 
+app.MapGet("/api/test-timeout-vs-cancellation", async (IHttpClientFactory httpClientFactory, CancellationToken cancellationToken) =>
+{
+    var httpClient = httpClientFactory.CreateClient("TestClient");
+
+    try
+    {
+        using var response = await httpClient.GetAsync("/api/delay-4-seconds", cancellationToken);
+
+        return Results.Ok();
+    }
+    catch (OperationCanceledException ex) when (ex.InnerException is TimeoutException)
+    {
+        return Results.Text("The request timed out");
+    }
+    catch (OperationCanceledException)
+    {
+        return Results.Text("The caller canceled the request");
+    }
+});
+
+app.MapGet("/api/test-resilience-timeout", async (IHttpClientFactory httpClientFactory) =>
+{
+    var httpClient = httpClientFactory.CreateClient("ResilientClient");
+
+    try
+    {
+        using var response = await httpClient.GetAsync("/api/delay-4-seconds");
+
+        return Results.Ok();
+    }
+    catch (Exception ex)
+    {
+        return Results.Text($"{ex.GetType().Name} after {httpClient.Timeout}");
+    }
+});
+
 app.Run();
@@ -55,4 +55,30 @@ public async Task GivenCustomTokenIsCombinedWithGlobalAndRequestToken_WhenTheReq
         // Assert
         await Assert.ThrowsAsync<TaskCanceledException>(() => client.GetAsync("/api/test-combined-timeout", cts.Token));
     }
+
+    [Fact]
+    public async Task WhenTheTimeoutElapses_ThenTheOperationCanceledExceptionNestsATimeoutException()
+    {
+        // Arrange
+        var client = _factory.CreateClient();
+
+        // Act
+        var responseMessage = await client.GetStringAsync("/api/test-timeout-vs-cancellation");
+
+        // Assert
+        Assert.Equal("The request timed out", responseMessage);
+    }
+
+    [Fact]
+    public async Task WhenTheResilienceHandlerTimesOut_ThenItThrowsTimeoutRejectedExceptionAndDisablesHttpClientTimeout()
+    {
+        // Arrange
+        var client = _factory.CreateClient();
+
+        // Act
+        var responseMessage = await client.GetStringAsync("/api/test-resilience-timeout");
+
+        // Assert
+        Assert.Equal("TimeoutRejectedException after -00:00:00.0010000", responseMessage);
+    }
 }
@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFramework>net10.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
 
@@ -10,11 +10,11 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="coverlet.collector" Version="6.0.0" />
-    <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="8.0.4" />
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
-    <PackageReference Include="xunit" Version="2.5.3" />
-    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.3" />
+    <PackageReference Include="coverlet.collector" Version="10.0.1" />
+    <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.12" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.10.1" />
+    <PackageReference Include="xunit" Version="2.9.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="4.0.0" />
   </ItemGroup>
 
   <ItemGroup>