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

Example csproj:

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

bash/guide.md