skip to content

With the .NET 10 SDK, how do .sln and .slnx solution files differ, and how would you move a 40-project solution to .slnx with dotnet sln migrate?

level: seniorimportance: should knowfreq 32%

answer

  1. GUID text format vs plain XML
  2. dotnet new sln writes .slnx in .NET 10
  3. --format sln for the old format
  4. migrate writes .slnx, keeps .sln
  5. SDK support since 9.0.200

basics

~20 s

.sln is the old line-based format full of GUIDs and configuration sections; .slnx is a short XML file listing projects and folders. dotnet sln App.sln migrate writes App.slnx next to the original, after which you switch every reference and delete the .sln.

solid answer

~40 s

An `.sln` file repeats each project with type and project GUIDs and lists every configuration-platform pair in `GlobalSection` blocks, so it is long and merge-conflict prone. An `.slnx` is XML: a `<Solution>` with `<Folder>` and `<Project Path="..." />` elements, using defaults for the rest. The SDK has read `.slnx` since 9.0.200, and from .NET 10 `dotnet new sln` creates `.slnx` unless you pass `--format sln`. For a 40-project solution: pin the SDK so every agent can read `.slnx`, run `dotnet sln Shop.sln migrate` (which writes `Shop.slnx` and fails if one exists), check `dotnet sln Shop.slnx list` and a build, then delete the `.sln` and update pipeline paths in the same change. Leaving both files makes commands that search the folder find two solutions and ask you to choose.

code

xml · 9 lines
xml
<Solution>
  <Folder Name="/src/">
    <Project Path="src/Shop.Api/Shop.Api.csproj" />
    <Project Path="src/Shop.Billing/Shop.Billing.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/Shop.Api.Tests/Shop.Api.Tests.csproj" />
  </Folder>
</Solution>

go deeper

for a junior

Recall that .slnx is the newer XML solution format and that the .NET 10 SDK creates it by default.

for a middle

Explain how the two formats differ, how dotnet sln add, list and migrate work, and which SDK versions read .slnx.

for a senior

Run the migration safely: pin the SDK, verify the project list and build, switch every pipeline reference and delete the .sln in one change.

for a principal

Plan format changes across many repositories: tool compatibility, SDK pinning, and a cut-over that avoids two solution files living on in parallel.

## Two formats A **solution file** groups projects so tools can build, test and open them together. .NET has two formats: | | `.sln` | `.slnx` | |---|---|---| | Syntax | custom text format | XML | | Projects | `Project("{type GUID}") = ...` lines with a project GUID each | `<Project Path="src/Shop.Api/Shop.Api.csproj" />` | | Configurations | every project times every configuration-platform pair in `GlobalSection` blocks | defaults; only exceptions are written | | Merge conflicts | frequent: GUIDs and long mapping sections | rare: one line per project | | CLI support | all SDKs | SDK 9.0.200 and later | In **.NET 10**, `dotnet new sln` creates an `.slnx` by default. `dotnet new sln --format sln` still produces the old format for tools that cannot read the new one. ## The scenario A team has `Shop.sln` with 40 projects in solution folders `src`, `tests` and `tools`. Every new project added on a branch touches the same `GlobalSection` lines, and merges keep breaking the file. The goal is `Shop.slnx`. ## The migration, step by step 1. **Pin an SDK that understands `.slnx`** on every machine and agent, typically with `global.json` at a .NET 10 version and `latestFeature`, and check that the IDEs and any other tools the team uses open `.slnx`. 2. **Generate the new file**: `dotnet sln Shop.sln migrate` writes `Shop.slnx` next to it, converting projects and solution folders. It fails if you pass an `.slnx`, or if `Shop.slnx` already exists. It does **not** delete `Shop.sln`. 3. **Verify**: `dotnet sln Shop.slnx list` should show all 40 projects; then `dotnet build Shop.slnx` and `dotnet test Shop.slnx`. Compare the project list against the old file if any project used unusual configuration mappings. 4. **Switch references**: CI scripts, build files, IDE launch settings and documentation that name `Shop.sln`. 5. **Delete `Shop.sln`** in the same commit. While both exist, commands that look for a solution in the folder, such as `dotnet sln list`, find two and ask you to name one, and developers keep editing the old file. ## Working with the new file - `dotnet sln add src/Shop.Billing/Shop.Billing.csproj` adds a project, creating solution folders from the path; `--in-root` puts it at the root, and `-s|--solution-folder` names a folder. - `dotnet sln remove` and `dotnet sln list` work the same on both formats. - Hand edits are reasonable now: the file is short, readable XML. ## Risks to check - Older SDKs, below 9.0.200, cannot read `.slnx`, so a pipeline pinned to an old SDK breaks. - Third-party tools that parse `.sln` text themselves need to support the XML format before you delete the old file. - Custom configuration mappings, such as a project built only in `Release`, should be reviewed in the generated file. ## Common mistakes - Running `migrate` and committing both files, which leaves two sources of truth. - Migrating while open branches still add projects to the `.sln`; land those first, or re-add the projects to the `.slnx` after merging. ## Solution filters and large solutions Large solutions often come with solution filters (`.slnf` files) that open a subset of projects in an IDE. A filter refers to its parent solution by path, so after the migration each filter must point at `Shop.slnx` instead of `Shop.sln`. Check them in the same change, because a filter that still names the deleted file stops opening.

  • How do you create a new solution in the old format with the .NET 10 SDK?
    Pass `--format sln` to the template: `dotnet new sln --format sln`. Without it, the .NET 10 SDK writes an `.slnx` file.
  • Why does an .slnx rarely produce merge conflicts?
    Each project is one line identified by its path, with no generated GUIDs and no per-configuration mapping block. Two branches adding different projects change different lines, which version control merges cleanly.

  • dotnet sln migrate deletes the .sln after writing the .slnx.
  • Any .NET SDK can build an .slnx file.
  • An .slnx still needs a GUID for every project.
  • Keeping .sln and .slnx side by side has no effect on the CLI.
  • dotnet new sln in .NET 10 still writes an .sln by default.

Assumes the .NET 10 SDK; dotnet new sln writes .slnx by default only from .NET 10, while .slnx support in the CLI dates from SDK 9.0.200.