This project provides plugin implementations for the experimental MSBuild Project Cache, which enables project-level caching within MSBuild.

To enable caching, simply add a <PackageReference> for the desired cache implementation and set various properties to configure it.

For repos which build C# code, add a <PackageReference> to Microsoft.MSBuildCache.SharedCompilation for shared compilation support.

Here is an example if you're using NuGet's Central Package Management and Azure Pipelines:

Directory.Packages.props:

  <PropertyGroup>
    <!-- In Azure pipelines, use Pipeline Caching as the cache storage backend. Otherwise, use the local cache. -->
    <MSBuildCachePackageName Condition="'$(TF_BUILD)' != ''">Microsoft.MSBuildCache.AzurePipelines</MSBuildCachePackageName>
    <MSBuildCachePackageName Condition="'$(MSBuildCachePackageName)' == ''">Microsoft.MSBuildCache.Local</MSBuildCachePackageName>

    <!-- Replace this with the latest version -->
    <MSBuildCachePackageVersion>...</MSBuildCachePackageVersion>
  </PropertyGroup>
  <ItemGroup>
    <GlobalPackageReference Include="$(MSBuildCachePackageName)" Version="$(MSBuildCachePackageVersion)" />
    <GlobalPackageReference Include="Microsoft.MSBuildCache.SharedCompilation" Version="$(MSBuildCachePackageVersion)" />
  </ItemGroup>

For repos using C++, you will need to add the projects to a packages.config and import the props/targets files directly.

Directory.Build.props:

  <PropertyGroup>
    <PackagesConfigFile>packages.config</PackagesConfigFile>
    <PackagesConfigContents>$([System.IO.File]::ReadAllText("$(PackagesConfigFile)"))</PackagesConfigContents>
    <MSBuildCachePackageVersion>$([System.Text.RegularExpressions.Regex]::Match($(PackagesConfigContents), 'Microsoft.MSBuildCache.*?version="(.*?)"').Groups[1].Value)</MSBuildCachePackageVersion>
    <MSBuildCachePackageRoot>$(NugetPackageDirectory)\$(MSBuildCachePackageName).$(MSBuildCachePackageVersion)</MSBuildCachePackageRoot>
  </PropertyGroup>
  <Import Project="$(MSBuildCachePackageRoot)\build\$(MSBuildCachePackageName).props" />

Directory.Build.targets:

  <Import Project="$(MSBuildCachePackageRoot)\build\$(MSBuildCachePackageName).targets" />

These settings are common across all plugins, although different implementations may ignore or handle them differently. Refer to the specific plugin documentation for details.

When configuring settings which are list types, you should always append to the existing value to avoid overriding the defaults:

<PropertyGroup>
  <MSBuildCacheIdenticalDuplicateOutputPatterns>$(MSBuildCacheIdenticalDuplicateOutputPatterns);**\foo.txt</MSBuildCacheIdenticalDuplicateOutputPatterns>
</PropertyGroup>

This implementation uses Azure Pipeline Caching as the cache storage, which is ideal for repos using Azure Pipelines for their builds.

Please refer to the cache isolation and security pipeline caching provides to understand the security around this cache implementation.

It is expected that this plugin is used within an Azure Pipeline. The SYSTEM_ACCESSTOKEN environment variable will need to be explicitly passed to the task calling MSBuild since it's considered a secret. In classic pipelines this is done by checking "Allow scripts to access the OAuth token" in the job. In yml pipelines, this is done by passing the env var explicitly using the $(System.AccessToken) variable:

- script: MSBuild /graph /restore /reportfileaccesses /bl:$(Build.ArtifactStagingDirectory)\Logs\msbuild.binlog /p:Configuration=Release
  displayName: Build
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

For the access token to have scopes relevant to Pipeline Caching, the Cache task must be used in the pipeline. There is work planned to opt-into this explicitly, but using the task is currently the workaround. You can cache a dummy folder if there is no otherwise reasonable use of the task in your build.

- task: Cache@2
  displayName: Enable Pipeline Caching
  inputs:
    key: '"dummy"'
    path: build

This implementation uses the local file system for the cache. In particular, it uses BuildXL's LocalCache. This is recommended for locally testing and debugging caching for your repo.

This implementation uses Azure Blob Storage as the cache storage.

The connection string to the blob storage account must be provided in the MSBUILDCACHE_CONNECTIONSTRING environment variable. This connection string needs both read and write access to the resource.

This package enables accurate file access reporting for the Roslyn Compiler Server. Because the compiler server (vbcscompiler) launches as a detached process, its file accesses are not observed by MSBuild. This package manually reports these files accesses to the plugin.

In the future, this feature will be directly supported by Roslyn, at which point this package will no longer be needed.

This package contains much of the shared logic for the plugins, including handling file accesses and cache fingerprinting. For those wanting to use a different cache backend than the ones associated with the available plugins, referencing this package can be a good option to avoid having to duplicate the rest of the logic involved with caching.

See CONTRIBUTING.md

Microsoft.MSBuildCache is licensed under the MIT license.

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.