Skip to content

About

An example repository showing best practices for structuring and managing .NET solutions.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

59 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

.NET Template Project

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:

  1. Project files are small and simple enough to hand-edit
  2. Code analysis (.NET Analyzers and StyleCop) automatically enabled for all projects
  3. All common project properties managed in one location
  4. New projects automatically inherit all common project properties
  5. Projects support Dotnet CLI

Repository Structure

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

Root Directory

  • 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.

Project Files

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

Common Properties

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.

Creating New Projects

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 ProjectName

Visual Studio can still be used to update project settings, packages and references.

Versioning

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.

Code Style and Analysis

Code Analysis

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.

Code Formatting

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.

Build and Publish

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.

Building

To build the solution with Dotnet CLI:

dotnet build src/Example.slnx

Note that dotnet build will automatically restore packages.

Unit Tests

To run all unit tests in the solution with Dotnet CLI:

dotnet test src/Example.slnx

Test Coverage

A 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

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:

Publish Build

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.

Sample Build Script

A sample build script is available in the build directory that encapsulates all of the above commands:

  1. Builds
  2. Runs unit tests
  3. Generates a test coverage report
  4. Creates NuGet packages
  5. 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.sh

After running the script the published build, packages, and reports can be found in the dist folder.

After Cloning the Template

After cloning the template, update the following for your project:

  1. Update the author, copyright, and product information in Common.Product.props
  2. Rename the solution and project files
  3. Update the build script for the project renames
  4. Update Visual Studio Code launch settings and tasks
  5. Update this README
  6. ???
  7. Profit!

About

An example repository showing best practices for structuring and managing .NET solutions.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages