Skip to content

Commit 3a7d16e

Browse files
ghogenghogen
committed
Merging changes synced from https://github.com/MicrosoftDocs/visualstudio-docs-pr (branch live)
2 parents a070264 + 83a39d4 commit 3a7d16e

File tree

4 files changed

+88
-4
lines changed

4 files changed

+88
-4
lines changed

‎docs/msbuild/change-waves.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: Change waves
3+
description: Learn how to enable or disable features in MSBuild that are potentially disruptive.
4+
ms.date: 11/10/2020
5+
ms.topic: conceptual
6+
helpviewer_keywords:
7+
- Change waves [MSBuild]
8+
- MSBuildDisableFeaturesFromVersion environment variable
9+
author: ghogen
10+
ms.author: ghogen
11+
manager: jillfra
12+
monikerRange: ">=vs-2019"
13+
ms.workload:
14+
- multiple
15+
---
16+
# Change waves
17+
18+
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.
19+
20+
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](#change-waves-and-associated-features). Disabling a change wave also disables change waves of higher versions.
21+
22+
## Opt out of change wave features
23+
24+
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.
25+
26+
### MSBuildDisableFeaturesFromVersion Values
27+
28+
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:
29+
30+
| `MSBuildDisableFeaturesFromVersion` Value | Result | Receive Warning? |
31+
| :------------- | :---------- | :----------: |
32+
| Unset | Enable all change waves, meaning all features behind each change wave are enabled. | No |
33+
| Any valid and current change wave (for example, `16.8`) | Disable all features behind change wave `16.8` **and higher**. | No |
34+
| 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 |
35+
| 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 |
36+
| Invalid Format (for example, `16x8`, `17_0`, `garbage`) | Enable all change waves, meaning all features behind each change wave are enabled. | Yes |
37+
38+
## Change waves and associated features
39+
40+
The links in the list below go to the GitHub PR for the feature.
41+
42+
### 16.8
43+
44+
- [Enable NoWarn](https://github.com/dotnet/msbuild/pull/5671)
45+
- [Truncate Target/Task skipped log messages to 1024 chars](https://github.com/dotnet/msbuild/pull/5553)
46+
- [Don't expand full drive globs with false condition](https://github.com/dotnet/msbuild/pull/5669)
47+
48+
### 16.10
49+
50+
- [Error when a property expansion in a condition has whitespace](https://github.com/dotnet/msbuild/pull/5672)
51+
52+
### 17.0
53+
54+
There are no entries yet in this change wave.
55+
56+
## Change waves that are out of rotation
57+
58+
There are no out of rotation change waves at this time.
59+
60+
## FAQ
61+
62+
**Why target every other release for rotating change waves out?**
63+
64+
We believe this is enough time to have discussions with those affected and assist with adapting to the changes.
65+
66+
**Why an environment variable and not a project property?**
67+
68+
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.
69+
70+
**Why opt-out over opt-in?**
71+
72+
Opt-out is a better approach for us, otherwise we'd likely get limited feedback when a feature impacts customer builds.
73+
74+
## See also
75+
76+
- [MSBuild](msbuild.md)
77+
- [What's new in MSBuild 16](whats-new-msbuild-16-0.md)

‎docs/msbuild/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
href: whats-new-msbuild-16-0.md
99
- name: What's new in MSBuild 15.0
1010
href: what-s-new-in-msbuild-15-0.md
11+
- name: Change waves
12+
href: change-waves.md
1113
- name: MSBuild concepts
1214
items:
1315
- name: Overview

‎docs/msbuild/whats-new-msbuild-16-0.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,10 @@ MSBuild 16.0](https://github.com/microsoft/msbuild/releases/tag/v16.0.461.62831)
2828

2929
- `VisualStudioVersion` for this version of the tools is "16.0"
3030

31+
## Change waves
32+
33+
Starting with MSBuild 16.8, you can selectively choose whether to opt out of certain potentially disruptive changes in MSBuild. See [Change waves](change-waves.md).
34+
3135
## Updates
3236

3337
MSBuild (and Visual Studio) now targets .NET Framework 4.7.2. If you wish to use new MSBuild API features, your assembly must also upgrade, but existing code will continue to work.

‎docs/xml-tools/xslt-profiler.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,30 @@
22
title: XSLT performance
33
description: Learn about the XSLT Profiler in Visual Studio that creates detailed XSLT performance reports to help you optimize the performance of your XSLT code.
44
ms.custom: SEO-VS-2020
5-
ms.date: 03/05/2019
5+
ms.date: 11/11/2020
66
ms.topic: conceptual
77
ms.assetid: 87387c9a-2e89-4801-ad51-83740cd6ea25
88
author: TerryGLee
99
ms.author: tglee
1010
manager: jillfra
1111
ms.workload:
1212
- multiple
13+
monikerRange: vs-2017
1314
---
1415
# The XSLT Profiler
1516

1617
The XSLT Profiler creates detailed XSLT performance reports that help measure, evaluate, and target performance-related problems in XSLT code. The XSLT Profiler includes useful hints for XSL and XSLT style sheet optimizations. For XSLT applications that demand maximum performance, this tool can be essential.
1718

1819
The XSLT Profiler is part of Visual Studio and is available on the **XML** menu.
1920

20-
![XSLT Profiler](../xml-tools/media/profile-xslt-menu.png)
21+
![XSLT Profiler](../xml-tools/media/profile-xslt-menu.png "Screenshot of the XML menu items in Visual Studio 2017")
2122

2223
> [!NOTE]
23-
> The XSLT Profiler is only available in the Enterprise edition of Visual Studio.
24+
> The XSLT Profiler is only available in the Enterprise edition of Visual Studio 2017.
2425
2526
## Create a performance report
2627

27-
1. Open an XSLT document in Visual Studio.
28+
1. Open an XSLT document in Visual Studio 2017.
2829

2930
2. On the menu bar, choose **XML** > **Profile XSLT**.
3031

0 commit comments

Comments
 (0)