Repo sync for protected CLA branch

docs/build/how-to-integrate-custom-tools-into-the-project-properties.md

@@ -1,32 +1,50 @@
 ---
 title: "How to: Integrate Custom Tools into the Project Properties"
-ms.date: "05/16/2019"
-helpviewer_keywords: ["msbuild (c++), howto: integrate custom tools"]
-ms.assetid: f32d91a4-44e9-4de3-aa9a-1c7f709ad2ee
+description: "How to integrate custom tools into the Project Properties in Visual Studio C++ projects."
+ms.date: 10/08/2020
+helpviewer_keywords: ["MSBuild (C++), howto: integrate custom tools"]
 ---
 # How to: Integrate Custom Tools into the Project Properties
 
-You can add custom tool options to the Visual Studio **Property Pages** window by creating an underlying XML schema file.
+You can add custom tool options to the Visual Studio **Property Pages** window by creating an XML file.
 
-The **Configuration Properties** section of the **Property Pages** window displays setting groups that are known as *rules*. Every rule contains the settings for a tool or a group of features. For example, the **Linker** rule contains the settings for the linker tool. The settings in a rule can be subdivided into *categories*.
+The **Configuration Properties** section of the **Property Pages** window displays setting groups known as *rules*. Every rule contains the settings for a tool or a group of features. For example, the **Linker** rule contains the settings for the linker tool. The settings in a rule can be subdivided into *categories*.
 
