Guidelines for organizing .NET projects, including solution structure, project references, folder conventions, .slnx format, centralized build properties, and central package management. Use when setting up a new .NET solution with modern best practices, configuring centralized build properties acro

.NET Project Structure and Build Configuration When to Use This Skill Use this skill when: Setting up a new .NET solution with modern best practices Configuring centralized build properties across multiple projects Implementing central package version management Setting up SourceLink for debugging and NuGet packages Automating version management with release notes Pinning SDK versions for consistent builds Recommended Solution Layout Key principles: Separate src/ and tests/ directories One project per concern (Core/Domain, Infrastructure, API/Host) Solution file at the repo root All shared build configuration at the repo root Solution File Formats .slnx (Modern — .NET 9+) The XML based solution format is human readable and diff friendly. Requires .NET 9+ SDK or Visual Studio 17.13+. Migrating from .sln to .slnx Important: Do not keep both .sln and .slnx files in the same repository. Creating a New .slnx Solution Benefits Dramatically fewer merge conflicts Human readable and editable Consistent with modern .csproj format Better diff/review experience in pull requests Directory.Build.props Shared MSBuild properties applied to all projects in the directory subtree. Nested Directory.Build.props Inner files do not automatically import outer files: Directory.Build.targets Imported after project evaluation. Use for: Shared analyzer package references Custom build targets Conditional logic based on project type Directory.Packages.props Central Package Management CPM centralizes all NuGet package versions at the repo root. Individual .csproj files reference packages without a Version attribute. Consuming Packages (No Version Needed) Version Overrides .editorconfig Place at the repo root to enforce consistent code style: global.json SDK Version Pinning Roll Forward Policies Policy Behavior disable Exact version required patch Same major.minor, latest patch feature Same major, latest minor.patch latestFeature Same major, latest feature band minor Same major, latest minor latestMinor Same major, latest minor major Latest SDK (not recommended) Recommended: latestFeature Allows patch updates within the same feature band. nuget.config Configure package sources and security: The <clear / + explicit sources + <packageSourceMapping pattern prevents supply chain attacks. For private feeds: NuGet Audit .NET 9+ enables NuGetAudit by default: Lock Files Enable deterministic restores: In CI: SourceLink and Deterministic Builds For libraries published to NuGet: Version Management with RELEASE NOTES.md CI/CD Integration Quick Reference File Purpose MySolution.slnx Modern XML solution file Directory.Build.props Centralized build properties Directory.Packages.props Central package version management global.json SDK version pinning NuGet.Config Package source configuration RELEASE NOTES.md Version history .editorconfig Code style enforcement .config/dotnet tools.json Local .NET tools References [.NET Library Design Guidance](https://learn.microsoft.com/en us/dotnet/standard/library guidance/) [Central Package Management](https://learn.microsoft.com/en us/nuget/consume packages/central package management) [.slnx Format](https://learn.microsoft.com/en us/visualstudio/ide/reference/solution file) [Directory.Build.props](https://learn.microsoft.com/en us/visualstudio/msbuild/customize your build) [SourceLink](https://learn.microsoft.com/en us/dotnet/standard/library guidance/sourcelink) [NuGet Audit](https://learn.microsoft.com/en us/nuget/concepts/auditing packages)

project-structure