Modern Software Engineering

The GUIDs in your .sln were never data

Meysam Pourmonfared Azimi — Fri, 04 Sep 2026 12:06:22 GMT

Two people add a project on Friday afternoon. One adds Payments.Api, the other adds Payments.Worker. Neither has touched the other's code. Both branches merge cleanly everywhere except one file, and it is the file nobody wants to own.

The conflict is not in the project list. It is thirty lines lower, in a block that looks like this:

{8CDD8387-B905-44A8-B5D5-07BB50E05BEA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{8CDD8387-B905-44A8-B5D5-07BB50E05BEA}.Debug|Any CPU.Build.0 = Debug|Any CPU

Both developers appended four rows to the same global section, keyed by GUIDs neither of them chose, neither of them can read, and neither of them can verify by eye. Resolving it means deciding whether two opaque identifiers belong in the file — which is a question a human is unusually badly equipped to answer, and a question that never had to be asked.

That is the part of the .slnx story worth writing about. Not that XML is prettier.

What the old format was actually storing

Microsoft's own extensibility documentation is precise about the two GUIDs on a Project line: "This statement contains the unique project GUID and the project type GUID. This information is used by the environment to find the project file or files belonging to the solution, and the VSPackage required for each project."

Read that carefully. The project type GUID identifies which VSPackage loads the project — a resolution the file extension already determines. The unique project GUID identifies the project within the solution — an identity the relative path already provides, because two projects at the same relative path are the same project. Neither GUID carries a fact you could not recover from the path.

What they did carry was a cost. Every relation about a project was expressed by repeating its GUID in a different global section: nesting in NestedProjects, build order in ProjectDependencies, configuration mapping in ProjectConfigurationPlatforms two or three rows (ActiveCfg, Build.0, sometimes Deploy.0) for every solution configuration the project participates in. Adding one project meant appending to three or four append-only regions of one file. That is the merge-conflict generator, and it is structural rather than cosmetic.

What the schema says

The format is defined by a real schema in the library that reads and writes it, microsoft/vs-solutionpersistence. Slnx.xsd on main defines a project as:

One required attribute: the path. No Id. Type is optional, and the library explains why in a doc comment on ProjectType: it "maps a friendly name and or a file extension to a project type id", and the extension "can be used to determine the project type automatically". The type GUID is a function of the path, so the format stores the path and computes the GUID.

Solution folders lose their lookup table too. In .slnx a Folder has one required attribute, Name, and projects nest inside it as XML children — containment instead of a NestedProjects section of GUID pairs. Build order survives as on the project it belongs to.

The configuration mapping is the most interesting collapse. Instead of N × M rows, the schema has a rule group BuildType, Platform, Build, Deploy, each with an optional Solution attribute (which solution configuration this matches) and a Project attribute (what the project should do). Those rules hang off either a ProjectType or an individual Project. So the defaults for every .csproj in the solution are stated once, against the type, and a project only appears in the file when it deviates. The excluded-from-Release test project is now a two-line exception rather than a row in a wall of rows.

And this is the claim the whole thing rests on, from the .NET Blog: the new format "is much more concise than the old format – but it contains all of the same data!" Same data. What was removed was encoding.

The idea underneath

A solution file is a serialization of a small labelled graph. Projects are nodes, solution folders are a tree overlay, build dependencies are edges, and the configuration mapping is a function from (solution configuration, project) to (project configuration, build, deploy).

The .sln format gave every node a surrogate key and then expressed every relation by repeating that key elsewhere. .slnx uses the natural key that already existed and was already unique inside the solution — the relative path — and expresses relations by containment.

The framing is mine, not Microsoft's, but it makes a prediction you can check. A three-way text merge conflicts on co-located edits. Surrogate keys guarantee that facts about one node are scattered into shared global regions, so two semantically disjoint additions land in the same line range and collide. Natural keys plus containment put an addition on one line, in a position determined by where the project lives. That is the mechanism behind Microsoft's much blander phrasing: "By simplifying the file structure, we've reduced the likelihood of merge conflicts in version control systems."

Where the GUIDs came back

Two honest limits, because a piece that only shows the good half is not worth trusting.

Visual Studio has been observed writing GUIDs back in. Issue #109 on vs-solutionpersistence shows VS rewriting as the same element with Id="896cf6f3-..." on save. The schema on main declares only Name on Folder. The issue is closed with no visible maintainer answer, so whether current Visual Studio still does this is something to check on your own repo rather than take from me.

And extension-based type inference is not total. In dotnet/sdk#47638, dotnet sln add on a .msbuildproj failed with "Project has an unknown project type and cannot be added to the solution file." — while dotnet sln migrate kept the Type for the same project. That asymmetry is exactly why Type is in the schema as an optional attribute: inference is the default, not a promise.

What the migration actually costs

The conversion is one command, dotnet sln MySolution.sln migrate, and the interesting work is everywhere else.

Toolchain floors, on every machine and not just yours. SDK 9.0.200 for the CLI. MSBuild or Build Tools for Visual Studio 17.13 or later to build. Visual Studio 17.14 to open. Your laptop is not the constraint; the CI image with a pinned SDK is.

Two files in one folder is the real failure mode. Microsoft is blunt about it: "it's an error to run dotnet build or other commands that need to build in a directory with both a .sln and a .slnx — we don't know which one to build!" Delete the old file in the same commit, and update every workflow, script, Dockerfile and README that names it. Note also that dotnet sln migrate refuses to run if a .slnx of that name already exists — if you hit that, someone migrated before you and the two files may have diverged.

Check what the old file carried besides the project list. Solution folders and the loose files pinned into them, per-project configuration mappings, build-order dependencies, and projects deliberately excluded from a configuration — that last one is invisible, because it is an absent Build rule rather than an absent project. Diff dotnet sln .slnx list against the baseline, then read the XML for the rest.

Multi-project startup is the thing that silently disappears. dotnet/sdk#48014 asked for dotnet sln migrate to carry .slnLaunch over as .slnxLaunch. It was closed as not planned. If your team runs three services on F5, verify that before you delete anything.

Generators ignore your preference. Visual Studio 2026 exposes a "Default Solution File Format" option, but Unity — and anything else that regenerates a solution — writes whatever it wants.

Where this is going

The direction is settled. Since .NET 10, dotnet new sln emits and you need --format sln to get the old thing back; the stated reason is that SLNX has proven "a stable and understandable format". Visual Studio 2026 makes the choice a setting. In .NET 11, currently in preview with a November 2026 target, the only solution-related change is that dotnet sln can create and edit solution filters (.slnf) from the CLI, and a filter's parent can be a .sln or a .slnx.

There is no .NET 11 breaking change for .slnx. The format stopped being news, which is the outcome a file format should want.

Sources. .NET Blog, "Introducing support for SLNX" (2025-03-13) · Visual Studio Blog, "New, Simpler Solution File Format" (2025-03-13) · Microsoft Learn, dotnet sln reference and the .NET 10 breaking change for dotnet new sln · Microsoft Learn, "Solution (.sln) file", VS extensibility internals · microsoft/vs-solutionpersistence — Slnx.xsd, ProjectType.cs, issue #109 · dotnet/sdk issues #47638 and #48014, PR #51156 · What's new in .NET 11. All accessed 2026-09-01.

Not executed here. No .NET SDK was available in the environment where this was written, so no command above was run and no output was captured live. Every version floor, command and error string is quoted from the sources listed. Run the migration on one real repository before you run it on twelve.

If you have already moved a large solution: what did you find missing in the .slnx that you only noticed a week later?

#dotnet #csharp #softwarearchitecture

Central Package Management in .NET: One File, Zero Version Drift

Meysam Pourmonfared Azimi — Tue, 01 Sep 2026 12:53:33 GMT

Api.csproj references Serilog 4.0.0. Worker.csproj is on 3.1.1. A shared library nobody has touched since last winter is on something else entirely. The build is green. The tests pass. And then a behaviour differs between two services that were supposed to be running identical code.

Central Package Management (CPM) is NuGet's answer to that. It is not a new package format, not a tool to install, and not a migration you need a sprint for. It is one file, one property, and a handful of build errors that are on your side.

The File Structure

Create Directory.Packages.props at the root of the repository:


  
    true

Then strip the versions out of every project file:

PackageVersion declares which version. PackageReference declares who needs it. The two concerns stop living in the same line, and the second one stops being copy-pasted across a dozen files.

The file follows the same MSBuild import rules as Directory.Build.props — nearest one wins, walking up from each project — so a large monorepo can scope a subtree to its own set of versions if it truly needs to.

The four error codes worth knowing by heart

CPM's real value is that it converts a review comment into a compiler error. Four of them do most of the work:

NU1008 —> someone left a version behind on a project reference:

Projects that use central package version management should not define the version on the PackageReference items but on the PackageVersion items: Newtonsoft.Json.

This is the guardrail. Once CPM is on, the old habit of pinning a version inside a .csproj simply stops building. No convention doc required.

NU1010 —> a package is referenced but has no central version:

The PackageReference items Serilog do not have corresponding PackageVersion.

You will meet this one a lot during migration, and it is the friendliest error in the set: it hands you the exact list of PackageVersion entries you still have to add.

NU1013 —> a deliberate escape hatch that has been closed:

The package reference Newtonsoft.Json specifies a VersionOverride but the ability to override a centrally defined version is currently disabled.

VersionOverride lets a single project deviate from the central version — the pragmatic escape hatch for the one service that genuinely cannot move yet. If you would rather have no escape hatches at all, set CentralPackageVersionOverrideEnabled to false and any attempt to use one fails with NU1013.

NU1109 —> the one people meet after enabling transitive pinning:

Detected package downgrade: Serilog from 4.0.0 to centrally defined 3.1.1. Update the centrally managed package version to a higher version.

Which brings us to the feature that makes CPM more than tidy bookkeeping.

Transitive pinning

Turn it on with CentralPackageTransitivePinningEnabled:


  true
  true

Now your central versions apply to packages you never referenced directly. If a project pulls in Serilog.Sinks.Console and that package depends on Serilog, the transitively-resolved Serilog is lifted to the version in Directory.Packages.props — without adding a direct PackageReference to the project.

This is the answer to the "we have a CVE in a package three levels down" fire drill. One line in one file, and every project in the repository resolves the patched version.

The trade is NU1109: if a dependency demands a higher version than the one you pinned centrally, the restore now fails instead of silently unifying upward. That is a feature. It surfaces the conflict at the place where the decision belongs.

And note the precedence: with transitive pinning enabled, a VersionOverride on a direct reference still wins for that project. The narrower, more explicit statement beats the broader one.

GlobalPackageReference

The other quiet win. In Directory.Packages.props:

Every project in the repository now references it. This is exactly right for build-time-only concerns (analyzers, source generators, SourceLink) and exactly wrong for runtime libraries, because the reference is not something an individual project opted into.

One line, and the analyzer rollout that used to be twelve pull request comments is done.

The gotchas

Three things reliably cost people an afternoon:

Multiple package sources. If your NuGet.config defines more than one source, CPM will push you toward package source mapping (NU1507). This is a good thing, mapping which packages may come from which feed closes a real supply-chain hole, but it is work you did not plan for on migration day. Check your NuGet.config before you start, not after.

Tooling that still writes versions. dotnet add package and some IDE dialogs will happily write a Version attribute into your .csproj. The build catches it with NU1008, which is the system working, but expect the papercut until everyone's muscle memory updates.

Half-migrated repositories. CPM is per-project, not per-repository: a project without ManagePackageVersionsCentrally in scope keeps its own inline versions and quietly stays outside the system. If you migrate in stages, keep a list of what is not yet in, or the whole point is lost to a project nobody remembers.

The migration, in order

Add Directory.Packages.props with ManagePackageVersionsCentrally set to true.
Build. Read the NU1010 list, it is your inventory of every package in the solution.
Add a PackageVersion for each, deciding the single version where two projects disagree.
Delete the Version attributes from the project files. NU1008 tells you the ones you missed.
Move analyzers to GlobalPackageReference.
Enable transitive pinning last, once the direct versions are stable, and resolve any NU1109 conflicts it exposes.

It is an afternoon on a repository of moderate size, and it is the kind of afternoon that pays for itself the first time a security advisory lands.

All error messages in this article are real messages captured from a .NET SDK 8.0.130 build against a local package feed, not quoted from documentation.

What is the messiest version drift you have found in a repository you inherited?

#dotnet #csharp #softwareengineering #CenteralPackageManagement

repo : https://github.com/poormonfared/CPM-Demo