Binary Compatibility

[benstevens48]

What is the policy of WindowsAppSDK regarding binary compatibility (I mean using the WinRT API surface), including WinUI? Are new versions always binary compatible with previous versions, like built-in Windows components? Is this limited to 'minor' releases or do 'major' releases follow this as well? For example, if I have a native library complied against WindowsAppSDK 1.4 which uses Microsoft.UI.Xaml types, will that library still work as part of an app that references WindowsAppSDK 1.8? Or WindowsAppSDK 2.0 when released?

[benstevens48]

I'm assuming that it follows the convention that COM interfaces are immutable so binary compatibility is maintained indefinitely, but it would be good to get confirmation.

[DrusTheAxe]

I'm assuming that it follows the convention that COM interfaces are immutable so binary compatibility is maintained indefinitely, but it would be good to get confirmation.

Indefinitely? No. That's not guaranteed, but it's typical. See #6250 (reply in thread)

[benstevens48]

Doesn't the lack of binary compatibility guarantee cause a problem with the fact that WindowsAppSDK is released as NuGet packages (which isn't really designed for native libraries)? I mean if I author a package that depends on WindowsAppSDK and put in on NuGet declaring WindowsAppSDK 1.8 as a dependency, then by default NuGet will accept any higher version of WindowsAppSDK as satisfying that, but if it was not binary compatible with 1.8, couldn't that cause a crash at runtime? Would there be any compile time warning? Or maybe I am misunderstanding what binary compatibility means. I think as long as COM interfaces are immutable this situation should be OK, no? Does WindowsAppSDK not intend to stick to this convention? Do I need to put an upper limit on the NuGet package dependency? I should warn from experience with other ecosystems that once you start putting on upper limits it becomes a bit of a nightmare when library maintainers disappear etc since you end up getting stuck not being able to upgrade.

[DrusTheAxe]

+@Scottj1s

Do I need to put an upper limit on the NuGet package dependency?

That raises interesting questions about Nuget versioning and SemVer. @Scottj1s for authoritative answers on Nuget versioning, SemVer semantics and WinAppSDK's plans.

as long as COM interfaces are immutable this situation should be OK

SemVer doesn't guarantee compatibility across major versions (even if it's typically true).

WinAppSDK manages this in several ways. For one, WinAppSDK's MSIX packages use a different family name for each release e.g. Microsoft.WindowsAppRuntime.1.7 for 1.7.x vs Microsoft.WindowsAppRuntime.1.8 for 1.8.x, and looking forward Microsoft.WindowsAppRuntime.2 for 2.x vs Microsoft.WindowsAppRuntime.3 for 3.x. etc.

I think as long as COM interfaces are immutable this situation should be OK, no? Does WindowsAppSDK not intend to stick to this convention?

You're right at the micro level, but not necessarily at the macro level.

At the micro level, yes. WinAppSDK should never change a interface once shipped (the classic 'once published a COM interface is immutable forever' behavior). But at the macro level, there's no guarantee that interface will be supported in a future release.

(Deprecation and removal and possible, albeit rare)

[Scottj1s]

@benstevens48 Great question. The simplified package version syntax of "x" is shorthand for "[x,)" - no upper bound. Initially, all transitive nuspec references in the Windows App SDK 2.0 collection of packages will impose an upper bound that enforces references within the same major version - "[2.0,3.0)". We may relax this constraint, depending on customer feedback. But we want to avoid the very scenario you're describing - at least falling into it unintentionally.

[benstevens48]

Thanks for the info both. I'm actually talking about authoring a NuGet package that depends on WindowsAppSDK (whether to set an upper bound on that). The case I'm most interested in is Win2D (although I'm maintaining my own fork of this anyway due to lack of official maintenance). I wouldn't expect to have to be limited to using WindowsAppSDK 1.6 just because that's what Win2D is compiled against. From what you said from now on you are guaranteeing being compiled against 2.0 would make it OK for 2.x for any x, but then it may need to be recompiled against 3.0 etc. Although in practice for this to be a problem you would have to remove (or break the implementation of) an interface that Win2D used which seems quite unlikely... But still, technically, Win2D should probably put an upper limit on the WindowsAppSDK version (which of course presents a problem when people want to upgrade beyond that but Win2D is not updated).

[Dreynor87]

WindowsAppRuntime is now promising an ABForward Guarantee(we have not followed this in the past, but we are making a stronger guarantee starting with 2.0), that guarantees that:

1. Anything built on Major version N will run on N-1
2. Anything built on Major version N will run on N+1

Both of those, as long as you only call APIs that existed in the lower of the 2 versions.

This means we can mark something as "deprecated" and tell you what you should use in 1 Major version, but you can still build while calling that API during that version, and you can still even run while calling that API during that version. While in this "deprecated" mode, having the API will give a warning that this is going away, as well as a reference for what you should do instead.

It could actually fully go away in the next Major version. We will make sure to be done in a way that still works with COM, just causes you to not be able to use it anymore.

[benstevens48]

Thanks, this clears things up a bit. One question - would you consider defining a 'Core' set of APIs which will always be supported? So for something like Win2D an upper bound on the WindowsAppSdk.WinUI NuGet dependency is not required? I guess this could tie you down a bit so maybe not... In conclusion, once 2.0 is released, assuming I build Win2D against 2.x, I think what you are saying is it would be safe to specify an upper bound of < 4.0 for WindowsAppSDK.WinUI as a dependency in the Win2D NuGet package? Note that no upper bound has ever been specified in the past so I guess people just didn't think about this.