Repo sync for protected CLA branch

.github/workflows/stale-issues.yml

@@ -29,6 +29,6 @@ jobs:
           exempt-issue-labels: 'exempt'
           remove-stale-when-updated: true
           days-before-close: 14
-          days-before-issue-stale: 180
+          days-before-issue-stale: 90
           days-before-pr-stale: -1
           operations-per-run: 500

.openpublishing.redirection.json

@@ -1,5 +1,10 @@
 {
   "redirections": [
+    {
+      "source_path": "docs/msbuild/updating-an-existing-application.md",
+      "redirect_url": "/visualstudio/msbuild/find-and-use-msbuild-versions",
+      "redirect_document_id": true
+    },
     {
       "source_path": "docs/python/managing-python-on-azure-app-service.md",
       "redirect_url": "/azure/app-service/quickstart-python",

docs/designers/disable-dpi-awareness.md

@@ -1,7 +1,7 @@
 ---
 title: Disable DPI-awareness for scaling in forms
 description: Fix scaling issues with Windows Forms Designer on HDPI monitors.
-ms.date: 10/20/2022
+ms.date: 10/31/2022
 author: TerryGLee
 ms.author: tglee
 manager: jmartens
@@ -13,9 +13,9 @@ ms.custon: contperf-fy22q2
 
  [!INCLUDE [Visual Studio](~/includes/applies-to-version/vs-windows-only.md)]
 
-In this article, you'll learn the limitations of Windows Forms Designer on HDPI monitors and [how to run Visual Studio as a DPI-unaware process](#resolve-hdpi-display-problems).
+In this article, you'll learn about the limitations of Windows Forms Designer on HDPI monitors and [how to run Visual Studio as a DPI-unaware process](#resolve-hdpi-display-problems).
 
-Visual Studio is a dots per inch (DPI) aware application, which means the display scales automatically. If an application states that it's not DPI-aware, the operating system scales the application as a bitmap. This behavior is also called DPI virtualization. The application still thinks that it's running at 100% scaling, or 96 dpi.
+Visual Studio is a dots per inch (DPI) aware application, which means the display scales automatically. If an application states that it's not DPI-aware, the operating system scales the application as a bitmap. This behavior is also called DPI virtualization. The application still thinks that it's running at 100% scaling, or 96 DPI.
 
 You can also:
 + [Automatically scale in Windows Forms](/dotnet/framework/winforms/automatic-scaling-in-windows-forms)
@@ -27,81 +27,69 @@ Since the **Windows Forms Designer** in Visual Studio doesn't have scaling suppo
 
 ![Windows Forms Designer on HDPI monitor](./media/win-forms-designer-hdpi-1.gif)
 
-If you aren't working in the designer and don't need to adjust the layout of your form, you can ignore the informational bar and continue working in the code editor or in other types of designers. (You can also [disable notifications](#disable-notifications) so that the informational bar doesn't continue to appear.) Only the **Windows Forms Designer** is affected.
+### Use the information bar
 
-When you open a form in the **Windows Forms Designer** on an HDPI monitor, Visual Studio displays an informational bar.
-
-:::image type="content" source="media/scaling-gold-bar-message-1.png" alt-text="Screenshot of the informational bar in Visual Studio to restart in DPI-unaware mode.":::
+When you open a form in the **Windows Forms Designer** on an HDPI monitor, Visual Studio displays an information bar.
 
+:::image type="content" source="media/scaling-gold-bar-message-1.png" alt-text="Screenshot of the information bar in Visual Studio to restart in DPI-unaware mode.":::
 
+If you aren't working in the designer and don't need to adjust the layout of your form, you can ignore the information bar and continue working in the code editor or in other types of designers. (You can also [disable notifications](#disable-notifications) so that the information bar doesn't continue to appear.) Only the **Windows Forms Designer** is affected.
 
 > [!TIP]
-> If you've closed the informational bar at the top of the designer, but you still want to replicate the behavior of the link that says **Restart Visual Studio with 100% scaling**, you still can. Select **Tools** > **Command Line** > **Developer Command Prompt** from the Visual Studio menu bar. Then, enter `devenv /noScale`.
+> If you've closed the information bar but you still want restart Visual Studio with 100% scaling, you can. [Use the DevEnv.exe tool](#use-the-devenvexe-tool) to do so.
 
 ## Resolve HDPI display problems
 
-There are three options to resolve the display problem:
+There are several options to resolve the display problem:
 
 - [Restart Visual Studio as a DPI-unaware process](#restart-visual-studio-as-a-dpi-unaware-process)
-- [Add a registry entry](#add-a-registry-entry)
+<!-- - [Add a registry entry](#add-a-registry-entry) -->
 - [Set your display scaling setting to 100%](#set-your-display-scaling-setting-to-100)
-
-> [!TIP]
-> If you prefer to manage settings from the command line, [`devenv.exe`](../ide/reference/devenv-command-line-switches.md) takes `/noscale` as a command-line parameter to run in 100% scaling mode.
+- [Use the DevEnv.exe tool](#use-the-devenvexe-tool)
 
 ### Restart Visual Studio as a DPI-unaware process
 
-The preferred solution to this issue is to restart Visual Studio as a DPI-unaware process. Do so by selecting the option on the yellow informational bar.
+The preferred solution to this issue is to restart Visual Studio as a DPI-unaware process. Do so by selecting the option on the yellow information bar.
 
-When Visual Studio runs as a DPI-unaware process, the designer layout issues are resolved, but fonts may appear blurry and you may see issues in other designers such as the **XAML Designer**.. Visual Studio displays a different yellow informational message when it runs as a DPI-unaware process that says **Visual Studio is running as a DPI-unaware process. WPF and XAML designers might not display correctly.** The informational bar also provides an option to **Restart Visual Studio as a DPI-aware process**.
+When Visual Studio runs as a DPI-unaware process, the designer layout issues are resolved, but fonts may appear blurry and you may see issues in other designers such as the **XAML Designer**. Visual Studio displays a different yellow informational message when it runs as a DPI-unaware process that says **Visual Studio is running as a DPI-unaware process. WPF and XAML designers might not display correctly.** The informational bar also provides an option to **Restart Visual Studio as a DPI-aware process**.
 
 ::: moniker range="<=vs-2019"
 
 > [!NOTE]
-> - If you have undocked tool windows in Visual Studio when you select the option to restart as a DPI-unaware process, the position of the tool windows might change.
+> - If you have undocked [tool windows](../ide/customizing-window-layouts-in-visual-studio.md#tool-and-document-windows) in Visual Studio when you select the option to restart as a DPI-unaware process, the position of the tool windows might change.
 > - If you use the default Visual Basic profile, or if you have the **Save new projects when created** option deselected in **Tools** > **Options** > **Projects and Solutions**, Visual Studio cannot reopen your project when it restarts as a DPI-unaware process. However, you can open the project by selecting it under **File** > **Recent Projects and Solutions**.
 
 ::: moniker-end
 
 ::: moniker range=">=vs-2022"
 
 > [!NOTE]
-> - If you have undocked tool windows in Visual Studio when you select the option to restart as a DPI-unaware process, the position of the tool windows might change.
+> - If you have undocked [tool windows](../ide/customizing-window-layouts-in-visual-studio.md#tool-and-document-windows) in Visual Studio when you select the option to restart as a DPI-unaware process, the position of the tool windows might change.
 > - If you use the default Visual Basic profile, Visual Studio cannot reopen your project when it restarts as a DPI-unaware process. However, you can open the project by selecting it under **File** > **Recent Projects and Solutions**.
 
 ::: moniker-end
 
 It's important to restart Visual Studio as a DPI-aware process when you're finished working in the **Windows Forms Designer**. If you close and reopen Visual Studio when it's running in DPI-unaware mode, it becomes DPI-aware again. You can also select the **Restart Visual Studio as a DPI-aware process** option in the informational bar.
 
-### Add a registry entry
-
-As option two, you can mark Visual Studio as DPI-unaware by modifying the registry. Open **Registry Editor** and add an entry to the **HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\Layers** subkey:
-
-**Entry**: Depending on whether you're using Visual Studio 2017, 2019, or 2022, use one of these values:
-
-- C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\devenv.exe
-- C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\devenv.exe
-- C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\devenv.exe
-
-> [!NOTE]
-> If you're using the Professional or Enterprise edition of Visual Studio, replace **Community** with **Professional** or **Enterprise** in the entry. Also replace the drive letter as necessary.
+### Set your display scaling setting to 100%
 
-**Type**: REG_SZ <br>
-**Value**: DPIUNAWARE
+A third option to resolving the issue is to set your display scaling setting to 100% in Windows 10, type **display settings** in the task bar search box, and then select **Change display settings**. In the **Settings** window, set **Change the size of text, apps, and other items** to **100%**.  However, setting your display scaling to 100% may be undesirable since it can make the user interface too small to be usable.
 
-Visual Studio remains in DPI-unaware mode until you remove the registry entry.
+### Use the DevEnv.exe tool
 
-### Set your display scaling setting to 100%
+If you prefer to manage settings from the command line, [`devenv.exe`](../ide/reference/devenv-command-line-switches.md) takes `/noscale` as a command-line parameter to run in 100% scaling mode. Here's how:
 
-A third option to resolving the issue is to set your display scaling setting to 100% in Windows 10, type **display settings** in the task bar search box, and then select **Change display settings**. In the **Settings** window, set **Change the size of text, apps, and other items** to **100%**.  However, setting your display scaling to 100% may be undesirable since it can make the user interface too small to be usable.
+1. Select **Tools** > **Command Line** > **Developer Command Prompt** from the Visual Studio menu bar.
+1. Then, enter `devenv /noScale`.
 
 ## Disable notifications
 
 You can choose not to be notified of DPI scaling issues in Visual Studio. You might want to disable notifications if you aren't working in the designer, for example.
 
 To disable notifications:
+
 1. Choose **Tools** > **Options** to open the **Options** dialog.
-2. In the **Options** dialog, choose **Windows Forms Designer** > **General**, and set **DPI Scaling Notifications** to **False**.
+1. In the **Options** dialog, choose **Windows Forms Designer** > **General**, and set **DPI Scaling Notifications** to **False**.
 
 If you want to later reenable scaling notifications, set the property to **True**.
 

docs/msbuild/find-and-use-msbuild-versions.md

@@ -0,0 +1,128 @@
+---
+title: Find MSBuild and use its API | Microsoft Docs
+description: Learn how to ensure that programmatic builds from your application match builds done within Visual Studio or MSBuild.exe, and learn how to locate and use a consistent version on MSBuild when developing a programmatic build application on different machines.
+ms.custom: SEO-VS-2020
+ms.date: 10/25/2022
+ms.topic: conceptual
+author: ghogen
+ms.author: ghogen
+manager: jmartens
+ms.technology: msbuild
+ms.workload:
+- multiple
+---
+# Find and use a version of MSBuild
+
+To ensure that programmatic builds from your application match builds done within Visual Studio or *MSBuild.exe*, you might need to load the same version of the MSBuild assemblies that were installed with a specific version of Visual Studio and use the same SDKs that are available within that version of Visual Studio. Or, when you're creating a build application that will be run on machines that might have various installed versions of MSBuild, .NET, and Visual Studio, you might also want to find and use a consistent version of MSBuild. The Microsoft.Build.Locator NuGet package streamlines this process.
+
+## Use Microsoft.Build.Locator
+
+The Microsoft.Build.Locator package is relevant to situations where your application runs on client machines, virtual machines, or within containers, either where Visual Studio is installed or in environments where only the Visual Studio Build Tools, or just the .NET SDK is installed, such as when builds are requested with the `dotnet build` command line. In any case, your application needs to find the desired version of MSBuild. That could be the version that matches Visual Studio, MSBuild.exe, or `dotnet build`, or a particular consistent version regardless of the varying machine configurations in environments where your application might be used.
+
+If you redistribute *Microsoft.Build.Locator.dll* with your application, you won't need to distribute other MSBuild assemblies.
+
+Using the locator API requires a few changes in your project, described below. To see an example of the changes required to update a project, see [the commits made to an example project in the MSBuildLocator repository](https://github.com/Microsoft/MSBuildLocator/commits/example-updating-to-msbuild-15).
+
+## Change MSBuild references
+
+To make sure that MSBuild loads from a central location, you must not distribute its assemblies with your application.
+
+The mechanism for changing your project to avoid loading MSBuild from a central location depends on how you reference MSBuild.
+
+### Use NuGet packages (preferred)
+
+These instructions assume that you're using [PackageReference-style NuGet references](/nuget/consume-packages/package-references-in-project-files).
+
+Change your project file(s) to reference MSBuild assemblies from their NuGet packages. Specify `ExcludeAssets=runtime` to tell NuGet that the assemblies are needed only at build time, and shouldn't be copied to the output directory.
+
+The major and minor version of the MSBuild packages must be less than or equal to the minimum version of Visual Studio you wish to support. For example, if you wish to support Visual Studio 2017 and later versions, reference package version `15.1.548`.
+
+For example, you can use this XML:
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Microsoft.Build" Version="15.1.548" ExcludeAssets="runtime" />
+  <PackageReference Include="Microsoft.Build.Utilities.Core" Version="15.1.548" ExcludeAssets="runtime" />
+</ItemGroup>
+```
+
+#### Use extension assemblies
+
+If you can't use NuGet packages, you can reference MSBuild assemblies that are distributed with Visual Studio. If you reference MSBuild directly, ensure that it won't be copied to your output directory by setting `Copy Local` to `False`. In the project file, this setting will look like the following code:
+
+```xml
+    <Reference Include="Microsoft.Build, Version=15.1.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
+      <Private>False</Private>
+    </Reference>
+```
+
+> [!NOTE]
+> If you're updating from a version of MSBuild prior to 15, MSBuild requires binding redirects for certain assemblies (Microsoft.Build assemblies), but if you reference the Microsoft.Build.Locator package, you ensure that your application automatically uses the required binding redirects to version 15.1.0.0. Binding redirects to this version support MSBuild 15.x, 16.x, and 17.x.
+
+## Ensure output is clean
+
+Build your project and inspect the output directory to make sure that it doesn't contain any *Microsoft.Build.\*.dll* assemblies other than *Microsoft.Build.Locator.dll*, added in the next step.
+
+## Add package reference for Microsoft.Build.Locator
+
+Add a NuGet package reference for [Microsoft.Build.Locator](https://www.nuget.org/packages/Microsoft.Build.Locator/).
+
+```xml
+    <PackageReference Include="Microsoft.Build.Locator">
+      <Version>1.1.2</Version>
+    </PackageReference>
+```
+
+Do not specify `ExcludeAssets=runtime` for the Microsoft.Build.Locator package.
+
+## Register instance before calling MSBuild
+
+When you're creating a build application for general use, you don't know what versions of Visual Studio, .NET, and MSBuild might be installed on a machine your application is being executed on. The purpose of MSBuildLocator is to find an appropriate installation of MSBuild to use on machines with diverse installation environments. MSBuildLocator allows you to specify some logic to determine which MSBuild to use, but you as the developer of your application need to determine what MSBuild version it requires or can accept, or else provide a way for your users to specify a version, and include logic to translate that choice into appropriate calls to the MSBuildLocator API.
+
+The simplest way to add the call to the Locator API is to add a call to `MSBuildLocator.RegisterInstance`
+in your application startup code. One example is to pick the latest version, as shown here, but your application might have it own requirements.
+
+You cannot reference any MSBuild types (from the `Microsoft.Build` namespace) in the method that calls MSBuildLocator. For example, you cannot do this:
+
+ ```csharp
+ void ThisWillFail()
+ {
+     // Register the most recent version of MSBuild
+     RegisterInstance(MSBuildLocator.QueryVisualStudioInstances().OrderByDescending(
+        instance => instance.Version).First());
+     Project p = new Project(SomePath); // Could be any MSBuild type
+     // Code that uses the MSBuild type
+ }
+ ```
+
+ Instead, you must do this:
+
+ ```csharp
+ void MethodThatDoesNotDirectlyCallMSBuild()
+ {
+     var instance = ... // select which of the installed instances to use
+
+     // Register a specific instance of MSBuild
+     MSBuildLocator.RegisterInstance(instance);
+     MethodThatCallsMSBuild();
+ }
+
+ void MethodThatCallsMSBuild()
+ {
+     Project p = new Project(SomePath);
+     // Code that uses the MSBuild type
+ }
+ ```
+
+To specify an MSBuild instance, you can select a result of `MSBuildLocator.QueryVisualStudioInstances` to pass to `MSBuildLocator.RegisterInstance` using the custom logic you need.
+
+## Next steps
+
+Learn about MSBuild APIs by consulting the MSBuild API Reference:
+
+- [Microsoft.Build.Evaluation](/dotnet/api/microsoft.build.evaluation)
+- [Microsoft.Build.Execution](/dotnet/api/microsoft.build.execution)
+- [Microsoft.Build.Framework](/dotnet/api/microsoft.build.framework)
+- [Microsoft.Build.Logging](/dotnet/api/microsoft.build.logging)
+- [Microsoft.Build.Tasks](/dotnet/api/microsoft.build.tasks)
+- [Microsoft.Build.Utilities](/dotnet/api/microsoft.build.utilities)