A Hitchhiker's Guide to MSBuild, the .NET SDK, and Everything

guide.md

A Hitchhiker's Guide to MSBuild, the .NET SDK, and Everything

Note

I am no longer actively updating this document.

Resources

Additional MSBuild SDKs

• Microsoft.Build.NoTargets for building a project that produces no assembly
• Microsoft.Build.CentralPackageVersions for managing package versions in a central file per solution.

Articles

• MSBuild well-known item metadata
• MSBuild reserved and well-known properties
• Common MSBuild project items
• NuGet pack and restore as MSBuild targets
• Design-time builds
• The ProjectReference Protocol
• MSBuild reference for .NET SDK projects
  • RuntimeIdentifier(s) and other publish properties
  • TargetFramework(s) and other framework properties
• Shipping a cross-platform MSBuild task in a NuGet package

Configuration

• Default command line params

Items

ProjectReference

• Private: When set to "false" the assembly is not copied to the output directory.

PackageReference

• GeneratePathProperty: Generates MSBuild Properties with the path to the package

ContentWithTargetPath

This item allows one to customize the path in the output directory.

<ContentWithTargetPath Update="Gui\Templates\**\*.*">
	<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
	<TargetPath>Templates\%(RecursiveDir)%(Filename)%(Extension)</TargetPath>
</ContentWithTargetPath>

InternalsVisibleTo

<ItemGroup>
	<InternalsVisibleTo Include="Example.Tests" />
</ItemGroup>

Tips and Tricks when using .msbuildproj

Error: The FrameworkReference 'NETStandard.Library' was not recognized

<PropertyGroup Condition="$(MSBuildProjectExtension) == '.msbuildproj'">
    <!-- This suppresses a build error that only happens in Visual Studio. See https://github.com/dotnet/sdk/issues/3329 -->
    <GenerateErrorForMissingTargetingPacks>false</GenerateErrorForMissingTargetingPacks>
</PropertyGroup>

Customizing dotnet run

dotnet run can be customized throught MSBuild by setting one or more of the following properties:

Property Name	Description	Default for .NET Core*
RunCommand	Overrides the commmand of the executed process.	dotnet.exe
RunArguments	Overrides all arguments passed to the exeuted process.	-
RunWorkingDirectory	Configures the working directory. Wins over StartWorkingDirectory	project directory
StartArguments	Appends to the arguments passed to the executed process.	"<AssemblyName>.dll"
StartWorkingDirectory	Configures the working directory.	-

* Varies depending on your settings. See Microsoft.NET.Sdk.targets

Use Case 1: Run something completely custom

Override both RunCommand and RunArguments:

<PropertyGroup>
	<RunCommand>echo</RunCommand>
	<RunArguments>&quot;Hello World&quot;</RunArguments>
</PropertyGroup>

Use Case 2: Add CLI arguments for your executable

Override StartArguments:

<PropertyGroup>
	<StartArguments>--logging-level Verbose</RunCommand>
</PropertyGroup>

Creating a Source Code Package

• Transforming source code and configuration files
• Using the contentFiles element for content files

Example csproj:

<!-- ... -->
<ItemGroup>
    <Content Include="Metadata\**\*.cs">
        <BuildAction>Compile</BuildAction>
    </Content>
</ItemGroup>
<!-- ... -->