.NET

Overview

.NET is Microsoft's open-source, cross-platform framework for building web APIs, cloud services, desktop applications, mobile apps, games, IoT, and AI/ML solutions. The modern .NET platform (6+) unifies what were formerly separate runtimes (.NET Framework, .NET Core, Mono) into a single SDK. C# is the primary language, with F# for functional programming. The ecosystem spans 400,000+ NuGet packages, first-party Azure integration, and tooling through Visual Studio, VS Code, and JetBrains Rider.

Knowledge Map

dotnet/
├── ai/                    # ML.NET, ONNX, Azure AI, Microsoft.Extensions.AI, agents (A2A, MCP)
├── cli/                   # Spectre.Console, CliWrap, command-line cheatsheet
├── cloud/                 # Aspire, Azure Functions, Dapr, Orleans, service discovery
├── configuration/         # Extensions.Configuration, caching, feature flags, OpenFeature
├── data/                  # EF Core, Dapper, Redis, Lucene.NET, FluentStorage
├── dependency-injection/  # Extensions.DI, Generic Host, Spring.NET
├── documentation/         # OpenAPI / Swagger
├── eventing/              # MediatR, MassTransit, NServiceBus, Rebus, Wolverine, Brighter, Akka.NET
├── functional/            # F#, Language.Ext, FParsec, Optional, pidgin
├── general/               # Humanizer, ImageSharp, NodaTime, Stateless, worker services, cheatsheet
├── localization/          # i18n, resource-based localization, MessageFormat
├── logging/               # Serilog, NLog, Extensions.Logging
├── mapping/               # AutoMapper, Mapperly
├── networking/            # gRPC, DotNetty, MimeKit, System.IO.Pipelines, Twilio
├── observability/         # OTLP logging, OpenTelemetry conventions
├── project-system/        # MSBuild/csproj, Roslyn analyzers, source generators, EditorConfig, Fody
├── reactive/              # Rx.NET, System.Threading.Channels, DynamicData, IAsyncEnumerable
├── resilience/            # Polly, Extensions.Resilience
├── security/              # ASP.NET Identity, cryptography, authorization (Topaz, Enforcer)
├── serialization/         # Protobuf-net, Bond, Hyperion, FluentSerializer
├── testing/               # Testcontainers, Moq, AutoFixture, Pact, Reqnroll, Playwright
├── ui/                    # MAUI, Avalonia, Blazor, Uno Platform, Blazorise, MonoGame, Unity
├── validation/            # FluentValidation, Validot, Parse Don't Validate, CommunityToolkit.Guard
└── web/                   # ASP.NET Core, SignalR, YARP, Ocelot, GraphQL, Refit, Orchard CMS

Choosing Guide

.NET Version Landscape

Choosing a Version

• Starting a new project? Use .NET 8 (LTS) for stability, or .NET 9 for latest features.
• In production with .NET 6? Plan migration to .NET 8 — .NET 6 support has ended.
• Need native AOT? .NET 8+ supports AOT for ASP.NET Core minimal APIs and gRPC.
• Using Aspire for orchestration? Requires .NET 8+.

C# Quick Reference

Modern C# Features (10-13)

// Global usings (C# 10) — reduce boilerplate across files
global using System.Text.Json;
global using Microsoft.Extensions.Logging;

// File-scoped namespaces (C# 10)
namespace MyApp.Services;

// Records with positional syntax — immutable data types
public record OrderPlaced(Guid OrderId, string CustomerId, decimal Total, DateTime PlacedAt);

// Primary constructors (C# 12) — DI without field ceremony
public class OrderService(IOrderRepository repo, ILogger<OrderService> logger)
{
    public async Task<Order> GetAsync(Guid id)
    {
        logger.LogInformation("Fetching order {OrderId}", id);
        return await repo.FindAsync(id) ?? throw new NotFoundException(id);
    }
}

// Collection expressions (C# 12)
int[] numbers = [1, 2, 3, 4, 5];
List<string> names = ["Alice", "Bob", "Charlie"];
ReadOnlySpan<byte> header = [0x48, 0x54, 0x54, 0x50];

// Pattern matching with list patterns (C# 11)
string Describe(int[] values) => values switch
{
    [] => "empty",
    [var single] => $"one item: {single}",
    [var first, .., var last] => $"from {first} to {last}",
};

// Raw string literals (C# 11) — no escaping needed
var json = """
    {
        "name": "Widget",
        "price": 29.99,
        "tags": ["electronics", "sale"]
    }
    """;

// Required members (C# 11)
public class Config
{
    public required string ConnectionString { get; init; }
    public required int MaxRetries { get; init; }
    public TimeSpan Timeout { get; init; } = TimeSpan.FromSeconds(30);
}

// Switch expressions with property patterns
decimal CalculateDiscount(Order order) => order switch
{
    { Total: > 1000, Customer.IsPremium: true } => order.Total * 0.15m,
    { Total: > 500 } => order.Total * 0.10m,
    { Customer.IsPremium: true } => order.Total * 0.05m,
    _ => 0m,
};

Key NuGet Package Categories

Best Practices

1. Use the latest LTS release (.NET 8) for production workloads. LTS releases receive 3 years of security patches and bug fixes.

2. Enable nullable reference types (<Nullable>enable</Nullable>) in every project. This catches null-reference bugs at compile time:

   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
   </PropertyGroup>

3. Use IOptions<T> pattern for configuration instead of reading values directly. This provides validation, reload support, and testability:

   public class SmtpOptions
   {
       public const string Section = "Smtp";
       public required string Host { get; init; }
       public int Port { get; init; } = 587;
       public required string FromAddress { get; init; }
   }
   
   // In Program.cs
   builder.Services.AddOptions<SmtpOptions>()
       .BindConfiguration(SmtpOptions.Section)
       .ValidateDataAnnotations()
       .ValidateOnStart();

4. Prefer records for data transfer objects and events. Records provide value equality, immutability, and concise syntax. Use record class for heap-allocated (default) and record struct for stack-allocated small types.

5. Use primary constructors for DI in services and controllers (C# 12). This eliminates boilerplate private readonly fields while keeping constructor injection.

6. Avoid async void — it swallows exceptions. Always return Task or ValueTask from async methods. The only exception is event handlers.

7. Use CancellationToken everywhere — pass it through all async call chains so requests can be cancelled cleanly when clients disconnect:

   app.MapGet("/orders/{id}", async (Guid id, IOrderRepository repo, CancellationToken ct) =>
       await repo.FindAsync(id, ct) is { } order
           ? Results.Ok(order)
           : Results.NotFound());

8. Register services with the correct lifetime — Singleton for stateless/thread-safe services, Scoped for per-request state (EF DbContext), Transient for lightweight stateless operations. Never inject Scoped into Singleton.

9. Use source generators over reflection where available (Mapperly, System.Text.Json source gen, Roslyn analyzers). Source generators run at compile time, eliminate reflection costs, and are compatible with Native AOT.

10. Structure solutions with clear project boundaries — separate API host, domain logic, infrastructure, and tests into distinct projects. Use <ProjectReference> and enforce dependency direction (domain has no external references).