SubSolution

SubSolution is a tool set giving you control on your Visual Studio solutions.

It includes various tools:

• .Subsln files able to generate .sln files.
• A Visual Studio extension using .subsln files to update your solutions.
• A command line tool working with .subsln files.
• .NET libraries to read/write/edit solutions in many ways.

Configuration files: .subsln

SubSolution use XML files with the extension .subsln to describe the content of Visual Studio solutions in a user-friendly syntax.

You can find the .subsln format documentation at this address: https://subsln.github.io.

That address is also the XML namespace used by .subsln files so you will always be a click away from the doc!

<Subsln xmlns="http://subsln.github.io">
    <Root>
        <Folder Name="Tools">
            <Files Path="tools/*.bat" />
        </Folder>
        <Folder Name="Tests">
            <Projects Path="**/*.Tests.csproj" />
        </Folder>
        <Projects Path="src/">
    </Root>
</Subsln>

Syntax overview

• Describe your item hierarchy: <Root>
  • Add projects with glob patterns: <Projects>
  • Add files for quick-access: <Files>
  • Create folders to organize your items: <Folder>
  • Find project dependencies and dependents: <Dependencies> / <Dependents>
  • Include the content of existing solutions: <Solutions> / <SubSolutions>
  • Select what you want to keep from other solutions: <KeepOnly>
  • Apply complex filters on your item sources: <Where>
• Setup your solution configuration-platforms: <Configurations> / <Platforms>
  • Ignore them to auto-generate from projects.
  • Create new ones: <SolutionConfiguration> / <SolutionPlatform>
  • Match them with project configurations and platforms: <ProjectConfiguration> / <ProjectPlatform>
• And a lot more options as XML attributes !

The complete documentation is available on https://subsln.github.io.

Why use a .subsln file ?

• It allows you to express your solution organization rules ("those projects in that folder, unit tests in that one...") and ensure they are respected on solution changes.
• It acts as a substitute or edition assistant of .sln files, to describe the solution content with a user-friendly structure similar to the Visual Studio "Solution Explorer" representation.
• It can also be used as a punctual tool, to apply a one-time update.
• It allows to quickly iterate on your solution structure until it matches your needs, without requiring to run Visual Studio.
• It can build an entirely customized hierarchy, or at contrary mirror your file system structure.
• It can find and fill your solution with dependencies of your central projects.
• It can describe solutions in a modular way by including the content of a solution into another.
• It makes it easier to apply changes to multiple solutions sharing the same projects.
• It can create a smaller solution from a big one to have a better environment or performances in Visual Studio.

Visual Studio extension

The Visual Studio extension includes the following features:

• You can create/open the .subsln file associated to the current solution from the Solution Explorer context menu.

  

• When saving a .subsln file, you can see a preview of the updated solution and decide if you want to apply it or not.

  

• When opening a solution, it automatically checks if your solution is up-to-date.

  

Command line tool: subsln

"subsln" is a command line tool using .subsln configuration files to build Visual Studio solutions.

> subsln create MySolution
> subsln generate MySolution.subsln
> subsln validate MySolution.subsln
> subsln show MySolution.sln

Install it with the .NET SDK command line:

> dotnet tool install subsln --global 

Check the Releases page for standalone executables.

By default, subsln will try to find MSBuild binaries on your machine. There are multiple options to specify which MSBuild binaries use to read projects. Use subsln help or subsln [command] --help for more details on commands.

.NET libraries

You can use SubSolution .NET libraries as Nuget packages:

• SubSolution: core package to edit solutions using minimum dependencies.
• SubSolution.Builders: solution building features used by .subsln format.
• SubSolution.MsBuild: project reader implementation based on MSBuild.

The API is structured around 3 representations of solutions:

• Solution:
  • Match the Visual Studio edition experience.
  • Edit the item hierarchy as it show in the Solution Explorer.
  • Automatically fill solution configurations-platforms with your projects.
  • Use ManualSolution to manually fill configuration-platforms.
• RawSolution:
  • Match the .sln format.
  • Dedicated to input/ouput files (but hard to edit).
  • Convert to/from Solution with RawSolutionConverter/SolutionConverter.
• Subsln:
  • Match the .subsln format.
  • Dedicated to build patterns & modular usages.
  • Build Solution with SolutionBuilder.

SubSolution is currently released as version v0. All core features are already implemented but it needs to be tested in more practical cases.

Also be aware of the following:

• Some small API breaking changes might happen until version v1.
• Some MSBuild project types are not supported yet. (Supported project types)

About MSBuild usage

SubSolution.MsBuild implements MsBuildProjectReader to read projects with MSBuild. But core MSBuild DLLs are not enough to read every project types because some dependencies are installed by Visual Studio modular setup. The MSBuild setup coming with .NET SDK also mostly support .NET projects only.

For that reason, SubSolution.MsBuild package does not come with MSBuild DLLs to let you choose between multiple strategies if you need a project reader:

1. Use Microsoft.Build.Locator to use existing MSBuild binaries on the user machine. For example, it can use MSBuild from a local Visual Studio or a .NET SDK install.
   • It is recommended to target a framework compatible with the MSBuild binaries you are trying to use in that case.
2. Use Microsoft.Build NuGet package to get only the core DLLs + set MsBuildProjectReader.ImportFallback to true to read project even on missing import/SDKs.
3. Implement your own IProjectReader if you don't want to depends on MSBuild.

Contribute

• Install .NET SDK
• Make a fork of the repo.
• Clone it locally (including submodules if you are using ReSharper in Visual Studio).
• Build the solution.
  • It will automatically install LinqToXsdCore to generate C# from the XML schema.
• Make your changes.
• Submit a pull request.