/project-structure

name: dotnet-project-structure
description: Modern .NET project structure including .slnx solution format, Directory.Build.props, central package management, SourceLink, version management with RELEASE_NOTES.md, and SDK pinning with global.json.
user-invocable: false

.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

Related Skills

• **`dotnet-local-tools`** - Managing local .NET tools with dotnet-tools.json
• **`microsoft-extensions-configuration`** - Configuration validation patterns

---

Solution File Format (.slnx)

The `.slnx` format is the modern XML-based solution file format introduced in .NET 9. It replaces the traditional `.sln` format.

Benefits Over Traditional .sln

| Aspect | .sln (Legacy) | .slnx (Modern) | |--------|---------------|----------------| | Format | Custom text format | Standard XML | | Readability | GUIDs, cryptic syntax | Clean, human-readable | | Version control | Hard to diff/merge | Easy to diff/merge | | Editing | IDE required | Any text editor |

Version Requirements

| Tool | Minimum Version | |------|-----------------| | .NET SDK | 9.0.200 | | Visual Studio | 17.13 | | MSBuild | Visual Studio Build Tools 17.13 |

**Note:** Starting with .NET 10, `dotnet new sln` creates `.slnx` files by default. In .NET 9, you must explicitly migrate or specify the format.

Example .slnx File

<Solution>
  <Folder Name="/build/">
    <File Path="Directory.Build.props" />
    <File Path="Directory.Packages.props" />
    <File Path="global.json" />
    <File Path="NuGet.Config" />
    <File Path="README.md" />
  </Folder>
  <Folder Name="/src/">
    <Project Path="src/MyApp/MyApp.csproj" />
    <Project Path="src/MyApp.Core/MyApp.Core.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/MyApp.Tests/MyApp.Tests.csproj" />
  </Folder>
</Solution>

Migrating from .sln to .slnx

Use the `dotnet sln migrate` command to convert existing solutions:

# Migrate a specific solution file
dotnet sln MySolution.sln migrate

# Or if only one .sln exists in the directory, just run:
dotnet sln migrate

**Important:** Do not keep both `.sln` and `.slnx` files in the same repository. This causes issues with automatic solution detection and can lead to sync problems. After migration, delete the old `.sln` file.

You can also migrate in Visual Studio: 1. Open the solution 2. Select the Solution in Solution Explorer 3. Go to **File > Save Solution As...** 4. Change "Save as type" to **Xml Solution File (*.slnx)**

Creating a New .slnx Solution

# .NET 10+: Creates .slnx by default
dotnet new sln --name MySolution

# .NET 9: Specify the format explicitly
dotnet new sln --name MySolution --format slnx

# Add projects (works the same for both formats)
dotnet sln add src/MyApp/MyApp.csproj

Recommendation

**If you're using .NET 9.0.200 or later, migrate your solutions to .slnx.** The benefits are significant:

• Dramatically fewer merge conflicts (no random GUIDs changing)
• Human-readable and editable in any text editor
• Consistent with modern `.csproj` format
• Better diff/review experience in pull requests

---

Directory.Build.props

`Directory.Build.props` provides centralized build configuration that applies to all projects in a directory tree. Place it at the solution root.

Complete Example

<Project>
  <!-- Metadata -->
  <PropertyGroup>
    <Authors>Your Team</Authors>
    <Company>Your Company</Company>
    <!-- Dynamic copyright year - updates automatically -->
    <Copyright>Copyright © 2020-$([System.DateTime]::Now.Year) Your Company</Copyright>
    <Product>Your Product</Product>
    <PackageProjectUrl>https://github.com/yourorg/yourrepo</PackageProjectUrl>
    <RepositoryUrl>https://github.com/yourorg/yourrepo</RepositoryUrl>
    <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
    <PackageTags>your;tags;here</PackageTags>
  </PropertyGroup>

  <!-- C# Language Settings -->
  <PropertyGroup>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <NoWarn>$(NoWarn);CS1591</NoWarn> <!-- Missing XML comments -->
  </PropertyGroup>

  <!-- Version Management -->
  <PropertyGroup>
    <VersionPrefix>1.0.0</VersionPrefix>
    <PackageReleaseNotes>See RELEASE_NOTES.md</PackageReleaseNotes>
  </PropertyGroup>

  <!-- Target Framework Definitions (reusable properties) -->
  <PropertyGroup>
    <NetStandardLibVersion>netstandard2.0</NetStandardLibVersion>
    <NetLibVersion>net8.0</NetLibVersion>
    <NetTestVersion>net9.0</NetTestVersion>
  </PropertyGroup>

  <!-- SourceLink Configuration -->
  <PropertyGroup>
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.SourceLink.GitHub" PrivateAssets="All" />
  </ItemGroup>

  <!-- NuGet Package Assets -->
  <ItemGroup>
    <None Include="$(MSBuildThisFileDirectory)logo.png" Pack="true" PackagePath="\" />
    <None Include="$(MSBuildThisFileDirectory)README.md" Pack="true" PackagePath="\" />
  </ItemGroup>

  <PropertyGroup>
    <PackageIcon>logo.png</PackageIcon>
    <PackageReadmeFile>README.md</PackageReadmeFile>
  </PropertyGroup>

  <!-- Global Using Statements -->
  <ItemGroup>
    <Using Include="System.Collections.Immutable" />
  </ItemGroup>
</Project>

Key Patterns

Dynamic Copyright Y