Solution Files¶

In the Suite, Solution Files (.sln) are used on the Developer's environment only, usually for Visual Studio or other editor tooling, or CLIs like dotnet.

For the continuos integration process, other methods are employed for building, which reference projects by path directly without depending on Solution Files.

This is a preferred method since Solution Files are quite big, messy, with-GUIDs text files.

This is one of the most common causes of conflicts that we've seen when working on the Suite monorepo.

Hence, we recommend development teams not to upload solution files to source control at all. Instead, we can upload a .tvproj file which contains globs patterns for referencing the required projects. This is quite useful: we no longer need to edit this file when we add, rename, or delete a project since we use expressions (like framework/**/*.csproj) to reference other projects.

In order to achieve this, two components are used together: the SlnGen tool and the Traversal SDK Project.

The Traversal SDK Project is an MSBuild SDK, that allows us to create an MSBuild project file that references other projects using glob patterns.

SlnGen is a .NET Tool that can generate a Solution File from a MSBuild project file. Do you see where this is going?

Teams Developing Services¶

Each Bounded Context includes a .tvproj file that we can use to generate a Solution File.

When creating a new Bounded Context using the provided templates, a ITsynch.Suite.[BoundedContextName].tvproj is created in the root of your Bounded Context with the following contents:

XML
<Project Sdk="Microsoft.Build.Traversal/3.0.3">

    <PropertyGroup>
        <IncludeInSolutionFile>false</IncludeInSolutionFile>
    </PropertyGroup>

    <ItemGroup>
        <ProjectReference Include="$(FrameworkPath)/**/*.*proj" />
        <ProjectReference Include="$(ModulesPath)/**/*.*proj" />
        <ProjectReference Include="$(RuntimePath)/**/*.*proj" />
        <ProjectReference Include="$(ServicesPath)Microservice/**/*.*proj" />
        <ProjectReference Include="$(TestsPath)services/Microservice/**/*.*proj" />

        <!--
            TODO: Add references to the .Application.Contracts of the Services
            you depend on. i.e
            <ProjectReference Include="$(ServicesPath)ITsynch.Suite.UsersProfile.Application.Contracts/ITsynch.Suite.UsersProfile.Application.Contracts.csproj" />
        -->
    </ItemGroup>
</Project>

The Solution that will be generated from that file will include all that's required to build a Service.

Skip to Running SlnGen to see how to create a Solution file from the .tvproj file.

Teams Developing Suite Framework / Modules¶

For the Suite Team, we have two project files that we can use to generate Solution Files:

dotnet/ITsynch.Suite.Framework.tvproj includes framework, modules, runtime, samples and templates. Basically everything except services. This is what we use to develop new modules / features.

Now, when we need to refactor / rename of any public API, we must use dotnet/ITsynch.Suite.tvproj to do so. This file includes everything! all Services are included. We can use this file to perform atomic refactors across the entire project.

You can use the ITsynch.Suite.tvproj for daily developing, however, when more projects are added to the monorepo, we believe this will be unfeasible.

Running SlnGen¶

The easiest way to run SlnGen is by using the dotnet/slngen.sh script. You can provide your .tvproj file as an argument.

Bash
cd dotnet
./slngen.sh src/services/DataSync/ITsynch.Suite.DataSync.tvproj

or

Bash
cd dotnet
./slngen.sh DataSync

Tip

For working on the Suite Framework, simply run ./slngen.sh without any arguments.

It will open VS2019 for you with a solution loaded with all projects that are required for development.

As we mentioned, we don't recommend uploading these files. We recommend all Teams to open Visual Studio by using the previous command.

Development Experience¶

Instead of opening VS2019, or the .sln file directly, we recommend teams get used to open VS2019 by running the slngen.sh command.

This will ensure that you always have a sln file up to date with the latest projects that the Suite or your Team have added.

Caveats¶

When pulling from dev, your previously generated solution may be outdated, hence you need to regenerate it.

You will see an error similar to:

Cannot restore MyProject.csproj, run dotnet restore or make sure you have added it to the solution file.