Change waves

A change wave is a set of behavior changes in MSBuild that you can opt out of by specifying a particular flag as an environment variable. The purpose of this is to warn you of potentially disruptive changes so that you have flexibility in adapting to these changes before they become standard functionality. All the features in a specific change wave can only be enabled or disabled together, not individually.

When you upgrade to a new version of MSBuild, changes that are potentially breaking are enabled by default, but if a feature affects your build negatively, you can easily disable that wave of changes. Each change wave is identified by an MSBuild version number (for example, 16.8), but setting the change wave only controls certain features that have the potential to affect the build process, not all the changes in that MSBuild version. A list of the features in each change wave appears later in this article. Disabling a change wave also disables change waves of higher versions.

Opt out of change wave features

To disable the features in a change wave, set the environment variable MSBuildDisableFeaturesFromVersion to the change wave (or MSBuild version) that contains the feature you want disabled. This is the version of MSBuild that the features were developed for. See the mapping of change waves to features below.

MSBuildDisableFeaturesFromVersion Values

You will receive a warning and/or default to a specific wave if you don't set MSBuildDisableFeaturesFromVersion to a valid change wave. The following table shows the possible settings:

MSBuildDisableFeaturesFromVersion Value	Result	Receive Warning?
Unset	Enable all change waves, meaning all features behind each change wave are enabled.	No
Any valid and current change wave (for example, 16.8)	Disable all features behind change wave 16.8 and higher.	No
Invalid Value (for example, 16.9 when valid waves are 16.8 and 16.10)	Default to the closest valid value (ascending). For example, setting 16.9 will default you to 16.10.	No
Out of Rotation (for example, 17.1 when the highest wave is 17.0)	Clamp to the closest valid value. For example, 17.1 clamps to 17.0, and 16.5 clamps to 16.8	Yes
Invalid Format (for example, 16x8, 17_0, garbage)	Enable all change waves, meaning all features behind each change wave are enabled.	Yes

Change waves and associated features

Current Rotation of Change Waves

18.8

• RAR task: across multiple input properties, resolve relative paths against the project directory (not the process current directory)

18.7

• Copy task retries on ERROR_ACCESS_DENIED on non-Windows platforms to handle transient lock conflicts (e.g. macOS CoW filesystems)
• Fix ASP.NET WebSite projects to resolve netstandard2.0 dependencies - Pass TargetFrameworkVersion to RAR task and copy netstandard.dll facade for .NET Framework 4.7.1+ web projects.

18.6

• AbsolutePath.GetCanonicalForm optimization - avoid expensive Path.GetFullPath calls when paths don't need canonicalization
• TaskHostTask forwards request-level global properties (e.g. MSBuildRestoreSessionId) to out-of-proc TaskHost in -mt mode
• Fix ShouldTreatWarningAsError in OOP TaskHost checking wrong collection (WarningsAsMessages instead of WarningsAsErrors)
• Fix ToolTask hang when tool spawns grandchild processes that inherit stdout/stderr pipe handles

18.5

• FindUnderPath and AssignTargetPath tasks no longer throw on invalid path characters when using TaskEnvironment.GetAbsolutePath
• AssignTargetPath on Linux respects case sensitivity of the file system instead of always ignoring case

18.4

• Start throwing on null or empty paths in MultiProcess and MultiThreaded Task Environment Drivers.

Change waves that will be removed in the release accompanying .NET 11

18.3

• Replace Transactional property with ChangeWave control, implement atomic file replacement with retry logic, and update tests.

17.14

• ~.SLNX support - use the new parser for .sln and .slnx~ reverted after compat problems discovered
• Support custom culture in RAR - see 11607 for details
• VS Telemetry

17.12

• Log TaskParameterEvent for scalar parameters
• Convert.ToString during a property evaluation uses the InvariantCulture for all types
• Fix oversharing of build results in ResultsCache
• Add ParameterName and PropertyName to TaskParameterEventArgs
• Emit eval props if requested by any sink
• Load Microsoft.DotNet.MSBuildSdkResolver into default load context (MSBuild.exe only)

17.10

• AppDomain configuration is serialized without using BinFmt - feature can be opted out only if BinaryFormatter is allowed at runtime by editing MSBuild.runtimeconfig.json. Please note that any usage of BinaryFormatter is insecure.
• Warning on serialization custom events by default in .NET framework
• Cache SDK resolver data process-wide
• Target parameters will be unquoted, meaning the ';' symbol in the parameter target name will always be treated as separator
• Add Link metadata to Resources in AssignLinkMetadata target
• Change Version switch output to finish with a newline
• Load NuGet.Frameworks into secondary AppDomain (MSBuild.exe only)
• Update Traits when environment has been changed
• Exec task does not trim leading whitespaces for ConsoleOutput
• Introduce [MSBuild]::StableStringHash overloads
• Keep the encoding of standard output & error consistent with the console code page for ToolTask

Change Waves No Longer In Rotation

16.8

• Enable NoWarn
• Truncate Target/Task skipped log messages to 1024 chars
• Don't expand full drive globs with false condition

16.10

• Error when a property expansion in a condition has whitespace
• Allow Custom CopyToOutputDirectory Location With TargetPath
• Allow users that have certain special characters in their username to build successfully when using exec
• Fail restore operations when an SDK is unresolveable
• Optimize glob evaluation

17.0

• Scheduler should honor BuildParameters.DisableInprocNode
• Don't compile globbing regexes on .NET Framework
• Default to transitively copying content items
• Reference assemblies are now no longer placed in the bin directory by default (reverted here and brought back here)
• Improve debugging experience: add global switch MSBuildDebugEngine; Inject binary logger from BuildManager; print static graph as .dot file
• Fix deadlock in BuildManager vs LoggingService
• Optimize diag level for file logger and console logger
• Optimized immutable files up to date checks
• Add Microsoft.IO.Redist for directory enumeration
• Process-wide caching of ToolsetConfigurationSection
• Normalize RAR output paths

17.4

• Respect deps.json when loading assemblies
• Consider Platform as default during Platform Negotiation
• Adding accepted SDK name match pattern to SDK manifests
• Throw warning indicating invalid project types
• MSBuild server

17.6

• Parse invalid property under target
• Eliminate project string cache
• Log an error when no provided search path for an import exists
• Log assembly loads
• AnyHaveMetadataValue returns false when passed an empty list
• Log item self-expansion

17.8

• [RAR] Don't do I/O on SDK-provided references
• Delete destination file before copy
• Moving from SHA1 to SHA256 for Hash task
• Deprecating custom derived BuildEventArgs - feature can be opted out only if BinaryFormatter is allowed at runtime by editing MSBuild.runtimeconfig.json

FAQ

Why target every other release for rotating change waves out?

We believe this is enough time to have discussions with those affected and assist with adapting to the changes.

Why an environment variable and not a project property?

There are scenarios where we want to place a feature under a change wave before MSBuild has loaded the project. For that reason, change waves require using environment variables.

Why opt-out over opt-in?

Opt-out is a better approach for us, otherwise we'd likely get limited feedback when a feature impacts customer builds.

Related content

• MSBuild
• What's new in MSBuild 16