Xamarin.Forms 5.0.0.2662 (5.0.0) Release Notes

  • Article

Getting Started | What's New | Known Issues | Breaking Changes | API Changes | Blogs | Thank you | Reporting Issues | Open Source

Upgrading to Xamarin.Forms 5.0

Xamarin.Forms 5 brings to stable release several new controls and features including App Themes (Dark Mode), Brushes, CarouselView, RadioButton, Shapes and Paths, and SwipeView.

As you upgrade your applications to Xamarin.Forms 5, there are some changes and removals to be aware of. Below is an itemized list:

Dependency Requirements

  • Android 13 or greater should be your Target Framework
  • AndroidX is now the default for Xamarin.Forms. For guidance migration from Android Support to AndroidX, visit our documentation here.

Visual Studio 2017 No Longer Supported

Updates to Android and iOS are only delivered to Visual Studio 2019 and higher, and these are fundamental for getting the latest platform security fixes features required by Apple and Google. Before updating to Xamarin.Forms 5, install Visual Studio 2019 or higher.

MasterDetailPage Renamed

MasterDetailPage has been renamed to FlyoutPage. This change is in accordance with our values of diversity and inclusivity. We previously renamed our master branch on GitHub to main. The name also more closely reflects the behavior of the control. It is also in keeping with how we describe the behavior in Shell.

What should I do after upgrading?

This is a deprecation, so your app will work as before. To adopt this change, we recommend you rename MasterDetailPage in your projects to FlyoutPage. A few other types and property names have been updated as well including:

  • MasterDetailPage.Master changed to FlyoutPage.Flyout
  • MasterBehavior changed to FlyoutLayoutBehavior

RadioButton Changes

RadioButton now supports setting any content and using control templates. You can start with simple text:

<StackLayout 
    RadioButtonGroup.GroupName="SimpleRadios"
    Orientation="Horizontal">
    <RadioButton Content="Day"/>
    <RadioButton Content="Week"/>
    <RadioButton Content="Month"/>
</StackLayout>

And add more complex UI to match your design needs:

<RadioButton 
    ControlTemplate="{StaticResource 
                        CalendarRadioTemplate}">
    <RadioButton.Content>
        <StackLayout 
            HorizontalOptions="Center" 
            VerticalOptions="Center">
            <Image
                Source="{FontImage FontFamily=FontAwesome, 
                        Glyph={x:Static local:IconFont.CalendarDay}, 
                        Color=#323130,Size=32}"/>
            <Label Text="Day" TextColor="#323130"/>
        </StackLayout>
    </RadioButton.Content>
</RadioButton>

A sample control template XAML is here.

RadioButtons image

UIWebView Removed

UIWebView has been completely removed. Since March, Apple has been warning that usage of this control was deprecated and apps would be rejected beginning later in the year. Since 4.x, we switched the default usage in Xamarin.Forms to WKWebView, and in 4.6, we made it possible to remove the UIWebView renderer to avoid Apple's review process from flagging apps as violating their policy. Still, third-party projects may still make use of UIWebView and trigger the violation. Now it is completely gone, and we recommend all libraries to make sure to switch to WKWebView as well.

What should I do after upgrading?

If you don't have a known need for UIWebView, then you don't need to do anything. For anyone else, the renderer code is available on GitHub to be copied into our application source.

C# UI, Expander, and MediaElement Moved

These experimental features have been migrated to the Xamarin Community Toolkit which everyone should be taking full advantage of. It's a wonderful library of extremely useful Xamarin controls, effects, value converters, and more. In fact, it even has a native CameraView, Avatar view, and RangeSlider control. These features and controls are continuing to grow and improve, and while Xamarin.Forms moves into an extended stable release, we feel it's better for those to ship for now in the toolkit. At a future time, they may be brought back into the core library.

As a "community" toolkit, it is being maintained and supported by a talented group of both community and Microsoft engineers. A big thanks to the maintainers and contributors of this wonderful library for their hard work.

If you're interested in learning more, check out GitHub and the project's Discord channel.

What should I do after upgrading?

If you have been using these features and controls, then add the latest Xamarin Community Toolkit to your project. After you resolve the new namespaces, your project should once again compile. Any time you update NuGets, you should do a full clean and build.

DataPages and Themes Packages Removed

In Xamarin.Forms 2, before joining Microsoft, we prototyped some interesting ways to build data driven UIs. These experiments were shipped as preview packages called DataPages and Themes. Since then, we have continued shipping the packages, but no work or customer interest has grown around them. Instead, features such as App Themes are much easier to use and implement dark and light mode, as well as general theme support using dynamic styles. As of Xamarin.Forms 5, we will no longer be building and shipping these packages.

What should I do after upgrading?

If you have the packages installed and are not using them, then you can safely remove them.

For themes related usage, migrate your implementation to using dynamic styles and AppThemeBinding.

For anything else, please contact us.

XFCorePostProcessor.Tasks Removed

This project injects IL to maintain XF 2.5 compatibility. We're far enough away from XF 2.5 now that this weaving should no longer be necessary.

What's New in this Release

See the latest Service Release page for detailed information.

Reporting Issues

Your feedback is important to us. If there are any problems with this release, check the Xamarin.Forms Forums and GitHub for existing issues. Report new issues and suggestions on GitHub.

Open Source

Xamarin.Forms 5.0.0 is based on the open-source Xamarin.Forms repository: