Skip to content

Commit 895c579

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #10548 from ghogen/issues-8588-smaller
Update guidance for locating versions of MSBuild
2 parents 8080ee8 + 10ca81e commit 895c579

File tree

4 files changed

+135
-123
lines changed

4 files changed

+135
-123
lines changed

‎.openpublishing.redirection.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
{
22
"redirections": [
3+
{
4+
"source_path": "docs/msbuild/updating-an-existing-application.md",
5+
"redirect_url": "/visualstudio/msbuild/find-and-use-msbuild-versions",
6+
"redirect_document_id": true
7+
},
38
{
49
"source_path": "docs/python/managing-python-on-azure-app-service.md",
510
"redirect_url": "/azure/app-service/quickstart-python",

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

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: Find MSBuild and use its API | Microsoft Docs
3+
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.
4+
ms.custom: SEO-VS-2020
5+
ms.date: 10/25/2022
6+
ms.topic: conceptual
7+
author: ghogen
8+
ms.author: ghogen
9+
manager: jmartens
10+
ms.technology: msbuild
11+
ms.workload:
12+
- multiple
13+
---
14+
# Find and use a version of MSBuild
15+
16+
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.
17+
18+
## Use Microsoft.Build.Locator
19+
20+
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.
21+
22+
If you redistribute *Microsoft.Build.Locator.dll* with your application, you won't need to distribute other MSBuild assemblies.
23+
24+
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).
25+
26+
## Change MSBuild references
27+
28+
To make sure that MSBuild loads from a central location, you must not distribute its assemblies with your application.
29+
30+
The mechanism for changing your project to avoid loading MSBuild from a central location depends on how you reference MSBuild.
31+
32+
### Use NuGet packages (preferred)
33+
34+
These instructions assume that you're using [PackageReference-style NuGet references](/nuget/consume-packages/package-references-in-project-files).
35+
36+
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.
37+
38+
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`.
39+
40+
For example, you can use this XML:
41+
42+
```xml
43+
<ItemGroup>
44+
<PackageReference Include="Microsoft.Build" Version="15.1.548" ExcludeAssets="runtime" />
45+
<PackageReference Include="Microsoft.Build.Utilities.Core" Version="15.1.548" ExcludeAssets="runtime" />
46+
</ItemGroup>
47+
```
48+
49+
#### Use extension assemblies
50+
51+
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:
52+
53+
```xml
54+
<Reference Include="Microsoft.Build, Version=15.1.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
55+
<Private>False</Private>
56+
</Reference>
57+
```
58+
59+
> [!NOTE]
60+
> 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.
61+
62+
## Ensure output is clean
63+
64+
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.
65+
66+
## Add package reference for Microsoft.Build.Locator
67+
68+
Add a NuGet package reference for [Microsoft.Build.Locator](https://www.nuget.org/packages/Microsoft.Build.Locator/).
69+
70+
```xml
71+
<PackageReference Include="Microsoft.Build.Locator">
72+
<Version>1.1.2</Version>
73+
</PackageReference>
74+
```
75+
76+
Do not specify `ExcludeAssets=runtime` for the Microsoft.Build.Locator package.
77+
78+
## Register instance before calling MSBuild
79+
80+
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.
81+
82+
The simplest way to add the call to the Locator API is to add a call to `MSBuildLocator.RegisterInstance`
83+
in your application startup code. One example is to pick the latest version, as shown here, but your application might have it own requirements.
84+
85+
You cannot reference any MSBuild types (from the `Microsoft.Build` namespace) in the method that calls MSBuildLocator. For example, you cannot do this:
86+
87+
```csharp
88+
void ThisWillFail()
89+
{
90+
// Register the most recent version of MSBuild
91+
RegisterInstance(MSBuildLocator.QueryVisualStudioInstances().OrderByDescending(
92+
instance => instance.Version).First());
93+
Project p = new Project(SomePath); // Could be any MSBuild type
94+
// Code that uses the MSBuild type
95+
}
96+
```
97+
98+
Instead, you must do this:
99+
100+
```csharp
101+
void MethodThatDoesNotDirectlyCallMSBuild()
102+
{
103+
var instance = ... // select which of the installed instances to use
104+
105+
// Register a specific instance of MSBuild
106+
MSBuildLocator.RegisterInstance(instance);
107+
MethodThatCallsMSBuild();
108+
}
109+
110+
void MethodThatCallsMSBuild()
111+
{
112+
Project p = new Project(SomePath);
113+
// Code that uses the MSBuild type
114+
}
115+
```
116+
117+
To specify an MSBuild instance, you can select a result of `MSBuildLocator.QueryVisualStudioInstances` to pass to `MSBuildLocator.RegisterInstance` using the custom logic you need.
118+
119+
## Next steps
120+
121+
Learn about MSBuild APIs by consulting the MSBuild API Reference:
122+
123+
- [Microsoft.Build.Evaluation](/dotnet/api/microsoft.build.evaluation)
124+
- [Microsoft.Build.Execution](/dotnet/api/microsoft.build.execution)
125+
- [Microsoft.Build.Framework](/dotnet/api/microsoft.build.framework)
126+
- [Microsoft.Build.Logging](/dotnet/api/microsoft.build.logging)
127+
- [Microsoft.Build.Tasks](/dotnet/api/microsoft.build.tasks)
128+
- [Microsoft.Build.Utilities](/dotnet/api/microsoft.build.utilities)

‎docs/msbuild/toc.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -730,7 +730,7 @@ items:
730730
- name: Overview
731731
displayName: Use MSBuild programmatically
732732
href: msbuild-api.md
733-
- name: Update to MSBuild 15
734-
href: updating-an-existing-application.md
733+
- name: Find and use a version of MSBuild
734+
href: find-and-use-msbuild-versions.md
735735
- name: MSBuild glossary
736736
href: msbuild-glossary.md

‎docs/msbuild/updating-an-existing-application.md

Lines changed: 0 additions & 121 deletions
This file was deleted.

0 commit comments

Comments
 (0)