Msbuild: Add the ability to write comments in a solution (.sln) file

[tom-corwin]

I think it would be beneficial to allow for comments in a solution file, since not all solution files are generated/managed by an IDE, but directly edited in a text editor. There are articles/comments online that say the # character is used for comments, but that's not quite how the solution file is processed by msbuild:

https://github.com/microsoft/msbuild/blob/0f3d8e94ac11dd892c0c2fadb28b1a42e0d45fb1/src/Build/Construction/Solution/SolutionFile.cs#L435-L462

EDIT: Removed ambiguous references and other formatting.

[rainersigwald]

There's a comment baked into ~every solution file, like ours:

https://github.com/Microsoft/msbuild/blob/13843078ee8c824facae4ac7c96ecdd6d5b9d54c/MSBuild.sln#L3

But it looks like our parser handles that via this case:

https://github.com/Microsoft/msbuild/blob/13843078ee8c824facae4ac7c96ecdd6d5b9d54c/src/Build/Construction/Solution/SolutionFile.cs#L457-L461

Which works only for top-level elements. If Visual Studio's solution parser handles comment lines elsewhere, MSBuild's should too.

[tom-corwin]

Which works only for top-level elements. If Visual Studio's solution parser handles comment lines elsewhere, MSBuild's should too.

My main use case for this is to separate the ProjectConfigurationPlatforms in the global sections, so it's easier to see what is what when you have numerous projects in a solution, so top-level comments don't really help in that situation.

EDIT: I don't know if VS's parser handles comments, but i agree that the implementations should parse two identical files the same, comments or not.

[alanta]

Another use case for this is to allow excluding parts of a .sln file in a _dotnet new_ template. For example:

#if (includedatabase)
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microservice.Database", "Microservice.Database\Microservice.Database.csproj", "{6F650E2B-8E2C-414A-A5CA-6B983B39746B}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microservice.Database.Migrations", "Microservice.Database.Migrations\Microservice.Database.Migrations.csproj", "{51DCC1F2-D929-429C-80AD-F446C8386CE1}"
EndProject
#endif

This is part of a solution file that's packaged up into a template and processed when the package is newed up. The comments are processing instructions for _dotnet new_.
To verify the solution before packaging I tried to build it, but after adding these comments the solution no longer builds from the CLI (.NET Core 3.0 preview 6). I can load it in Visual Studio 2019 without problems though.

[rainersigwald]

In #4451, @rrelyea reported

It turned out that a comment in the wrong place of the solution file, worked fine in VS, but broke msbuild parsing of that solution.

Which answers that question that we had above.

[brettrowberry]

I put # comments in a .sln file and built against the 3.1.201 SDK and it worked great! My template had a class library, a test project, a webapi, and a console app. The template has a switch to choose between the console app and the webapi. It's all in F#, including the template pack project! Here's a snippet of the .sln file.

#if (project-type == "webapi")
Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "Name.WebApi", "Name.WebApi\Name.WebApi.fsproj", "{6F89DBFC-2E09-45DA-82D3-E9F605B76389}"
EndProject
#endif
#if (project-type == "console")
Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "Name.Console", "Name.Console\Name.Console.fsproj", "{0C2A9339-81B7-4C8F-B1F8-23915A6542C0}"
EndProject
#endif
Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "Name", "Name\Name.fsproj", "{2511DBCE-E53C-4E8A-A3F9-88A85ACCD824}"
EndProject
Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "Name.Tests", "Name.Tests\NameTests.fsproj", "{46CC6586-892A-4377-B90D-800BE2E10D6D}"
EndProject

I recommend trying comments again with a newer SDK.

[tom-corwin]

I haven't looked into this for a while, as per @brettrowberry, I will try adding comments into a new solution file tonight, and see what happens when built with the .NET CLI and Visual Studio.

[tom-corwin]

So, after some testing (using the VS Developer CMD Prompt and dotnet build), it seems that comments are allowed in nearly all parts of the solution file. The only time I ran into a build error was when there were comments in the ProjectConfigurationPlatforms and SolutionConfigurationPlatforms global sections. The errors were:

A:\temp\slnfilecommentdemo\SlnCommentTest.sln(21): Solution file error MSB5008: Error parsing the solution configuration section in solution file. The entry "# Comment 8" is invalid.

A:\temp\slnfilecommentdemo\SlnCommentTest.sln(27): Solution file error MSB5008: Error parsing the solution configuration section in solution file. The entry "# Comment 10" is invalid.

You can find the solution that I used for testing in this repo.

EDIT: I should point out that the solution loaded fine in VS 16.6.2, it just wouldn't build.