Add three new properties (#31967)

Author: gewarren

docs/core/project-sdk/msbuild-props.md

@@ -1,7 +1,7 @@
 ---
 title: MSBuild properties for Microsoft.NET.Sdk
 description: Reference for the MSBuild properties and items that are understood by the .NET SDK.
-ms.date: 05/24/2022
+ms.date: 10/21/2022
 ms.topic: reference
 ms.custom: updateeachrelease
 ---
@@ -462,6 +462,7 @@ The following MSBuild properties are documented in this section:
 - [DocumentationFile](#documentationfile)
 - [EmbeddedResourceUseDependentUponConvention](#embeddedresourceusedependentuponconvention)
 - [EnablePreviewFeatures](#enablepreviewfeatures)
+- [EnableWindowsTargeting](#enablewindowstargeting)
 - [GenerateDocumentationFile](#generatedocumentationfile)
 - [GenerateRequiresPreviewFeaturesAttribute](#generaterequirespreviewfeaturesattribute)
 - [OptimizeImplicitlyTriggeredBuild](#optimizeimplicitlytriggeredbuild)
@@ -484,21 +485,21 @@ This property was introduced in .NET SDK 7.0.100, though it defaults to not bein
 
 The `DisableImplicitFrameworkDefines` property controls whether or not the SDK generates preprocessor symbols for the target framework and platform for the .NET project. When this property is set to `false` or is unset (which is the default value) preprocessor symbols are generated for:
 
-* Framework without version (`NETFRAMEWORK`, `NETSTANDARD`, `NET`)
-* Framework with version (`NET48`, `NETSTANDARD2_0`, `NET6_0`)
-* Framework with version minimum bound (`NET48_OR_GREATER`, `NETSTANDARD2_0_OR_GREATER`, `NET6_0_OR_GREATER`)
+- Framework without version (`NETFRAMEWORK`, `NETSTANDARD`, `NET`)
+- Framework with version (`NET48`, `NETSTANDARD2_0`, `NET6_0`)
+- Framework with version minimum bound (`NET48_OR_GREATER`, `NETSTANDARD2_0_OR_GREATER`, `NET6_0_OR_GREATER`)
 
 For more information on target framework monikers and these implicit preprocessor symbols, see [Target frameworks](../../standard/frameworks.md).
 
 Additionally, if you specify an operating system-specific target framework in the project (for example `net6.0-android`), the following preprocessor symbols are generated:
 
-* Platform without version (`ANDROID`, `IOS`, `WINDOWS`)
-* Platform with version (`IOS15_1`)
-* Platform with version minimum bound (`IOS15_1_OR_GREATER`)
+- Platform without version (`ANDROID`, `IOS`, `WINDOWS`)
+- Platform with version (`IOS15_1`)
+- Platform with version minimum bound (`IOS15_1_OR_GREATER`)
 
 For more information on operating system-specific target framework monikers, see [OS-specific TFMs](../../standard/frameworks.md#net-5-os-specific-tfms).
 
-Finally, if your target framework implies support for older target frameworks, preprocessor symbols for those older frameworks are emitted. For example, `net6.0` **implies** support for `net5.0` and so on all the way back to `.netcoreapp1.0`. So for each of these target frameworks, the _Framework with version minimum bound_ symbol will be defined.
+Finally, if your target framework implies support for older target frameworks, preprocessor symbols for those older frameworks are emitted. For example, `net6.0` **implies** support for `net5.0` and so on all the way back to `.netcoreapp1.0`. So for each of these target frameworks, the *Framework with version minimum bound* symbol will be defined.
 
 ### DocumentationFile
 
@@ -547,6 +548,16 @@ An analyzer warns if this attribute is present on dependencies for projects wher
 
 Library authors who intend to ship preview assemblies should set this property to `True`. If an assembly needs to ship with a mixture of preview and non-preview APIs, see the [GenerateRequiresPreviewFeaturesAttribute](#generaterequirespreviewfeaturesattribute) section below.
 
+### EnableWindowsTargeting
+
+Set the `EnableWindowsTargeting` property to `true` to build Windows apps (for example, Windows Forms or Windows Presentation Foundation apps) on a non-Windows platform. If you don't set this property to `true`, you'll get build warning [NETSDK1100](../tools/sdk-errors/netsdk1100.md). This error occurs because targeting and runtime packs aren't automatically downloaded on platforms that aren't supported. By setting this property, those packs are downloaded when cross-targeting.
+
+```xml
+<PropertyGroup>
+  <EnableWindowsTargeting>true</EnableWindowsTargeting>
+</PropertyGroup>
+```
+
 ### GenerateDocumentationFile
 
 The `GenerateDocumentationFile` property controls whether the compiler generates an XML documentation file for your library. If you set this property to `true` and you don't specify a file name via the [DocumentationFile property](#documentationfile), the generated XML file is placed in the same output directory as your assembly and has the same file name (but with an *.xml* extension).
@@ -976,14 +987,16 @@ The `TieredCompilationQuickJitForLoops` property configures whether the JIT comp
 </PropertyGroup>
 ```
 
-## Reference properties
+## Reference-related properties
 
 The following MSBuild properties are documented in this section:
 
 - [AssetTargetFallback](#assettargetfallback)
 - [DisableImplicitFrameworkReferences](#disableimplicitframeworkreferences)
+- [DisableTransitiveFrameworkReferenceDownloads](#disabletransitiveframeworkreferencedownloads)
 - [DisableTransitiveProjectReferences](#disabletransitiveprojectreferences)
 - [Restore-related properties](#restore-related-properties)
+- [UseMauiEssentials](#usemauiessentials)
 - [ValidateExecutableReferencesMatchSelfContained](#validateexecutablereferencesmatchselfcontained)
 
 ### AssetTargetFallback
@@ -1010,6 +1023,16 @@ Set this property to `true` to disable implicit `FrameworkReference` or [Package
 </PropertyGroup>
 ```
 
+### DisableTransitiveFrameworkReferenceDownloads
+
+Set the `DisableTransitiveFrameworkReferenceDownloads` property to `true` to avoid downloading extra runtime and targeting packs that aren't directly referenced by your project.
+
+```xml
+<PropertyGroup>
+  <DisableTransitiveFrameworkReferenceDownloads>true</DisableTransitiveFrameworkReferenceDownloads>
+</PropertyGroup>
+```
+
 ### DisableTransitiveProjectReferences
 
 The `DisableTransitiveProjectReferences` property controls implicit project references. Set this property to `true` to disable implicit `ProjectReference` items. Disabling implicit project references results in non-transitive behavior similar to the [legacy project system](https://github.com/dotnet/project-system/blob/main/docs/feature-comparison.md).
@@ -1034,6 +1057,16 @@ Restoring a referenced package installs all of its direct dependencies and all t
 </PropertyGroup>
 ```
 
+### UseMauiEssentials
+
+Set the `UseMauiEssentials` property to `true` to declare an explicit reference to a project or package that depends on MAUI Essentials. This setting ensures that your project pulls in the correct known framework reference for MAUI Essentials. If your project references a project that uses MAUI Essentials but you don't set this property to `true`, you might encounter build warning `NETSDK1186`.
+
+```xml
+<PropertyGroup>
+  <UseMauiEssentials>true</UseMauiEssentials>
+</PropertyGroup>
+```
+
 ### ValidateExecutableReferencesMatchSelfContained
 
 The `ValidateExecutableReferencesMatchSelfContained` property can be used to disable errors related to executable project references. If .NET detects that a self-contained executable project references a framework-dependent executable project, or vice versa, it generates errors NETSDK1150 and NETSDK1151, respectively. To avoid these errors when the reference is intentional, set the `ValidateExecutableReferencesMatchSelfContained` property to `false`.

docs/core/tools/dependencies.md

@@ -70,5 +70,5 @@ dotnet remove package Microsoft.EntityFrameworkCore
 
 ## See also
 
-* [Package references in project files](../project-sdk/msbuild-props.md#reference-properties)
+* [Package references in project files](../project-sdk/msbuild-props.md#reference-related-properties)
 * [dotnet list package command](dotnet-list-package.md)

docs/core/tools/sdk-errors/netsdk1100.md

@@ -26,4 +26,8 @@ To resolve this error, set the `EnableWindowsTargeting` property to true. You ca
 
 If you want to apply this setting to your whole solution or repository, you can set it in a *Directory.Build.props* file.
 
-By default, .NET downloads all targeting packs (and runtime packs for self-contained builds) for the current target framework whether they're needed or not, because they might be brought in by a transitive framework reference. We didn't want to ship the Windows targeting packs with the non-Windows SDK builds, but we also didn't want a vanilla Console or ASP.NET Core app to automatically download these targeting and runtime packs the first time you build. The `EnableWindowsTargeting` property enables them to only be downloaded if you opt in.
+By default, .NET downloads all targeting packs (and runtime packs for self-contained builds) for the current target framework whether they're needed or not, because they might be brought in by a transitive framework reference. We didn't want to ship the Windows targeting packs with the non-Windows SDK builds, but we also didn't want a vanilla Console or ASP.NET Core app to automatically download these targeting and runtime packs the first time you build. The `EnableWindowsTargeting` property enables them to be downloaded only if you opt in.
+
+## See also
+
+- [EnableWindowsTargeting property](../../project-sdk/msbuild-props.md#enablewindowstargeting)