From ea9aff3b7836fcaa153bce54a41841ceed89fe29 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 21 Oct 2022 15:02:22 -0700 Subject: [PATCH 1/4] add three new properties --- docs/core/project-sdk/msbuild-props.md | 49 +++++++++++++++++++----- docs/core/tools/sdk-errors/netsdk1100.md | 6 ++- 2 files changed, 45 insertions(+), 10 deletions(-) diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index 5df756d6bb6b9..b119a4612cf0b 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/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 + + true + +``` + ### 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,7 +987,7 @@ The `TieredCompilationQuickJitForLoops` property configures whether the JIT comp ``` -## Reference properties +## Reference-related properties The following MSBuild properties are documented in this section: @@ -1010,6 +1021,16 @@ Set this property to `true` to disable implicit `FrameworkReference` or [Package ``` +### DisableTransitiveFrameworkReferenceDownloads + +Set the `DisableTransitiveFrameworkReferenceDownloads` property to `true` to avoid downloading extra runtime and targeting packs that your project doesn't need. + +```xml + + true + +``` + ### 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 +1055,16 @@ Restoring a referenced package installs all of its direct dependencies and all t ``` +### UseMauiEssentials + +Set the `UseMauiEssentials` property to `true` to declare an explicit reference to a project or package that depends on MAUI Essentials. This setting ensure that your project correctly 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 + + true + +``` + ### 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`. diff --git a/docs/core/tools/sdk-errors/netsdk1100.md b/docs/core/tools/sdk-errors/netsdk1100.md index b22283ad3041e..6573eda3f5c66 100644 --- a/docs/core/tools/sdk-errors/netsdk1100.md +++ b/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) From fdb9ca846b51d1d98067759521294505053a11ab Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 21 Oct 2022 15:04:34 -0700 Subject: [PATCH 2/4] add indexes --- docs/core/project-sdk/msbuild-props.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index b119a4612cf0b..d2af29efcf913 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -993,8 +993,10 @@ 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 From a85a7b1251cd24689ddbfe40315759aac55b5b7e Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 21 Oct 2022 15:27:35 -0700 Subject: [PATCH 3/4] fix bookmark --- docs/core/tools/dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/dependencies.md b/docs/core/tools/dependencies.md index 5e6f95e598439..13c161b61fc43 100644 --- a/docs/core/tools/dependencies.md +++ b/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) From 0b4b24662707cf6df13ea43e5caeace61f06a9f8 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 24 Oct 2022 08:54:58 -0700 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Daniel Plaisted Co-authored-by: Tom Dykstra --- docs/core/project-sdk/msbuild-props.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index d2af29efcf913..230e6e286a871 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -1025,7 +1025,7 @@ Set this property to `true` to disable implicit `FrameworkReference` or [Package ### DisableTransitiveFrameworkReferenceDownloads -Set the `DisableTransitiveFrameworkReferenceDownloads` property to `true` to avoid downloading extra runtime and targeting packs that your project doesn't need. +Set the `DisableTransitiveFrameworkReferenceDownloads` property to `true` to avoid downloading extra runtime and targeting packs that aren't directly referenced by your project. ```xml @@ -1059,7 +1059,7 @@ Restoring a referenced package installs all of its direct dependencies and all t ### UseMauiEssentials -Set the `UseMauiEssentials` property to `true` to declare an explicit reference to a project or package that depends on MAUI Essentials. This setting ensure that your project correctly 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`. +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