MSBuild ArtifactsPath

Setting up an out-of-source build with MSBuild and the .NET SDK

A really cool but not well-known feature of the .NET SDK is the ArtifactsPath property. It allows you to specify a single directory into which all build artifacts from all projects will be placed: Binaries, Intermediates, NuGet packages, etc.

This is especially useful in CI/CD environments, where you might want to keep all build artifacts in a dedicated temporary directory to make use of your CI runners built-in cleanup, caching, and publishing features.

It is also a nice feature for local development, as you can keep your project directories clean, remove local artifacts from all projects at once and easily find local build outputs while maintaining a short .gitignore.

Usage

All you need to do to place all created artifacts into subfolders of ./artifacts is to set the ArtifactsPath MSBuild property:

<!-- Directory.Build.props -->
<Project>
  <PropertyGroup>
    <ArtifactsPath>$(MSBuildThisFileDirectory)artifacts</ArtifactsPath>
  </PropertyGroup>
</Project>

It is a good idea to set this property in a Directory.Build.props file in the root of your repository, so that it automatically applies to all projects when building locally.

In a CI/CD environment, you can then override this default with a command line argument. Example for an Azure DevOps pipeline:

- task: DotNetCoreCLI@2
  inputs:
    command: 'build'
    projects: 'Solution.sln'
    arguments: '--property:ArtifactsPath=$(Build.ArtifactStagingDirectory)\artifacts'

Or a simple command line call:

dotnet build Solution.sln --property:ArtifactsPath=artifacts

Default Paths

Setting a custom ArtifactsPath sets off an override cascade by the .NET SDK regarding output paths:

$(OutputPath)

Folder where the binaries for a project will be placed. Aka the bin directory.
Default: $(ArtifactsPath)\bin\$(MSBuildProjectName)\$(ArtifactsPivots)\

$(IntermediateOutputPath)

Folder used to place intermediate artifacts, such as temporary .props generated by the restore process or the compilers direct outputs. Aka the obj directory.
Default: $(ArtifactsPath)\obj\$(MSBuildProjectName)\$(ArtifactsPivots)\

$(PublishDir)

Folder where a published artifact will be placed, generated by dotnet publish.
Default: $(ArtifactsPath)\publish\$(MSBuildProjectName)\$(ArtifactsPivots)\

$(PackageOutputPath)

Folder where .nupkg files will be placed, generated by dotnet pack.
Default: $(ArtifactsPath)\package\$(Configuration)\

The $(ArtifactsPivots) variable is a placeholder for projects that feature multiple build variants. At the minimum, it will contain the $(Configuration), while the _$(RuntimeIdentifier) and _$(TargetFramework) suffixes will be added if necessary (for example when TargetFrameworks is configured).

There are many more knobs that you can turn, such as omitting the project name from the paths by setting the IncludeProjectNameInArtifactsPaths property. Most of these features can be found in the Microsoft.Common.CurrentVersion.targets file provided by the .NET SDK.

A simpler way of adjusting the paths is by setting them directly in the project file or the Directory.Build.props file: The .NET SDK will respect any value that you set.

However, note that overriding these properties might lead to unexpected consequences, so I don’t recommend diverging from these defaults unless necessary. I especially recommend against setting a single OutputPath for multiple projects, as this will lead to sporadic conflicts without careful management.

Example

Let’s look at a simple example involving a C# class library, console project, and XUnit test project:

# Setup ArtifactsPath
echo "<Project>
  <PropertyGroup>
    <ArtifactsPath>\$(MSBuildThisFileDirectory)artifacts</ArtifactsPath>
  </PropertyGroup>
</Project>" >> Directory.Build.props

# Create Projects
dotnet new classlib --name Sample.Library --output Sample.Library 
dotnet new xunit --name Sample.Tests --output Sample.Tests 
dotnet new console --name Sample.App --output Sample.App 

# Add References 
dotnet add Sample.App reference Sample.Library
dotnet add Sample.Tests reference Sample.Library

# Create Solution
dotnet new sln --name Sample
dotnet sln add Sample.Library/Sample.Library.csproj
dotnet sln add Sample.Tests/Sample.Tests.csproj
dotnet sln add Sample.App/Sample.App.csproj

# Build Solution
dotnet build Sample.sln

The resulting directory structure will look like this (files omitted for brevity):

.
├── Sample.App/
├── Sample.Library/
├── Sample.Tests/
└── artifacts/
    ├── bin/
    │   ├── Sample.App/
    │   │   └── debug/
    │   ├── Sample.Library/
    │   │   └── debug/
    │   └── Sample.Tests/
    │       └── debug/
    └── obj/
        ├── Sample.App/
        │   └── debug/
        │       ├── ref/
        │       └── refint/
        ├── Sample.Library/
        │   └── debug/
        │       ├── ref/
        │       └── refint/
        └── Sample.Tests/
            └── debug/
                ├── ref/
                └── refint/

The structure would, of course, look a bit different if we built the solution in release mode, published the projects, created NuGet packages or similar, as explained in Default Paths.

Also note that this sample was created with the .NET SDK version 9.0.100, the behavior might differ in prior or future versions.

More Information

If you would like to learn more about the ArtifactsPath property, you can consult the official documentation on the MS Docs. A more powerful, albeit more technical, way to discover your possibilities is by analyzing a binary log of your build using the Structured Log Viewer.