Handler deprecation/versioning strategy

[PureWeen]

Description

A number of scenarios can occur that require us to move to new handlers. There are cases where the platform owners (iOS/Android/WinUI) will introduce new controls that users want to use. Sometimes we are forced to migrate to these new controls in order for Apple to continue letting users publish to the store. For example, in Xamarin.Forms we had to remove all references to UIWebView and recently we modified all of our Android input fields to inherit from a specific base class otherwise Android would stop lettings us published to the store. We try not to break users in unexpected and undesirable ways but in order for the platform to evolve and for apps to continue functioning we have to deprecate and sometimes remove.

General strategy

The current plan will be to follow a similar pattern as windows and just append an incrementing number to new handlers. If we migrate one platform to Handler2 we will create a Handler2 version on all platforms. The Handler and Handler2 for the untouched platforms will retain the same behavior as one another. Example can be seen here.

If we were to only migrate the Windows handler to Handler2 that would make the xplat APIs confusing

#if WINDOWS
     SwipeViewHandler2.Mapper
#else     
     SwipeViewHandler.Mapper
#endif

vs

     SwipeViewHandler2.Mapper

How do I opt in for these new handlers?

By default, users will need to opt-in to the new handlers. The mechanisms around this still need to be discussed, but it will almost definitely be some sort of builder extension method.

builder.UseMaui<App>()
           .UseLatestFeatures()

We can possibly break this out to specific handlers as well for discovery purposes. This also lets us document the extension method itself to indicate what opting into this handler includes.

builder.UseMaui<App>()
           .UseButtonHandler2()

Users can also manually opt into the new handlers through handler registration

builder.UseMaui<App>()
           .ConfigureMauiHandlers(handlers =>
           {
                      handlers.AddHandler<SwipeView, SwipeViewHandler2>
           });

If users only want to opt into the new handler on a single platform they can. If they have a lot of code written against SwipeViewHandler.Mapper on Android and only care about updating Windows. Or maybe we've changed SwipeViewHandler on two platforms but they only want to opt into the Windows one.

builder.UseMaui<App>()
#if WINDOWS
           .UseButtonHandler2()
#endif

or

builder.UseMaui<App>()
           .ConfigureMauiHandlers(handlers =>
           {
#if WINDOWS
                      handlers.AddHandler<SwipeView, SwipeViewHandler2>
#endif
           });

Additional Notes

• New handlers will not inherit from the previous handlers. There should be nothing that connects the two handlers together. Each handler should be able to exist independently of each other.
• Handler interfaces will not implement previous versions
  • With windows, numbered interfaces are used to add behavior, but for this scenario we are implementing a completely new handler. ISwipeViewHandler and ISwipeViewHandler2 will have no overlap. We need to be able to delete ISwipeViewHandler without breaking ISwipeViewHandler2

Alternate suggestion to Handler<Num>

Associate handlers with the .NET release they were implemented in. This gives a bit of clarity to where the handlers came into existence but could also lead to a number of confusions

Cons:

• We may have issues figuring out what handlers are actually being used as technically any library can request v1 or v2 at any point during the setup.
• If we have a net8 namespace, people may not think that net8 works in net9 or expect all versions of handlers to have a related namespace.
• There may be code ambiguity as depending on who/what adds a namespace the type is the same yet is actually different - further aggravated with the VS IDE adding random namespaces in a copy-paste.

Obsoleting Handlers

These scenarios will be a bit case by case.

Platform forces us to deprecate delete

There are some cases where the platform (iOS, Android) forces our hand, and we have to delete/break code based on the requirements of those platforms.

Platform offers a new control

As the platforms themselves evolve new types of controls are created for existing UI concepts (i.e. datepickers, timepickers, entries, etc...). In order for us to stay current we need to provide users with the most modern experience. The timeline of deprecating/deleting older handlers here will depend on the requirements of the platform. If enough time has passed and the old version of a DatePicker is no longer recommended or used by Apple then we will stop actively maintaining and remove the Handler

We've implemented what we feel is a better version then what the platform offers

