Different default values of TargetPlatformVersions for the Class Library (26.0) and Exe (26.2)

[snechaev]

Apple platform

macOS

Framework version

net10.0-*

Affected platform version

.net 10.0.201 / macos workload 26.2.10217/10.0.100

Description

I tried to move simple code var opts = new NSBindingOptions(); from the Exe project to the Class Library project. Both projects are fresh net10.0-macos projects after dotnet new.
Exe project with this code compiles and runs without problems.
Library project won't compile: Error CS0246 : The type or namespace name 'NSBindingOptions' could not be found.
After short investigation I realized that there are different TargetPlatformVersions calculated for the projects

• for Exe TargetPlatformVersions=26.2
• for Library TargetPlatformVersions=26.0

The NSBindingOptions bindings was added in the 26.2 SDK, so it become clear why the library project won't compile. But it is not clear why we get different values of the TargetPlatformVersions without any visible differences in the projects configuration.

Steps to Reproduce

• Grab test solution test.zip
  • test code contained in the ViewController.cs and Class1.cs
• build exe project dotnet build ./macOsApp - success.
• build lib project dotnet build ./lib - error CS0246: The type or namespace name 'NSBindingOptions' could not be found

Expected: uniform behavior. Either both projects succeed or both fail.

Did you find any workaround?

Workaround: explicitly set tfm=net10.0-macos26.2 for the class library project.

Build logs

See the test.zip inside per-project folders.

[rolfbjarne]

This is by design, but it's admittedly somewhat confusing.

The default TargetPlatformVersion for executable projects is the last version that's supported by the current workload (so iOS 26.2 for the last iOS workload). This is so that you always build your app with the latest version of Xcode - otherwise everybody would have to change TargetPlatformVersion to do that (few people wants to build their .NET 9 projects with Xcode 18.0 and the iOS 18.0 SDK - which is what was the initial TargetPlatformVersion when .NET 9 was released).

On the other hand, TargetPlatformVersion for library projects is the earliest version that is supported for a given .NET version - that's iOS 26.0 for .NET 10, because library developers typically don't need Xcode to build their projects, and also they desire maximum compatibility for their libraries.

See #21343 for more information.

This is documented here: https://learn.microsoft.com/en-us/dotnet/standard/frameworks#os-version-in-tfms (scroll down a bit for a purple-ish "Note" box)

[snechaev]

Thank you for the clarification! I apologize for overlooking that note in the docs.

May I ask about the best practices for project configuration in the context of this behavior?

I understand the decision to use the oldest TargetPlatformVersion for libraries. However, in my particular case, the libraries are used simply to share code between projects in the same solution (meaning the libraries will not be distributed as independent products). Therefore, it is guaranteed that the libraries and their consuming executable projects will always share the same environment.

Because of this, I am interested in targeting the class libraries to the newest macOS version supported by the current workload (while keeping compatibility with older macOS versions like 15.0-26.2). This would allow me to use the latest APIs and align the API surface between the executables and library projects.

Right now, I see the following options:

• Explicitly set TargetFramework=net10.0-macos26.2 or TargetPlatformVersion=26.2 per-project or in Directory.Build.props. It works, but it requires manually updating the version after each workload update, which is not ideal.
• Use the _XamarinTargetPlatformVersionExecutable property from Xamarin.Shared.Sdk.TargetFrameworkInference.props (e.g., <TargetPlatformVersion>$(_XamarinTargetPlatformVersionExecutable)</TargetPlatformVersion>). This doesn't seem to work directly (perhaps due to the order of <Import/> statements?), and anyway, relying on non-public MSBuild properties is against best practices and is fragile and unreliable.

Can you please advise if there is a better way to switch libraries to the latest TargetPlatformVersion without this manual housekeeping and versions sync? Thank you!

[rolfbjarne]

Can you please advise if there is a better way to switch libraries to the latest TargetPlatformVersion without this manual housekeeping and versions sync? Thank you!

Yes, there is!

You can set the property UseFloatingTargetPlatformVersion=true to get the behavior you want: https://learn.microsoft.com/en-us/dotnet/ios/building-apps/build-properties#usefloatingtargetplatformversion