dotnet-architecture-patterns

name	dotnet-architecture-patterns
description	Designs ASP.NET Core architecture -- vertical slices, pipelines, caching, errors.
license	MIT
targets	["*"]
category	architecture
subcategory	patterns
tags	["architecture","dotnet","skill","patterns","vertical-slices"]
version	1.0.0
author	dotnet-agent-harness
invocable	true
related_skills	["dotnet-domain-modeling","dotnet-middleware-patterns","dotnet-minimal-apis","dotnet-resilience"]
claudecode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
codexcli	{"short-description":".NET skill guidance for architecture tasks"}
opencode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
copilot	{}
geminicli	{}
antigravity	{}

dotnet-architecture-patterns

Modern architecture patterns for .NET applications. Covers practical approaches to organizing minimal APIs at scale, vertical slice architecture, request pipeline composition, validation strategies, caching, error handling, and idempotency/outbox patterns.

Scope

• Vertical slice architecture and feature-folder organization
• Request pipeline composition and MediatR patterns
• Caching strategies (memory, distributed, output caching, HybridCache)
• Error handling and problem details (RFC 9457)
• Idempotency and outbox patterns
• Result pattern for business logic error flow

Out of scope

• DI container mechanics and async/await patterns -- see [skill:dotnet-csharp-dependency-injection] and [skill:dotnet-csharp-async-patterns]
• Project scaffolding and file layout -- see [skill:dotnet-scaffold-project]
• Testing strategies -- see [skill:dotnet-testing-strategy] and [skill:dotnet-integration-testing]
• SOLID principles and design pattern foundations -- see [skill:dotnet-solid-principles]

Cross-references: [skill:dotnet-csharp-dependency-injection] for service registration and lifetimes, [skill:dotnet-csharp-async-patterns] for async pipeline patterns, [skill:dotnet-csharp-configuration] for Options pattern in configuration, [skill:dotnet-solid-principles] for SOLID/DRY design principles governing class and interface design.

---

For detailed code examples (vertical slices, minimal API organization, pipeline composition, error handling, caching, idempotency, outbox), see examples.md in this skill directory.

Agent Gotchas

1. Idempotency must handle three states -- An idempotency implementation must distinguish no-record (claim it), in-progress (reject duplicate), and completed (replay cached response). Check-then-act without guarding the in-progress state allows concurrent duplicate execution.
2. Always finalize idempotency records unconditionally -- Do NOT gate completion on specific IResult subtypes (e.g., IValueHttpResult). Non-value results like Results.NoContent() or Results.Accepted() would be left permanently stuck in the in-progress state.
3. Cache invalidation must be explicit -- When using output caching or distributed caching, ALWAYS invalidate (evict by tag or key) after write operations. Forgetting invalidation causes stale reads that are hard to debug.
4. HybridCache stampede protection only works with GetOrCreateAsync -- Do NOT use separate get-then-set patterns with ; use the factory overload so the library serializes concurrent requests for the same key.