Skip to content

In <PackageReference Condition/> docs, mention IsTargetFrameworkCompatible #3432

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

In <PackageReference Condition/> docs, mention IsTargetFrameworkCompatible #3432

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
09c384b
In `<PackageReference Condition/>` docs, mention `IsTargetFrameworkCo…
YoshiRulz May 19, 2025
8e2c834
Also link to `IsTargetFrameworkCompatible`'s documentation
YoshiRulz May 19, 2025
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
14 changes: 14 additions & 0 deletions docs/consume-packages/Package-References-in-Project-Files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,20 @@ Conditions can also be applied at the `ItemGroup` level and will apply to all ch
</ItemGroup>
```

When you have many targets, it may be better to match ranges of TFMs, in which case you can use `IsTargetFrameworkCompatible`:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we link to https://learn.microsoft.com/en-us/visualstudio/msbuild/property-functions?view=vs-2022#msbuild-targetframework-and-targetplatform-functions as well?
https://github.com/NuGet/docs.microsoft.com-nuget?tab=readme-ov-file#links

It's worth noting that the more complicated the conditions are, the more challenging it is for any tooling to update these correctly.
I'd consider these to be advanced scenarios, so my suggestion would be to call them out as such.

```xml
<ItemGroup>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The 3 examples are pretty equivalent.

They're all showing the usage of IsTargetFrameworkCompatible with negation.
I think it'll be easier for the reader if they were to see one example.

<!-- reference 8.0 System.Text.Json when targeting things older than .NET 8 -->
<PackageReference Include="System.Text.Json" Version="8.0.5" Condition=" !$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0')) " />
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is probably me overthinking it because of https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#prunepackagereference, but the idea is that we generally want to make sure people are not referencing platform packages unless they're absolutely required.
For example, there's many System.Text.Json references when customers target .NET and that's unnecessary.

So I'm thinking that we can maybe use a Contoso named package, or if we're sticking with System.Text.Json we can use: GetTargetFrameworkIdentifier.

Maybe we end up with 2 examples, 1 using IsTargetFrameworkCompatible, while the other one uses GetTargetFrameworkIdentifier

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As in $([MSBuild]::GetTargetFrameworkIdentifier('$(TargetFramework)')) != '.NETCoreApp'?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the .NET SDK sets property TargetFrameworkIdentifier, and MSBuild evaluates properties top to bottom before items, doing a TFI condition is easier by using Condition=" '$(TargetFrameworkIdentifier)' != '.NETCoreApp' ", rather than calling the instrinsic function and passing the target framework as an argument.


<!-- reference 10.0 System.Linq.AsyncEnumerable when targeting things older than .NET 10 -->
<PackageReference Include="System.Linq.AsyncEnumerable" Version="10.0.0-preview.2.25163.2" Condition=" !$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net10.0')) " />

<!-- Reference System.Memory on frameworks not compatible with .NET Core 2.1 nor .NETStandard 2.1 -->
<PackageReference Include="System.Memory" Condition=" !($([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'netcoreapp2.1')) OR $([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'netstandard2.1'))) " />
</ItemGroup>
```

## GeneratePathProperty

This feature is available with NuGet **5.0** or above and with Visual Studio 2019 **16.0** or above.
Expand Down