These cases will most likely be pretty rare as it's a lot of work to maintain custom built controls. One scenario that's currently active is the SwipeView control https://github.com/dotnet/maui/pull/11229. We have a custom implementation that enables mouse interactions. If we pull this PR in, we will most likely need to maintain both handlers for some time until we can confidently say that the new implementation is a 100 percent accurate stand in for the obsolete handler. There is a decent change that when this happens, we will be maintaining both handlers for a number of years.

Will you ever delete handlers?

If we've deemed that users need to move all new code to a new handler, then we will obsolete the old handler for a major release cycle to allow time to migrate and then remove the handler.

Current optimism indicates that we will move any obsolete handlers to Compatibility unless it's a scenario where the platform is no longer compatible with that Handler. For example, on Android you're required to implement AppCompatEditText so if we had any handlers that weren't using AppCompatEditText we would just delete these because our hand is forced by Google.

Examples

Currently we have a PR to implement a new SwipeViewHandler https://github.com/dotnet/maui/pull/11229 that is custom built and enables more features than the WinUI SwipeView. Once/if the new handler reaches 100 percent feature parity with SwipeViewHandler then we can obsolete SwipeViewHandler

[ghost]

We've added this issue to our backlog, and we will work to address it as time and resources allow. If you have any additional information or questions about this issue, please leave a comment. For additional info about issue management, please read our Triage Process.

[dersia]

Is there a reason why we can't use V1, V2, V3 namespaces? I really don't like the SwipeView2 approach because it is ugly and it does not allow for a real type SwipeView2 to exists (let's say this one has a two way swipe, left right, up down). I also thing that users new to the platform or coming from not windows platforms might not understand, than it is an evolution, where as V2 is something that users from any platform will see as a Version 2 and therefor as an evolution.

[juwens]

Just imagine, what amount of effort could be saved for the Maui team, and also for developers using MAUI, if they switch to drawn controls. Not constantly needing to adjust to changed platform controls or incomplete/buggy handlers. Simply continuously improving/enhancing existing controls. If only there would be a person at MSFT who peruses this goal and created a prototype.

Details

https://github.com/dotnet/Microsoft.Maui.Graphics.Controls

[brabebhin]

I also find it strange using 2, 3 etc for new handlers. Iirc, the pattern in windows is used for interfaces adding new features to a class, rather than adding new classes (so you have the same class X that implements ix1, ix2 etc in newer versions). I never seen anyone use ListView2 in a ui, for instance. Not sure if that's even a thing.

I do agree that having a custom renderer would fix so many of maui's issues. Who knows, maybe in maui2 or maui3...

I don't think users should be forced into opting in for the latest handlers. It should be the other way around.

[Xyncgas]

I agree with @juwens, in my experience of developing in blazor, the browser is like one big collection of drawn UI I don't have to deal with a lot of the things I dealt with in xamarin

[mattleibow]

Drawn UI is great, but it is semi expensive but then there is the 50% of people who want native. No matter what we do, unless we have a drawn UI for each OS and keep up with os changes, 50% will be unhappy. We probably need both as always.

[Xyncgas]

Maybe there is shouldn't be one way to code UI, some wants native some wants framework pretending to be native so there is greater abstractions and consistencies, I agree making MAUI work is more important on making every feature supported

[juwens]

Drawn UI is great, but it is semi expensive but then there is the 50% of people who want native. No matter what we do, unless we have a drawn UI for each OS and keep up with os changes, 50% will be unhappy. We probably need both as always.

I have the impression, that:

• Devs which want a native UI use the native bindings, without forms.
• And devs who use forms, want a UI which works on all platforms without endless hassle.

[Dreamescaper]

You probably need to think how to be able to "freeze" handler versions during the project creation. I.e. when I create a project, the latest recommended handlers should be used (not simply a V1). But when a new handler version is released, previously created project shouldn't migrate there automatically (therefore you can't simply use UseLatestFeatures in the project template).

[rctec-at]

How do users know what handler versions are available, and what versions should be used?