Merge pull request #13698 from ghogen/msbuild-slnx

MSBuild support for slnx builds

Author: prmerger-automator[bot]

docs/msbuild/build-process-overview.md

@@ -24,7 +24,7 @@ The next sections are about the input files, such as solution files or project f
 
 ### Solutions and projects
 
-MSBuild instances may consist of one project, or many projects as part of a solution. The solution file isn't an MSBuild XML file, but MSBuild interprets it to know all the projects that are required to be built for the given configuration and platform settings. When MSBuild processes this XML input, it's referred to as the solution build. It has some extensible points that allow you to run something at every solution build, but since this build is a separate run from the individual project builds, no settings of properties or target definitions from the solution build are relevant to each project build.
+MSBuild instances may consist of one project, or many projects as part of a solution. Solution files in the `.slnx` format or the `.sln` format are both supported (in MSBuild 17.12 and later). The solution file (`.sln`) isn't an MSBuild XML file, but MSBuild interprets it to know all the projects that are required to be built for the given configuration and platform settings. When MSBuild processes this input, it's referred to as the solution build. It has some extensible points that allow you to run something at every solution build, but since this build is a separate run from the individual project builds, no settings of properties or target definitions from the solution build are relevant to each project build.
 
 You can find out how to extend the solution build at [Customize the solution build](customize-solution-build.md).
 

docs/msbuild/customize-solution-build.md

@@ -35,6 +35,9 @@ When you have many solution files that you want to extend in the same way, but y
 
 When you have *Directory.Solution.props* or *Directory.Solution.targets* in a root folder, but you have a solution under that folder that you don't want to import them, you can use the solution-specific files mentioned previously `before.{solutionname}.sln.targets` and `after.{solutionname}.sln.targets` to set the properties `$(ImportDirectorySolutionProps)` and `$(ImportDirectorySolutionTargets)` to false. Or, you can use the properties `$(DirectorySolutionPropsPath)` and `$(DirectorySolutionTargetsPath)` to specify a different location for those files. This could be helpful if you have various subsets of your solutions that require certain property values or targets common to the subsets.
 
+> [!NOTE]
+> The solution build is supported with the `.slnx` solution file format in MSBuild 17.12 and later. Both `before.{solutionname}.slnx.targets` and `before.{solutionname}.sln.targets` work (and likewise for the `after` forms) with MSBuild 17.14 and later.
+
 ## Related content
 
 - [Customize your build](customize-your-build.md).

docs/msbuild/msbuild-command-line-reference.md

