Skip to content

Add three new properties #31967

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 24, 2022
Merged

Add three new properties #31967

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ea9aff3
add three new properties
gewarren Oct 21, 2022
fdb9ca8
add indexes
gewarren Oct 21, 2022
a85a7b1
fix bookmark
gewarren Oct 21, 2022
0b4b246
Apply suggestions from code review
gewarren Oct 24, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 42 additions & 9 deletions docs/core/project-sdk/msbuild-props.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---
Expand Down Expand Up @@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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
Expand All @@ -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).
Expand All @@ -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`.
Expand Down
2 changes: 1 addition & 1 deletion docs/core/tools/dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
6 changes: 5 additions & 1 deletion docs/core/tools/sdk-errors/netsdk1100.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)