In 17.8 we changed the defaults for Build Acceleration. We didn't update the docs to reflect that. This changes the guidance around configuring Build Acceleration, and steers the reader towards the validation steps.
Build Acceleration gathers items to copy from referenced files, transitively. Each copy item includes a relative path, to which the file should be copied (relative to the output path of the project being built).
It's possible for multiple projects to specify copy items with the same relative target path. When this occurs, only one file will end up in the output directory at that location. The exact rules defining which file "wins" in this case are complex. The situation is relatively rare however.
This change makes Build Acceleration disable itself in cases where duplicate relative target paths exist. The project will fall back to calling MSBuild so that the correct behaviour is guaranteed.
Some users will have the newer "unified settings" view. This change adds a screenshot of that view for such users.
We also reduce the size of the images on screen so they're not as huge as they were, especially now there are two of them.
We have a feature that disables Build Acceleration when certain NuGet packages are detected. This change adds the ability to set `EnableDefaultBuildAccelerationIncompatiblePackages` to `false` in order to disable this behaviour. This allows customers to more easily disable this default behaviour.
While rare, it's possible for a NuGet package to include `.props` and/or `.targets` files that customise the build in a way that's not compatible with Build Acceleration. Ideally such packages would also set `AccelerateBuildsInVisualStudio` to `false`, however that's not always an option.
To address this situation, this change introduces the ability to specify NuGet packages that, when present in a project, will disable Build Acceleration.
We add one known package (`Microsoft.VSSDK.BuildTools`, for VSIX projects) to our design-time `.targets` file, but SDKs and customers may add their own items too.
For example, if `MyPackage` is known to be incompatible with Build Acceleration, adding a `BuildAccelerationIncompatiblePackage` item to your `Directory.Build.props` will automatically cause Build Acceleration to be disabled for any project that references that `MyPackage`:
```xml
<Project>
<PropertyGroup>
<AccelerateBuildsInVisualStudio>true</AccelerateBuildsInVisualStudio>
</PropertyGroup>
<ItemGroup>
<BuildAccelerationIncompatiblePackage Include="MyPackage" />
</ItemGroup>
</Project>
```
When a project is found to have an incompatible project reference, the FUTDC log displays a message to that effect, such as:
> Build acceleration has been disabled for this project due to known incompatible NuGet package reference(s) 'Microsoft.VSSDK.BuildTools'. See https://aka.ms/vs-build-acceleration.
Build acceleration works best when all referenced projects produce a reference assembly each. We recently added a message highlighting when this was not the case, but didn't explain which project needed to be modified in order to fix this issue.
This change tracks and logs which projects need updating. The TargetPath is printed for those projects, which will generally also identify the target framework and so is therefore more helpful than just the .csproj file.
Build acceleration relies heavily upon the presence of reference assemblies. If a referenced project does not produce a reference assembly, we will be unable to accelerate the case where that referenced project had a private (non public-API) change.
This change introduces a log message when we detect this scenario, directing the user to consider a change that would improve their incremental build performance.
I just added a label for issues relating to build acceleration. This change adds a link to open issues with that label from our BA docs, to make it easier for folks to like and subscribe.
This adds an opt-in feature to have Visual Studio copy files directly during build, bypassing MSBuild when it appears safe to do so.
This can reduce build times considerably, especially in solutions with large project reference graphs.
See the included `docs/build-acceleration.md` file for details on the feature.
Drew Noakes