@@ -32,7 +32,7 @@ The .NET CLI commands [dotnet build](/dotnet/core/tools/dotnet-build), [dotnet p
 
 |Argument|Description|
 |--------------|-----------------|
-|`ProjectFile`|Builds the targets in the project file that you specify. If you don't specify a project file, MSBuild searches the current working directory for a file name extension that ends in *proj* and uses that file. You can also specify a Visual Studio solution file for this argument.|
+|`ProjectFile`|Builds the targets in the project file that you specify. If you don't specify a project file, MSBuild searches the current working directory for a file name extension that ends in *proj* and uses that file. You can also specify a Visual Studio solution file for this argument. In Visual Studio 17.12 and later, the `.slnx` solution file format is supported, as well as the `.sln` format. Both `.sln` and `.slnx` files for the same solution can be present in the same directory; if both are present, you must explicitly specify one of them to build the solution. |
 
 ## Switches
 

docs/msbuild/msbuild-task.md

@@ -27,50 +27,50 @@ Builds MSBuild projects from another MSBuild project.
 
 | Parameter | Description |
 |-----------------------------------| - |
-| `BuildInParallel` | Optional `Boolean` parameter.<br /><br /> If `true`, the projects specified in the `Projects` parameter are built in parallel if it is possible. Default is `false`. |
+| `BuildInParallel` | Optional `Boolean` parameter.<br /><br /> If `true`, the projects specified in the `Projects` parameter are built in parallel if it's possible. Default is `false`. |
 | `Projects` | Required <xref:Microsoft.Build.Framework.ITaskItem>`[]` parameter.<br /><br /> Specifies the project files to build. |
-| `Properties` | Optional `String` parameter.<br /><br /> A semicolon-delimited list of property name/value pairs to apply as global properties to the child project. When you specify this parameter, it is functionally equivalent to setting properties that have the **-property** switch when you build with [*MSBuild.exe*](../msbuild/msbuild-command-line-reference.md). For example:<br /><br /> `Properties="Configuration=Debug;Optimize=$(Optimize)"`<br /><br /> When you pass properties to the project through the `Properties` parameter, MSBuild might create a new instance of the project even if the project file has already been loaded. MSBuild creates a single project instance for a given project path and a unique set of global properties. For example, this behavior allows you to create multiple MSBuild tasks that call *myproject.proj*, with Configuration=Release and you get a single instance of *myproject.proj* (if no unique properties are specified in the task). If you specify a property that has not yet been seen by MSBuild, MSBuild creates a new instance of the project, which can be built in parallel to other instances of the project. For example, a Release configuration can build at the same time as a Debug configuration.|
+| `Properties` | Optional `String` parameter.<br /><br /> A semicolon-delimited list of property name/value pairs to apply as global properties to the child project. When you specify this parameter, it's functionally equivalent to setting properties that have the **-property** switch when you build with [*MSBuild.exe*](../msbuild/msbuild-command-line-reference.md). For example:<br /><br /> `Properties="Configuration=Debug;Optimize=$(Optimize)"`<br /><br /> When you pass properties to the project through the `Properties` parameter, MSBuild might create a new instance of the project even if the project file has already been loaded. MSBuild creates a single project instance for a given project path and a unique set of global properties. For example, this behavior allows you to create multiple MSBuild tasks that call *myproject.proj*, with Configuration=Release and you get a single instance of *myproject.proj* (if no unique properties are specified in the task). If you specify a property that hasn't yet been seen by MSBuild, MSBuild creates a new instance of the project, which can be built in parallel to other instances of the project. For example, a Release configuration can build at the same time as a Debug configuration.|
 | `RebaseOutputs` | Optional `Boolean` parameter.<br /><br /> If `true`, the relative paths of target output items from the built projects have their paths adjusted to be relative to the calling project. Default is `false`. |
 | `RemoveProperties` | Optional `String` parameter.<br /><br /> Specifies the set of global properties to remove. |
 | `RunEachTargetSeparately` | Optional `Boolean` parameter.<br /><br /> If `true`, the MSBuild task invokes each target in the list passed to MSBuild one at a time, instead of at the same time. Setting this parameter to `true` guarantees that subsequent targets are invoked even if previously invoked targets failed. Otherwise, a build error would stop invocation of all subsequent targets. Default is `false`. |
-| `SkipNonexistentProjects` | Optional `Boolean` parameter.<br /><br /> If `true`, project files that do not exist on the disk will be skipped. Otherwise, such projects will cause an error. Defaults to `false`.|
-|`SkipNonexistentTargets`|Optional `Boolean` parameter.<br /><br /> If `true`, project files that exist but do not contain the named `Targets` will be skipped. Otherwise, such projects will cause an error. Defaults to `false`. Introduced in MSBuild 15.5.|
-| `StopOnFirstFailure` | Optional `Boolean` parameter.<br /><br /> If `true`, when one of the projects fails to build, no more projects will be built. Currently this is not supported when building in parallel (with multiple processors). |
-| `TargetAndPropertyListSeparators` | Optional `String[]` parameter.<br /><br /> Specifies a list of targets and properties as `Project` item metadata). Separators will be un-escaped before processing. e.g. %3B (an escaped ';') will be treated as if it were an un-escaped ';'. |
+| `SkipNonexistentProjects` | Optional `Boolean` parameter.<br /><br /> If `true`, project files that don't exist on the disk are skipped. Otherwise, such projects will cause an error. Defaults to `false`.|
+|`SkipNonexistentTargets`|Optional `Boolean` parameter.<br /><br /> If `true`, project files that exist but don't contain the named `Targets` are skipped. Otherwise, such projects will cause an error. Defaults to `false`. Introduced in MSBuild 15.5.|
+| `StopOnFirstFailure` | Optional `Boolean` parameter.<br /><br /> If `true`, when one of the projects fails to build, no more projects are built. Currently this option is not supported when building in parallel (with multiple processors). |
+| `TargetAndPropertyListSeparators` | Optional `String[]` parameter.<br /><br /> Specifies a list of targets and properties as `Project` item metadata). Separators are unescaped before processing. For example, %3B (an escaped ';') is treated as if it were an unescaped ';'. |
 | `TargetOutputs` | Optional <xref:Microsoft.Build.Framework.ITaskItem>`[]` read-only output parameter.<br /><br /> Returns the outputs of the built targets from all the project files. Only the outputs from the targets that were specified are returned, not any outputs that may exist on targets that those targets depend on.<br /><br /> The `TargetOutputs` parameter also contains the following metadata:<br /><br /> -   `MSBuildSourceProjectFile`: The MSBuild project file that contains the target that set the outputs.<br />-   `MSBuildSourceTargetName`: The target that set the outputs. **Note:**  If you want to identify the outputs from each project file or target separately, run the `MSBuild` task separately for each project file or target. If you run the `MSBuild` task only once to build all the project files, the outputs of all the targets are collected into one array. |
