An example repository demonstrating best practices for structuring and managing .NET projects. This can be used as a template when starting a new project/repository.
Goals:
- Project files are small and simple enough to hand-edit
- Code analysis (.NET Analyzers and StyleCop) automatically enabled for all projects
- All common project properties managed in one location
- New projects automatically inherit all common project properties
- Projects support Dotnet CLI
The repository should contain the following general structure.
.
|-- docs/
| |-- Setup.md
|-- build/
| |-- build.sh
|-- dist/
|-- src/
| |-- Example/
| | |-- Example.csproj
| | |-- Program.cs
| |-- Example.Library/
| | |-- Example.Library.csproj
| | |-- Foo.cs
| |-- Example.Library.UnitTests/
| | |-- Example.Library.UnitTests.csproj
| | |-- FooTests.cs
| |-- .editorconfig
| |-- .globalconfig
| |-- Common.Product.props
| |-- Common.Tests.props
| |-- Directory.Build.props
| |-- Example.slnx
|-- test/
|-- .gitignore
|-- LICENSE.txt
|-- README.md
|-- version.json
- docs/
- Setup document for building and publishing the application
- Contains any other project documentation
- build/
- Contains build and publishing scripts
- dist/
- Contains the build output
- This directory is ignored by Git
- src/
- Contains the main source code solution and projects
- Includes unit test projects
- test/
- Contains integration/acceptance test solutions and projects
- This does not contain unit tests
- This example repository does not demonstrate integration tests
- .gitattributes
- Specifies Git attributes per path
- .gitignore
- Specifies intentionally untracked files to ignore in Git (build output, etc.)
- LICENSE.txt
- Contains the project license information
- README.md
- You are reading it right now
- Contains information on the project/repository
- Written in Markdown
- version.json
- Application version configuration (more details below)
More details on the structure and files below.
All projects in the sample use the new SDK-style project format. SDK-Style projects have several advantages over the traditional csproj files:
- Very lightweight compared to traditional csproj files
- Package references are simplified
- All files in the project directory are automatically included
- Only files to be excluded are defined in the project file
- Supports all .NET framework types/versions:
- .NET Core
- .NET Standard
- .NET Framework
- Supports Dotnet CLI
- MSBuild is supported with these project files as well
- Assembly information contained directly in the project files
- AssemblyInfo.cs is not required (in most cases)
- Easy to generate NuGet packages
- .Nuspec files are not required (in most cases)
- No custom unit test targets required
All projects automatically import Directory.Build.props, which sets all common project properties:
- Common meta-data (imported through
Common.Product.props):- Company name
- Author
- Copyright
- Target framework version
- Enables .NET Analyzers and StyleCop
- Enforces code style on build
- Sets the build version (more details below)
- Enables 'Treat warnings' as errors
- Allows unit test projects access to internals
All unit tests projects also automatically import Common.UnitTests.props, which sets all common unit test project properties:
- Includes the appropriate MSTest packages
- Includes the Coverlet package to report on code coverage
- Enables the project to be run with
donet test(more details below)
Having all common properties automatically imported reduces the chance of creating new projects with incorrect settings.
With all common properties defined in Directory.Build.props and automatically imported,
new project files only containing information specific to that project.
When creating a new project file only a few things need to be added/set:
- Project and package references
- Output type (if not a class library)
- Package meta-data (more on this below)
- Etc.
As shown by the following example this is now quite easy to do by hand:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\Example.Library\Example.Library.csproj" />
</ItemGroup>
</Project>Dotnet CLI can also be used to create the initial project file:
dotnet new classlib -n ProjectNameVisual Studio can still be used to update project settings, packages and references.
Git Versioning is used to version the assemblies on build.
By default, the major and minor versions are configured in version.json, and the patch version is automatically bumped on each commit.
This setup makes it easier to follow Semantic Versioning and to have a unique version for every build.
All projects have both .NET Analyzers and StyleCop enabled.
This ensures static code analysis gets run on every build and all code follows the same style guidelines. The rules can be tweaked in the .globalconfig file under the src directory.
The .editorconfig file enforces consistent formatting, regardless of the Visual Studio settings.
This allows files to be auto-formatted in Visual Studio to comply with StyleCop.
Install the prerequisites covered here.
Below covers the commands to build, test, and publish with Dotnet CLI. These commands can be used from your CI/CD platform.
All commands are assumed to be run from the root of the repository.
To build the solution with Dotnet CLI:
dotnet build src/Example.slnxNote that dotnet build will automatically restore packages.
To run all unit tests in the solution with Dotnet CLI:
dotnet test src/Example.slnxA code coverage report can be generated with Coverlet with the following options:
rm -rf dist/Coverage
dotnet test src/Example.slnx --collect "XPlat Code Coverage" --results-directory "dist/Coverage" --settings "coverlet.runsettings"This generates a Cobertura report (XML) for each project. These reports can be integrated with your CI/CD platform or used with external tools.
To generate an HTML report with ReportGenerator:
reportgenerator -reports:"dist/Coverage/*/*.xml" -targetdir:"dist/Coverage" -reporttypes:HtmlSummary -title:"Unit Test Coverage"NuGet packages can be generated and published with DotNet CLI directly from the project files.
Custom targets using nuget.exe and .nuspec files are not required for most packages.
To allow a project to be packaged set IsPackable to true in the project settings.
If all projects in the solution are to be packaged this can be set in Directory.Build.props.
All other meta-data for the package will come from the common properties as well, except for the package description, which is generally project-specific.
Project settings:
<PropertyGroup>
<IsPackable>true</IsPackable>
<Description>Example package description</Description>
</PropertyGroup>To build the packages for the solution with Dotnet CLI:
dotnet pack src/Example.slnx -o "dist/Packages"dotnet nuget push can then be used to publish the packages to the desired server.
See the following links for additional details:
To publish an official build with Dotnet CLI:
dotnet publish src/Example/Example.csproj -o "dist/Publish"The publish command also has options for including .NET runtime dependencies and publishing as a single executable.
A sample build script is available in the build directory that encapsulates all of the above commands:
- Builds
- Runs unit tests
- Generates a test coverage report
- Creates NuGet packages
- Publishes the build
The script is a Bash script for better cross-platform compatibility. These commands/script(s) can be integrated into your CI/CD platform of choice.
To run the script open Git BASH prompt and run the following commands:
cd build
./build.shAfter running the script the published build, packages, and reports can be found in the dist folder.
After cloning the template, update the following for your project:
- Update the author, copyright, and product information in
Common.Product.props - Rename the solution and project files
- Update the build script for the project renames
- Update Visual Studio Code launch settings and tasks
- Update this README
- ???
- Profit!