MartinCostello.BuildKit 🛠️

Introduction

A NuGet package containing reusable MSBuild properties, items and targets for building and deploying my other .NET projects.

The functionality provided is very opinionated, even though it provides the ability to customize the build process.

As such, is not intended to be used by people other than myself - but you're welcome to take inspiration from it!

Installation

To install the NuGet package, it is recommended to use a global package reference in your Directory.Packages.props file as shown below:

<Project>
  <ItemGroup>
    <GlobalPackageReference Include="MartinCostello.BuildKit" Version="0.2.1" />
  </ItemGroup>
</Project>

Features

At a high-level, the package provides the following features:

• Configures warnings as errors
• Configures .NET and code style analysis
• Enables C# implicit using statements and nullable reference types
• Configures reproducible builds
• Simplifies the configuration of strong naming
• Adds more default global using statements
• Embeds additional Git metadata in assemblies
• Installs/restores npm packages
• Configures versions plus container and package metadata for builds that take place in GitHub Actions
• Configures code coverage using when using VSTest (with Coverlet) or Microsoft.Testing.Platform
• Generate code coverage reports using ReportGenerator
• Assumes the use of artifacts output
• Enable the Pyroscope profiler in Linux containers

MSBuild Documentation

A summary of the MSBuild properties, items and targets provided by the package is provided below.

For more detailed information, consult the .props and .targets files here.

Properties

The following custom properties are provided to control behaviour.

It is recommended to set these values in Directory.Build.props (or the .csproj file of a single project).

Property	Default Value	Description
AssemblyIsCLSCompliant	true (false for test projects)	Emits the [CLSCompliant] attribute with the specified value
CoverageFormat	cobertura	The coverage output format to use with Microsoft.Testing.Platform
CoverageOutput	artifacts/coverage/{project}/coverage.xml	The coverage output file to use with Microsoft.Testing.Platform
CoverageOutputPath	artifacts/coverage	The path to write code coverage results to
CoverageRunSettings	-	The path to the .runsettings file to use with Microsoft.Testing.Platform
GenerateGitMetadata	true	Whether to embed additional [AssemblyMetadata] for Git projects
TestResultsDirectory	artifacts/tests	The path to write test logs to with Microsoft.Testing.Platform
UseDefaultAssemblyOriginatorKeyFile	false	Whether to use the built-in .snk file
UseDefaultCodeAnalysisRuleSet	false	Whether to use the built-in .ruleset file
UseDefaultTestRunSettings	true	Whether to use the built-in .runsettings file with Microsoft.Testing.Platform
UsePyroscope	false	Whether to enable Pyroscope for container applications
UseSentry	true	Whether to enable Sentry for container applications during publishing (requires SentryAuthToken to be specified)

The following properties are made available for use in the build process:

Property	Description
DynamicProxyGenAssembly2StrongNamePublicKey	The public key to use with [InternalsVisibleTo] for DynamicProxyGenAssembly2 when using NSubstitute or Moq
GitHubBranchName	The name of the current Git branch when not a pull request
GitHubPullRequest	The number of the pull request that triggered the current build, if any
GitHubRepositoryName	The name of the GitHub repository
GitHubRepositoryOwner	The owner of the GitHub repository
GitHubRepositoryUrl	The URL of the GitHub repository
GitHubTag	The value of the tag that triggered the current build, if any
IsGitHubActions	Set to true when running in GitHub Actions
IsGitHubPullRequest	Whether the current build was triggered by a pull request
IsGitHubTag	Whether the current build was triggered by a tag
PyroscopeApplicationName	The name of the application to profile with Pyroscope
StrongNamePublicKey	When UseDefaultAssemblyOriginatorKeyFile=true contains the public key for the .snk file

Items

The following custom items are provided:

Property	Defaults	Description
CoverletExclude	Tests and xunit	Patterns to exclude from code coverage when using Coverlet (ensure values are escaped)
CoverletExcludeByAttribute	GeneratedCodeAttribute	Patterns for attributes to exclude from code coverage when using Coverlet
CoverletExcludeByFile	artifacts/obj/**/*	Patterns for files to exclude from code coverage when using Coverlet (ensure values are escaped)
CoverletInclude	-	Patterns to include in code coverage when using Coverlet (ensure values are escaped)
CoverletOutputFormats	cobertura and json	The output formats to use with Coverlet
PyroscopeLabels	-	Labels to use with Pyroscope when profiling applications
ReportGeneratorReportTypes	HTML	The report types to generate with ReportGenerator
TestingPlatformIgnoreExitCodes	8	Exit codes to ignore as failures when running tests with Microsoft.Testing.Platform
Using	System.Globalization and System.Text	Additional global using statements

Targets

The following custom targets are provided:

Target	Description
AddGitHubMetadataAssemblyAttributes	Embeds additional [AssemblyMetadata] into assemblies with Git and GitHub information
CheckCodeCoverageThreshold	Checks the code coverage of a project meets a specified line and/or branch threshold when using Microsoft.Testing.Platform
GenerateCoverageReports	Generates code coverage reports using ReportGenerator
RestoreNpmPackages	Runs npm install/npm ci if node_modules does not exist when a package.json file is found in a project
SetGitHubContainerOutputs	Writes a published container's digest, image and tag to GITHUB_OUTPUT
SetNuGetPackageOutputs	Writes the comma-separated names and version of any published NuGet packages to GITHUB_OUTPUT

Building and Testing

Compiling the package yourself requires Git and the .NET SDK to be installed.

To build and test the package locally from a terminal/command-line, run the following set of commands:

git clone https://github.com/martincostello/build-kit.git
cd build-kit
./build.ps1

Feedback

Any feedback or issues can be added to the issues for this project in GitHub.

Repository

The repository is hosted in GitHub: https://github.com/martincostello/build-kit.git

License

This project is licensed under the Apache 2.0 license.