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

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
• Cache SDK resolver data process-wide

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

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.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
• Call new CultureInfo API when validating cultures (.NET Core only)

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

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

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