-| `Targets` | Optional `String` parameter.<br /><br /> Specifies the target or targets to build in the project files. Use a semicolon to separate a list of target names. If no targets are specified in the `MSBuild` task, the default targets specified in the project files are built. **Note:**  The targets must occur in all the project files. If they do not, a build error occurs. |
-| `ToolsVersion` | Optional `String` parameter.<br /><br /> Specifies the `ToolsVersion` to use when building projects passed to this task.<br /><br /> Enables an MSBuild task to build a project that targets a different version of the .NET Framework than the one specified in the project. Valid values are `2.0`, `3.0` and `3.5`. Default value is `3.5`. |
+| `Targets` | Optional `String` parameter.<br /><br /> Specifies the target or targets to build in the project files. Use a semicolon to separate a list of target names. If no targets are specified in the `MSBuild` task, the default targets specified in the project files are built. **Note:**  The targets must occur in all the project files. If they don't, a build error occurs. |
+| `ToolsVersion` | Optional `String` parameter.<br /><br /> Specifies the `ToolsVersion` to use when building projects passed to this task.<br /><br /> Enables an MSBuild task to build a project that targets a different version of the .NET Framework than the one specified in the project. Valid values are `2.0`, `3.0`, and `3.5`. Default value is `3.5`. |
 
 ## Remarks
 
- In addition to the parameters listed above, this task inherits parameters from the <xref:Microsoft.Build.Tasks.TaskExtension> class, which itself inherits from the <xref:Microsoft.Build.Utilities.Task> class. For a list of these additional parameters and their descriptions, see [TaskExtension base class](../msbuild/taskextension-base-class.md).
+ In addition to the parameters listed previously, this task inherits parameters from the <xref:Microsoft.Build.Tasks.TaskExtension> class, which itself inherits from the <xref:Microsoft.Build.Utilities.Task> class. For a list of these additional parameters and their descriptions, see [TaskExtension base class](../msbuild/taskextension-base-class.md).
 
  Unlike using the [Exec task](../msbuild/exec-task.md) to start *MSBuild.exe*, this task uses the same MSBuild process to build the child projects. The list of already-built targets that can be skipped is shared between the parent and child builds. This task is also faster because no new MSBuild process is created.
 
- This task can process not only project files but also solution files.
+ This task can process not only project files but also solution files. In MSBuild 17.12 and later, both `.slnx` and `.sln` solution file formats are accepted.
 
- Any configuration that is required by MSBuild to enable projects to build at the same time, even if the configuration involves remote infrastructure (for example, ports, protocols, timeouts, retries, and so forth), must be made configurable by using a configuration file. When possible, configuration items should be able to be specified as task parameters on the `MSBuild` task.
+ Any configuration that is required by MSBuild to enable projects to build at the same time, even if the configuration involves remote infrastructure (for example, ports, protocols, time-outs, retries, and so forth), must be made configurable by using a configuration file. When possible, configuration items should be able to be specified as task parameters on the `MSBuild` task.
 
- Beginning in MSBuild 3.5, Solution projects now surface TargetOutputs from all of the sub-projects it builds.
+ Beginning in MSBuild 3.5, Solution projects now surface TargetOutputs from all of the subprojects it builds.
 
 ## Pass properties to projects
 
  In versions of MSBuild prior to MSBuild 3.5, passing different sets of properties to different projects listed in the MSBuild item was challenging. If you used the Properties attribute of the [MSBuild task](../msbuild/msbuild-task.md), then its setting was applied to all of the projects being built unless you batched the [MSBuild task](../msbuild/msbuild-task.md) and conditionally provided different properties for each project in the item list.
 
