Merge pull request #10756 from ghogen/issue-8733

MSBuild: Add coverage of certain properties

Author: prmerger-automator[bot]

docs/msbuild/common-msbuild-project-properties.md

@@ -58,6 +58,8 @@ The following table lists frequently used properties that are defined in the Vis
 | DefineTrace | All | A boolean value that indicates whether you want the TRACE constant defined. |
 | DelaySign | .NET | A boolean value that indicates whether you want to delay-sign the assembly rather than full-sign it. |
 | Deterministic | .NET | A boolean value that indicates whether the compiler should produce identical assemblies for identical inputs. This parameter corresponds to the `/deterministic` switch of the compilers. |
+| DirectoryBuildPropsPath | All | Specifies the path to the *Directory.Build.props* file; if defined, this property overrides the default search algorithm. See [Customize your build](customize-your-build.md#directorybuildprops-and-directorybuildtargets). |
+| DirectoryBuildTargetsPath| All | Specifies the path to the *Directory.Build.targets* file; if defined, this property overrides the default search algorithm. See [Customize your build](customize-your-build.md#directorybuildprops-and-directorybuildtargets). |
 | DisableFastUpToDateCheck | All | A boolean value that applies to Visual Studio only. The Visual Studio build manager uses a process called FastUpToDateCheck to determine whether a project must be rebuilt to be up to date. This process is faster than using MSBuild to determine this. Setting the DisableFastUpToDateCheck property to `true` lets you bypass the Visual Studio build manager and force it to use MSBuild to determine whether the project is up to date. |
 | DocumentationFile | .NET | The name of the file that is generated as the XML documentation file. This name includes only the file name and has no path information. |
 | ErrorReport | .NET | Specifies how the compiler task should report internal compiler errors. Valid values are "prompt," "send," or "none." This property is equivalent to the `/errorreport` compiler switch. |
@@ -67,6 +69,8 @@ The following table lists frequently used properties that are defined in the Vis
 | GenerateDocumentation | .NET | A boolean parameter that indicates whether documentation is generated by the build. If `true`, the build generates documentation information and puts it in an *.xml* file together with the name of the executable file or library that the build task created. |
 | GenerateFullPaths | C# | Generate full paths for filenames in output by using the [-fullpaths](/dotnet/csharp/language-reference/compiler-options/fullpaths-compiler-option) compiler option. |
 | GenerateSerializationAssemblies | .NET | Indicates whether XML serialization assemblies should be generated by *SGen.exe*, which can be set to on, auto, or off. This property is used for assemblies that target .NET Framework only. To generate XML serialization assemblies for .NET Standard or .NET Core assemblies, reference the *Microsoft.XmlSerializer.Generator* NuGet package. |
+| ImportDirectoryBuildProps | All | A boolean value that indicates whether to import a *Directory.Build.props* file. See [Customize your build](customize-your-build.md#directorybuildprops-and-directorybuildtargets).|
+| ImportDirectoryBuildTargets | All | A boolean value that indicates whether to import a *Directory.Build.targets* file. See [Customize your build](customize-your-build.md#directorybuildprops-and-directorybuildtargets). |
 | IntermediateOutputPath | All | The full intermediate output path as derived from `BaseIntermediateOutputPath`, if no path is specified. For example, *obj\debug\\*. |
 | KeyContainerName | All | The name of the strong-name key container. |
 | KeyOriginatorFile | All | The name of the strong-name key file. |

docs/msbuild/customize-your-build.md

@@ -106,10 +106,13 @@ A summary of MSBuild's general approach is as follows:
 - For any given project, MSBuild finds the first *Directory.Build.props* upward in the solution structure, merges it with defaults, and stops scanning for more.
 - If you want multiple levels to be found and merged, then [`<Import...>`](../msbuild/property-functions.md#msbuild-getpathoffileabove) (shown above) the "outer" file from the "inner" file.
 - If the "outer" file does not itself also import something above it, then scanning stops there.
-- To control the scanning/merging process, use `$(DirectoryBuildPropsPath)` and `$(ImportDirectoryBuildProps)`.
 
 Or more simply: the first *Directory.Build.props* that doesn't import anything is where MSBuild stops.
 
+To control the import process more explicitly, use the properties `$(DirectoryBuildPropsPath)`, `$(ImportDirectoryBuildProps)`, `$(DirectoryBuildTargetsPath)`, and `$(ImportDirectoryBuildTargets)`. The property `$(DirectoryBuildPropsPath)` specifies the path to the `Directory.Build.props` file to use; similarly, `$(DirectoryBuildTargetsPath)` specifies the path to the `Directory.Build.targets` file.
+
+The Boolean properties `$(ImportDirectoryBuildProps)` and `$(ImportDirectoryBuildTargets)` are set to `true` by default, so MSBuild normally searches for these files, but you can set them to `false` to prevent MSBuild from importing them.
+
 ### Choose between adding properties to a .props or .targets file
 
 MSBuild is import-order dependent, and the last definition of a property (or a `UsingTask` or target) is the definition used.