What is the difference between a .sln and a .slnx solution file, and when would you use a solution filter?

1. Where the solution sits

        IDE / dotnet build
               |
               v
   +-------------------------+        +----------------------+
   | Contoso.slnx            |        | Payments.slnf        |
   |  list of projects       |<-------|  subset of projects  |
   |  folders, config maps   |        +----------------------+
   +-------------------------+
               |
     +---------+----------+
     v         v          v
  Api.csproj Domain.csproj Tests.csproj   <-- build logic lives here
     \         |          /
      Directory.Build.props / .targets     <-- and here

A solution answers two questions: which projects belong together, and which project configuration to build for each solution configuration (for example, solution Release|Any CPU builds every project as Release|AnyCPU). Everything else (target framework, packages, compiler settings) lives in project files.

The quick test: delete the solution, and every project should still build with dotnet build path/to/project.csproj. If it doesn't, build logic has leaked into the solution, usually through $(SolutionDir) (see section 6).

2. How MSBuild builds a solution

MSBuild doesn't understand solution files natively. When you run dotnet build Contoso.slnx (or .sln), it converts the solution into an in-memory metaproject: a generated MSBuild project with one MSBuild task call per project, passing the mapped Configuration and Platform.

 Contoso.slnx --parse--> metaproject (in memory)
                            |
                            +-- MSBuild Api.csproj      Configuration=Release
                            +-- MSBuild Domain.csproj   Configuration=Release
                            +-- MSBuild Tests.csproj    Configuration=Release
                                   |
                                   +-- ProjectReference --> built on demand

Set the environment variable MSBUILDEMITSOLUTION=1 to write the metaproject to disk as Contoso.slnx.metaproj and see exactly what it does. Build order comes from ProjectReference items, not from the order in the solution.

3. The two formats compared

What a .sln entry really contains

Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Orders.Api", "src\Orders.Api\Orders.Api.csproj", "{6A1C4F0E-...}"
EndProject
...
Global
  GlobalSection(ProjectConfigurationPlatforms) = postSolution
    {6A1C4F0E-...}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
    {6A1C4F0E-...}.Debug|Any CPU.Build.0 = Debug|Any CPU
    {6A1C4F0E-...}.Release|Any CPU.ActiveCfg = Release|Any CPU
    {6A1C4F0E-...}.Release|Any CPU.Build.0 = Release|Any CPU
  EndGlobalSection
  GlobalSection(NestedProjects) = preSolution
    {6A1C4F0E-...} = {2150E333-...}
  EndGlobalSection
EndGlobal

The first GUID is the project type (C# SDK-style, in this case). The second is the project's own id. Each new project adds lines in three different places, which is why two branches that each add a project almost always conflict.

The same thing in .slnx

<Solution>
  <Folder Name="/Solution Items/">
    <File Path="Directory.Build.props" />
    <File Path="global.json" />
  </Folder>
  <Folder Name="/src/">
    <Project Path="src/Orders.Api/Orders.Api.csproj" />
    <Project Path="src/Orders.Domain/Orders.Domain.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/Orders.Tests/Orders.Tests.csproj" />
  </Folder>
</Solution>

No GUIDs, forward slashes in paths, and one line per project. Non-standard mappings, such as a project that should only build for one platform, are written as child elements of that <Project>.

4. Migrating from .sln to .slnx

1. List every tool that reads solution files: CI scripts, code-analysis tools, documentation generators, internal scripts that parse the .sln text. Check each supports .slnx.
2. Make sure everyone has a supporting IDE version and an SDK of 9.0.200 or later (pinned in global.json).
3. Run dotnet sln Contoso.sln migrate. It writes Contoso.slnx next to the original.
4. Build and test with the new file locally and in CI (dotnet build Contoso.slnx). Compare the list of projects with dotnet sln Contoso.slnx list.
5. Delete Contoso.sln in the same pull request, update CI paths and any .slnf files that point at the old name.
6. Announce the change, because open branches that add projects need to add them to the new file.

5. Solution filters (.slnf)

{
  "solution": {
    "path": "Contoso.slnx",
    "projects": [
      "src\\Payments\\Payments.Api\\Payments.Api.csproj",
      "src\\Payments\\Payments.Domain\\Payments.Domain.csproj",
      "tests\\Payments.Tests\\Payments.Tests.csproj"
    ]
  }
}

Filters are a developer convenience. CI usually still builds the full solution, or uses a traversal project, so nothing is missed.

6. Solution-only properties to avoid

When MSBuild builds through a solution, it sets properties such as SolutionDir, SolutionName and SolutionPath. When you build a single project, they are undefined (SolutionDir becomes *Undefined*).

<!-- Breaks when the project is built on its own -->
<Import Project="$(SolutionDir)build\common.props" />

Instead: locate shared files relative to the project, for example with $([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), 'global.json')), or move the settings into Directory.Build.props, which MSBuild finds automatically.

7. Traversal projects for CI

Very large repos often stop relying on a hand-maintained solution in CI:

<!-- dirs.proj at the repo root -->
<Project Sdk="Microsoft.Build.Traversal">
  <ItemGroup>
    <ProjectReference Include="src/**/*.csproj" />
    <ProjectReference Include="tests/**/*.csproj" />
  </ItemGroup>
</Project>

Pin the SDK version in global.json under msbuild-sdks. dotnet build dirs.proj then builds every project found by the globs, so a new project can't be forgotten. Solutions and filters remain for the IDE.

8. Performance

• IDE load time grows with the number of loaded projects. A filter with 15 projects instead of 300 often opens in seconds rather than minutes.
• Build time doesn't change with the file format; .sln and .slnx produce the same metaproject.
• Large solutions in CI benefit more from incremental builds, caching and parallelism (-m) than from the solution format.

9. .NET 11 awareness

Expect .slnx to remain the default and more third-party tools to support it. Keep production repos on the .NET 10 SDK; the solution format needs no change for .NET 11.

10. Try it yourself

1. Create a classic solution: dotnet new sln --format sln -n Demo, then add two projects with dotnet sln Demo.sln add.
2. Open Demo.sln and count the lines and GUIDs.
3. Run dotnet sln Demo.sln migrate and open Demo.slnx.
4. Run dotnet build Demo.slnx and dotnet sln Demo.slnx list.
5. Set MSBUILDEMITSOLUTION=1, build again and open the generated .metaproj file.
6. Write a .slnf that lists one project which references the other, run dotnet build Demo.slnf, and notice the referenced project builds too.
7. Add <Import Project="$(SolutionDir)x.props" Condition="Exists('$(SolutionDir)x.props')" /> to a project, then build the project alone and through the solution, and compare.

# New solution (slnx by default in the .NET 10 SDK)
dotnet new sln -n Contoso
dotnet sln Contoso.slnx add src/Orders.Api/Orders.Api.csproj src/Orders.Domain/Orders.Domain.csproj
dotnet sln Contoso.slnx add --solution-folder tests tests/Orders.Tests/Orders.Tests.csproj
dotnet sln Contoso.slnx list

# Convert an existing classic solution
dotnet sln Legacy.sln migrate

# Build just a team's slice
dotnet build Payments.slnf -c Release