- MSBuild 3.5, however, provides two new reserved metadata items, Properties and AdditionalProperties, that provide you a flexible way to pass different properties for different projects being built using the [MSBuild task](../msbuild/msbuild-task.md).
+ MSBuild 3.5, however, provides two new reserved metadata items, Properties and AdditionalProperties, that provide you with a flexible way to pass different properties for different projects being built using the [MSBuild task](../msbuild/msbuild-task.md).
 
 > [!NOTE]
 > These new metadata items are applicable only to items passed in the Projects attribute of the [MSBuild task](../msbuild/msbuild-task.md).
 
 ## Multi-processor build benefits
 
- One of the major benefits of using this new metadata occurs when you build your projects in parallel on a multi-processor system. The metadata allows you to consolidate all projects into a single [MSBuild task](../msbuild/msbuild-task.md) call without having to perform any batching or conditional MSBuild tasks. And when you call only a single [MSBuild task](../msbuild/msbuild-task.md), all of the projects listed in the Projects attribute will be built in parallel. (Only, however, if the `BuildInParallel=true` attribute is present in the [MSBuild task](../msbuild/msbuild-task.md).) For more information, see [Build multiple projects in parallel](../msbuild/building-multiple-projects-in-parallel-with-msbuild.md).
+ One of the major benefits of using this new metadata occurs when you build your projects in parallel on a multi-processor system. The metadata allows you to consolidate all projects into a single [MSBuild task](../msbuild/msbuild-task.md) call without having to perform any batching or conditional MSBuild tasks. And when you call only a single [MSBuild task](../msbuild/msbuild-task.md), all of the projects listed in the Projects attribute are built in parallel. (Only, however, if the `BuildInParallel=true` attribute is present in the [MSBuild task](../msbuild/msbuild-task.md).) For more information, see [Build multiple projects in parallel](../msbuild/building-multiple-projects-in-parallel-with-msbuild.md).
 
 ## Properties metadata
 
  When specified, Properties metadata overrides the task's Properties parameter, while [AdditionalProperties](#additionalproperties-metadata) metadata gets appended to the parameter's definitions.
 
- A common scenario is when you are building multiple solution files using the [MSBuild task](../msbuild/msbuild-task.md), only using different build configurations. You may want to build solution a1 using the Debug configuration and solution a2 using the Release configuration. In MSBuild 2.0, this project file would look like the following:
+ A common scenario is when you're building multiple solution files using the [MSBuild task](../msbuild/msbuild-task.md), only using different build configurations. You may want to build solution a1 using the Debug configuration and solution a2 using the Release configuration. In MSBuild 2.0, this project file would look like the following:
 
 > [!NOTE]
 > In the following example, "..." represents additional solution files.
@@ -86,7 +86,7 @@ Builds MSBuild projects from another MSBuild project.
 </Project>
 ```
 
- By using the Properties metadata, however, you can simplify this to use a single [MSBuild task](../msbuild/msbuild-task.md), as shown by the following:
+ By using the Properties metadata, however, you can simplify this code to use a single [MSBuild task](../msbuild/msbuild-task.md), as shown by the following example:
 
 ### a.proj
 
@@ -125,7 +125,7 @@ Builds MSBuild projects from another MSBuild project.
 
 ## AdditionalProperties metadata
 
- Consider the following scenario where you are building two solution files using the [MSBuild task](../msbuild/msbuild-task.md), both using the Release configuration, but one using the x86 architecture and the other using the ia64 architecture. In MSBuild 2.0, you would need to create multiple instances of the [MSBuild task](../msbuild/msbuild-task.md): one to build the project using the Release configuration with the x86 Architecture, the other using the Release configuration with the ia64 architecture. Your project file would look like the following:
+ Consider the following scenario where you're building two solution files using the [MSBuild task](../msbuild/msbuild-task.md), both using the Release configuration, but one using the x86 architecture and the other using the ia64 architecture. In MSBuild 2.0, you would need to create multiple instances of the [MSBuild task](../msbuild/msbuild-task.md): one to build the project using the Release configuration with the x86 Architecture, the other using the Release configuration with the ia64 architecture. Your project file would look like the following:
 
 ### a.proj