Microsoft MSBuild Project SDKs

The Microsoft.Build.NoTargets MSBuild project SDK is designed for projects that do not need to compile an assembly. It is ideal for utility projects that perform tasks such as copying files, building packages, or running external tools. By using this SDK, you avoid the default compilation targets associated with standard SDKs like Microsoft.NET.Sdk.

<Project Sdk="Microsoft.Build.NoTargets">
  <!-- Project content here -->
</Project>

This repository provides several specialized MSBuild SDKs to extend build functionality:

• Microsoft.Build.Traversal: Creates traversal projects that indicate which projects to include in a build tree. These serve as high-performance replacements for Visual Studio solution files in large project trees.
• Microsoft.Build.NoTargets: Provides utility projects that do not compile an assembly.
• Microsoft.Build.Artifacts: Supports the staging of artifacts from build outputs.
• Microsoft.Build.CopyOnWrite: Enables Copy-on-Write on Windows Dev Drive and ReFS to accelerate file copy operations.
• Microsoft.Build.RunVSTest: Hooks VSTest into the Test target, enabling concurrent test execution during the build via msbuild /t:Build;Test.

The Microsoft.Build.CopyOnWrite SDK overrides the native MSBuild Copy task to support Copy on Write (CoW) operations. This minimizes actual file data duplication, accelerating builds in large repositories where many dependencies are copied.

Platform Support & Requirements:

• Windows: Requires a drive formatted with Dev Drive or ReFS. It is recommended to move your package cache to the same volume.
  • Note: On Windows 11 24H2 and Windows Server 2025, CoW support is built into the OS and is automatic for Dev Drive and ReFS volumes; this library is not required in those versions.
• Linux: CoW is automatically used starting in .NET 7.
• macOS: CoW is automatically used starting in .NET 8.

If you are not building on Windows, this library is generally not needed as the underlying runtimes handle CoW automatically.

MSBuild 15.0 introduced SDK-style projects. When you define a project with an Sdk attribute, MSBuild automatically performs implicit imports of Sdk.props at the beginning of the project evaluation and Sdk.targets at the end.

For example, a project defined as:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net46</TargetFramework>
  </PropertyGroup>
</Project>

Is expanded by MSBuild during evaluation to:

<Project Sdk="Microsoft.NET.Sdk">
  <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk" />

  <PropertyGroup>
    <TargetFramework>net46</TargetFramework>
  </PropertyGroup>

  <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk" />
</Project>

For packages that should be included in every project in the tree (e.g., build tools, analyzers, or versioning tools), use the GlobalPackageReference item in your Packages.props.

To ensure these are treated as development-only dependencies and do not leak into downstream consumers, use the following metadata:

1. IncludeAssets="Analyzers;Build": Limits usage to analyzers and build logic, preventing compile-time dependencies.
2. PrivateAssets="All": Prevents the reference from being picked up by downstream dependencies.

<!-- Packages.props -->
<Project>
  <ItemGroup>
    <GlobalPackageReference Include="Nerdbank.GitVersioning" Version="2.1.16" />
  </ItemGroup>
</Project>

To use the Microsoft.Build.Artifacts package in a standard .NET project, add it as a PackageReference in your project file. You must also define an ArtifactsPath property to specify where the staged artifacts should be placed. By default, the SDK attempts to stage contents from the project's $(OutputPath) to the location specified in $(ArtifactsPath).

Note: If you are using the .NET SDK's built-in artifacts functionality, the features of Microsoft.Build.Artifacts are disabled.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net46</TargetFramework>
    <ArtifactsPath>..\..\artifacts\MyApp</ArtifactsPath>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Build.Artifacts" Version="1.0.0" />
  </ItemGroup>
</Project>

The Microsoft.Build.RunVSTest SDK allows you to run tests directly from MSBuild, providing functionality similar to dotnet test. This SDK is primarily intended for users of msbuild.exe (the Visual Studio flavor of MSBuild).

You can install it using one of two methods:

1. Via Directory.Build.props: Add the SDK reference to your project configuration.
2. Via Directory.Packages.props: If your repository uses central package management, add it as a GlobalPackageReference.

<!-- Method 1: Directory.Build.props -->
<Sdk Name="Microsoft.Build.RunVSTest" Version="1.0.0" />

<!-- Method 2: Directory.Packages.props -->
<Project>
  <ItemGroup>
    <GlobalPackageReference Include="Microsoft.Build.RunVSTest" Version="1.0.0" />
  </ItemGroup>
</Project>

For large repositories already using Central Package Management (CPM), you can include the Microsoft.Build.CopyOnWrite SDK by adding it as a GlobalPackageReference in your Directory.Packages.props file. This ensures the optimized Copy task is available for all NuGet-based projects in the repository.

<Project>
  <ItemGroup>
    <!-- <PackageVersion> elements here -->
  </ItemGroup>
  <ItemGroup>
    <GlobalPackageReference Include="Microsoft.Build.CopyOnWrite" Version="1.0.0" />
  </ItemGroup>
</Project>

The SDK requires authentication to access Azure DevOps feeds.

1. Environment Variable (Recommended for CI): Use the UniversalPackagesPatVar property to specify the name of an environment variable that contains your Personal Access Token (PAT). This is necessary for non-interactive environments like CI/CD pipelines.
2. Interactive Authentication: By default, the SDK uses the Azure Artifacts Credential Provider to retrieve tokens. You can control this behavior with the UniversalPackagesInteractiveAuth property (defaults to true unless in a known CI environment).

Required Property:

• UniversalPackagesAccountName: Must be set to your Azure DevOps account name (e.g., if your URL is dev.azure.com/contoso, use contoso).

The Microsoft.Build.Traversal SDK allows you to create 'traversal projects' (typically named dirs.proj) that define a set of projects to be built. This is an alternative to Visual Studio solution files, making it better suited for large-scale build systems and hosted environments. You can include projects using wildcards for automatic discovery or explicit paths for precise control. Traversal projects can also reference other traversal projects to build entire directory trees from any level.

<Project Sdk="Microsoft.Build.Traversal">
  <ItemGroup>
    <!-- Build all projects recursively under the "src" folder -->
    <ProjectReference Include="src\**\*.*proj" />
  </ItemGroup>
</Project>