`slnx` support in the `dotnet` CLI

baronfel commented 3 months ago

The dotnet CLI should support the new slnx format for building and in the existing solution management commands. It should also help interested users migrate to the new format.

The new format

slnx is an XML-based format that simplifies the current sln file format. When released, it will have an open-source parser, so tools like MSBuild and the dotnet CLI can consistently operate on the format. The new format is intended to reduce common customer pains like merge conflicts and readability, but not to drastically change the experience of working with solutions.

`dotnet` experiences using solutions

There are three primary ways that the dotnet CLI interacts with solution files today

building solutions
- dotnet build myapp.sln
adding or removing projects and other files from solutions
- dotnet sln myapp.sln add src/migrations
creating new solutions
- dotnet new solution -n lodestone

Each of these should be made to work with the new format to some degree. In addition, a fourth new capability should be added:

migrating from sln to slnx
- dotnet sln <sln file> migrate [-o <slnx file name>]

Building solutions

This should be mostly transparent to the dotnet CLI. Much like solutions today, building a solution involves passing the path to the solution file to the MSBuild engine, which has the sole responsibility of converting the build configurations into a 'metaproject' - a kind of MSBuild representation that MSBuild can actually execute - and then building the requested targets on that metaproject.

The same process would hold with slnx - the CLI would forward along the slnx file provided (if any) and MSBuild itself would translate that file into a metaproject and execute that metaproject. Very few changes should be required in the CLI codebase to support this. MSBuild's tracking issue for this is https://github.com/dotnet/msbuild/issues/10266.

Manipulating solution content

The CLI has several commands that allow for adding and removing projects in a solution, as well as listing the existing projects. All of these commands should work with slnx as well. This is the area that will require the most investment. The CLI will need to

learn that slnx files are valid inputs to these commands
provide some kind of alternative implementation for these commands that works on slnx files
pivot the implementation used based on the file type provided

These commands allow for selection of the solution file. If invoked in a location where multiple potential solution files are present, the command should error and prompt the user to choose one of the possible solutions.

We'll also need to invest in test coverage to make sure we have parity between our sln support and slnx support.

Creating new solutions

The CLI currently ships a solution template that create a new, barebones solution file.

We should provide a template that can create an empty slnx file for users to begin with. The new slnx template should use UTF-8 without a BOM. One major question: should we supplant the existing solution template to create an slnx file? Should the old solution format be accessible via a template parameter?

Migrating existing solutions

An entirely new capability to migrate a sln file to a new slnx file should be implemented as well to ease onboarding and allow for automation. This command would load the existing sln file and analyze it, translating it into an equivalent slnx file. Ideally any data that matches the default conventions of the new slnx format (for example, default build configurations like Debug and Release) could be omitted from the generated slnx file.

References

glen-84 commented 3 months ago

Regarding the solution template, would it possible to exclude the byte order mark (BOM) now, or are there still known issues with VS or msbuild?

I know that:

The Unicode Standard does not recommend its use.
Even applications like Notepad now use UTF-8 without BOM by default. (source)

baronfel commented 3 months ago

@glen-84 I'm inclined to make that change, but would like to discuss with @rainersigwald and the rest of the MSBuild team about any gaps there.

rainersigwald commented 3 months ago

For .sln I would leave it as it has been (I believe that's the longstanding Windows 16-bit chars with BOM).

For .slnx we should definitely avoid the BOM but would need to check with the VS folks to make sure they agree.

baronfel commented 3 months ago

I've reached out to the VS side to check compatibility with no-BOM.

baronfel commented 3 months ago

The VS team confirmed that slnx defaults to UTF-8 No-BOM, so we are clear to default the slnx template contents to no-BOM as well. I've updated the description to match this.

vaind commented 2 months ago

Is there any concrete plan for this? I'm looking forward to build/test/restore support for slnx (also when referenced from a .slnf) so that we can update Sentry .NET SDK to use the new format.. Adding projects to the old format is so cumbersome when you need to keep a PR reviewable.

baronfel commented 2 months ago

We are still waiting for an official parser library for the new format to be made available by our partner teams. We're unable to make any progress without that library (and the stabilized format spec implied by that)

kasperk81 commented 1 month ago

dotnet / sdk