-This document explains how to create a file in a set directory that contains properties for your custom tool so that the properties are loaded when Visual Studio starts. For information about how to modify the file, see [Platform Extensibilty Part 2](/archive/blogs/vsproject/platform-extensibility-part-2) on the Visual Studio Project Team blog.
+You can create a rule file that contains properties for your custom tool so that the properties are loaded when Visual Studio starts. For information about how to modify the file, see [Platform Extensibility Part 2](/archive/blogs/vsproject/platform-extensibility-part-2) on the Visual Studio Project Team blog.
+
+::: moniker range="vs-2015"
+
+The folder to place your rule file in depends on the locale and the version of Visual Studio in use. In a Visual Studio 2015 or earlier developer command prompt, the rules folder is *`%ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>`*. The `<version>` value is *`v140`* in Visual Studio 2015. The `<locale>` is an LCID, for example, `1033` for English. You'll use a different path for each edition of Visual Studio that's installed, and for each language. For example, the default rules folder path for Visual Studio 2015 Community edition in English could be *`C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\v140\1033\`*.
+
+::: moniker-end
+
+::: moniker range="vs-2017"
+
+The folder to place your rule file in depends on the locale and the version of Visual Studio in use. In a Visual Studio 2017 developer command prompt, the rules folder is *`%VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\`*. The `<locale>` is an LCID, for example, `1033` for English. In a Visual Studio 2015 or earlier developer command prompt, the rules folder is *`%ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\`*, where the `<version>` value is *`v140`* in Visual Studio 2015. You'll use a different path for each edition of Visual Studio that's installed, and for each language. For example, the default rules folder path for Visual Studio 2017 Community edition in English could be *`C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\VC\VCTargets\1033\`*.
+
+::: moniker-end
+
+::: moniker range=">=vs-2019"
+
+The folder to place your rule file in depends on the locale and the version of Visual Studio in use. In a Visual Studio 2019 or later developer command prompt, the rules folder is *`%VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\`*, where the `<version>` value is *`v160`* in Visual Studio 2019. The `<locale>` is an LCID, for example, `1033` for English. In Visual Studio 2017, the rules folder is *`%VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\`*. In a Visual Studio 2015 or earlier developer command prompt, the rules folder is *`%ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\`*. You'll use a different path for each edition of Visual Studio that's installed, and for each language. For example, the default rules folder path for Visual Studio 2019 Community edition in English could be *`C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\`*.
+
+::: moniker-end
 
 ### To add or change project properties
 
 1. In the XML editor, create an XML file.
 
-1. Save the file in the Visual Studio `VCTargets\1033` folder. You will have a different path for each edition of Visual Studio that is installed and each language. For example, the default folder path for Visual Studio 2019 Community edition in English is `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\VC\VCTargets`. Adjust the path for your language and Visual Studio edition. Every rule in the **Property Pages** window is represented by an XML file in this folder. Make sure that the file is uniquely named in the folder.
+1. Save the file in the default rules folder. Adjust the path for your language and Visual Studio edition. Every rule in the **Property Pages** window is represented by an XML file in this folder. Make sure that the file is uniquely named in the folder.
 
-1. Copy the content of `%ProgramFiles%\Microsoft Visual Studio\2019\<VS Edition>\Common7\IDE\VC\VCTargets\<LCID>\cl.xml` (or whatever your path is), close it without saving changes, and then paste the content in your new XML file. You can use any XML schema file - this is just one that can be used so you start with a template.
+1. Copy the content of an existing rules file, such as *`rc.xml`*, close it without saving changes, and then paste the content in your new XML file. You can copy any XML schema file to use as a template. Choose one that's similar to your tool.
 
 1. In the new XML file, modify the content according to your requirements. Make sure to change the **Rule Name** and **Rule.DisplayName** at the top of the file.
 
-1. Save the changes and close the file.
+1. Save your changes and close the file.
 
-1. The XML files in `%ProgramFiles%\Microsoft Visual Studio\2019\<VS Edition>\Common7\IDE\VC\VCTargets\<LCID>` (or wherever you saved them) are loaded when Visual Studio starts. Therefore, to test the new file, restart Visual Studio.
+1. The XML files in the rules folder are loaded when Visual Studio starts. To test the new file, restart Visual Studio.
 
-1. In **Solution Explorer**, right-click a project and then click **Properties**. In the **Property Pages** window, in the left pane, verify that there is a new node with the name of your Rule.
+1. In **Solution Explorer**, right-click a project and then choose **Properties**. In the **Property Pages** window, verify that there's a new node with the name of your rule.
 
 ## See also
 

docs/build/project-property-inheritance.md

@@ -10,17 +10,35 @@ The Visual Studio native project system is based on MSBuild. MSBuild defines fil
 
 ## The .vcxproj file, .props files and .targets files
 
-Project properties are stored either directly in the project file (*`.vcxproj`*) or in other *`.targets`* or *`.props`* files that the project file imports and which supply default values. For Visual Studio 2015, these files are located in *`\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\V140`*. For Visual Studio 2017, these files are located in *`\Program Files (x86)\Microsoft Visual Studio\2017\<edition>\Common7\IDE\VC\VCTargets`*, where *`<edition>`* is the Visual Studio edition installed. In Visual Studio 2019, these files are located in *`\Program Files (x86)\Microsoft Visual Studio\2019\<edition>\MSBuild\Microsoft\VC\v160`*. Properties are also stored in any custom *`.props`* files that you might add to your own project. We highly recommend that you NOT edit those files manually. Instead, use the property pages in the IDE to modify all properties, especially the ones that participate in inheritance, unless you have a deep understanding of MSBuild.
+::: moniker range="vs-2015"
 
-As shown earlier, the same property for the same configuration may be assigned a different value in these different files. When you build a project, the MSBuild engine evaluates the project file and all the imported files in a well-defined order (described below). As each file is evaluated, any property values defined in that file will override the existing values. Any values that aren't specified are inherited from files that were evaluated earlier. When you set a property with property pages, it's also important to pay attention to where you set it. If you set a property to "X" in a *`.props`* file, but the property is set to "Y" in the project file, then the project will build with the property set to "Y". If the same property is set to "Z" on a project item, such as a *`.cpp`* file, then the MSBuild engine will use the "Z" value.
+Project properties are stored in several files. Some are stored directly in the *`.vcxproj`* project file. Others come from other *`.targets`* or *`.props`* files that the project file imports and which supply default values. You'll find the Visual Studio 2015 project files in a locale-specific folder under the base directory, *`%ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\v140`*.
+
+::: moniker-end
+
+::: moniker range="vs-2017"
+
+Project properties are stored in several files. Some are stored directly in the *`.vcxproj`* project file. Others come from other *`.targets`* or *`.props`* files that the project file imports and which supply default values. You'll find the Visual Studio 2017 project files in a locale-specific folder under the base directory, *`%VSINSTALLDIR%Common7\IDE\VC\VCTargets\`*.
+
+::: moniker-end
+
+::: moniker range=">=vs-2019"
+
+Project properties are stored in several files. Some are stored directly in the *`.vcxproj`* project file. Others come from other *`.targets`* or *`.props`* files that the project file imports and which supply default values. You'll find the Visual Studio project files in a locale-specific folder under the base directory, *`%VSINSTALLDIR%MSBuild\Microsoft\VC\<version>`*. The `<version>` is specific to the version of Visual Studio. It's *`v160`* for Visual Studio 2019.
+
+::: moniker-end
+
+Properties are also stored in any custom *`.props`* files that you might add to your own project. We highly recommend that you *NOT* edit those files manually. Instead, use the property pages in the IDE to modify all properties, especially the ones that participate in inheritance, unless you have a deep understanding of MSBuild and *`.vcxproj`* files.
+
+As shown earlier, the same property for the same configuration may be assigned a different value in these different files. When you build a project, the MSBuild engine evaluates the project file and all the imported files in a well-defined order that's described later. As each file is evaluated, any property values defined in that file will override the existing values. Any values that aren't specified are inherited from files that were evaluated earlier. When you set a property with property pages, it's also important to pay attention to where you set it. If you set a property to "X" in a *`.props`* file, but the property is set to "Y" in the project file, then the project will build with the property set to "Y". If the same property is set to "Z" on a project item, such as a *`.cpp`* file, then the MSBuild engine will use the "Z" value.
 
 Here's the basic inheritance tree:
 
-1. Default settings from the MSBuild CPP Toolset (..\Program Files\MSBuild\Microsoft.Cpp\v4.0\Microsoft.Cpp.Default.props, which is imported by the *`.vcxproj`* file.)
+1. Default settings from the MSBuild CPP Toolset (the *`Microsoft.Cpp.Default.props`* file in the base directory, which is imported by the *`.vcxproj`* file.)
 
 1. Property sheets
 
-1. *`.vcxproj`* file. (Can override the default and property sheet settings.)
+1. *`.vcxproj`* file. (This file can override the default and property sheet settings.)
 
 1. Items metadata