Difference between revisions of "HowTo:Convert Xamarin XAMLs to Maui"

Revision as of 15:26, 1 August 2025

Information

Frame to Border

Use Border instead of Frame. Frame is deprecated in MAUI. Use Border with `Stroke` instead of `BorderColor`.

LayoutOptions with "...AndExpand"

Replace "...AndExpand" with Grid layout. Horizontal/VerticalOptions ending in "...AndExpand" are deprecated. Use Grid with `ColumnDefinition Width="*"` for expansion.

GlyphLabel and Styles

Use Label with new styles. Custom controls like `GlyphLabel` are no longer needed. Use `Label` with styles like `UBIKSymbolText`.

SfTabView Virtualization

Enable virtualization. Add `EnableVirtualization="True"` to all SfTabView instances or styles.

Swipe Menu Icons on Android

Refactor swipe templates and label styles. Icons in swipe menus were truncated on Android. Fixed via refactoring.

Color Style Changes

Dark theme adjustments. Changes to color styles may affect appearance. Review usage of `UBIKDarkThemeColor`, `UBIKDarkTextColor`, etc.

Strikethrough Converter

Use `TextDecorations="Strikethrough"` instead of converter.

Button Disabled Trigger

Add trigger for disabled buttons. Maui buttons don’t visually change when disabled. Add trigger to style.

TapGestureRecognizer Replacement

Use TappedBehavior instead. TapGestureRecognizer now intercepts taps. Use `TappedBehavior` to avoid conflicts.

TapGestureRecognizer and Swipe Conflict

Remove TapGestureRecognizer from root Grid. TapGestureRecognizer blocks swipe behavior. Remove it and adapt parent list to trigger navigation.

Navigation in UBIKChildItem

Use EventHandlerBehavior for navigation.

Recommended

Extract DataTemplates from UBIKThemes

Create separate .xamlx files for the following DataTemplates. It's not so easy about the namespaces:

• In our default templates, it's enough to add the following ones to every new separate .xamlx files at the beginning;

   * xmlns:ctrls="clr-namespace:UBIK.MAUI.Controls;assembly=UBIK.MAUI";
   * xmlns:platform="clr-namespace:UBIK.MAUI.Platform.Renderers;assembly=UBIK.MAUI";
   * xmlns:resources="clr-namespace:UBIK.MAUI.Resources;assembly=UBIK.MAUI";
   * xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI";
   * xmlns:uiservices="clr-namespace:UBIK.UI.Services;assembly=UBIK.UI".

• But we don't know if other namespaces might be used in the custom templates. So it might be necessary to really analyze the namespaces used and find/copy them from the UBIKThemes file.

VideoPlayer Adjustments

This property is repsonsible for the video player regarding how or if it should get scaled up depending on the value of the Aspect property

The UriToVideoSourceConverter is no longer needed because the conversion of the VideoSource gets done by the MediaElement itself. It is marked as obsolete and should therefore no longer be used.

The StopTimer property is obsolete and no longer needed because the MediaElement behind does the Stop of the VideoPlayer by itself.

SearchBar Style Fix on iOS

On iOS, defining a transparent background for the SearchBar control results in a black text on black background appearance.

Avoid Redundant ControlTemplate in DataTriggers

This is about finding ControlTemplates that are set in DataTriggers in customized Xamls. When the same template is already set as a ContentView default ControlTemplate, it is recommended to remove the default ControlTemplate on the ContentView. For a detailed description please refer to sheet "Mandatory" in cell 27A-27C. Behavior that might occur if it remains unchanged: Property editor might not open on Android.

Replace TemplateBinding with Binding and Source

This is about finding SfListViewExt controls in customizings, and if there are TemplateBindings used, it's recommended to replace them with Binding, and the Source reference should be added. For a detailed description please refer to sheet "Mandatory" in cell 26A-26C. Behavior that might occur if it remains unchanged: Pre-selected item might appear unselected.

Remove TapGestureRecognizer from Main Item

Swiping on the Main items was broken by Maui (Documented in Information). The workaround is to remove the TapGestureRecognizer from UBIKMainItem, and add ListView-based navigation similar to that found in UBIKChildArea (with an extended binding path for technical reasons).

Add Navigation Behavior in Child Area

Highly Recommended

CircularImage to AvatarView

Use AvatarView instead of CircularImage. CircularImage and its wrapping Frame are no longer needed. Use AvatarView from the MAUI Community Toolkit. Add the namespace:

GlyphSize to FontSize and Alignment

Use FontSize and alignment properties instead of GlyphSize. The GlyphSize property is obsolete. Use FontSize and add alignment properties for better layout.

StaticResource to DynamicResource

Use DynamicResource and BaseResourceKey. For dynamic theming, use DynamicResource instead of StaticResource. When inheriting styles, use BaseResourceKey.

Mandatory

Namespace conversion

Update all namespaces to MAUI equivalents. All `xmlns` and `clr-namespace` declarations must be updated to their MAUI counterparts.

For classes referenced in the XAML code, please don't forget to also replace "CPL" with "MAUI" in the class namespace.

Syncfusion control updates

There are some other properties that have changed their names on SfListView/SfListViewExt. We don't use them in our standard XAMLs. But if you use them in customizings, please refer to https://help.syncfusion.com/maui/listview/migration for the complete list.

Syncfusion control updates

Layout name change

TemplateService binding for extracted templates

1. We need to add the following namespace where the changes are applied: xmlns:services="clr-namespace:UBIK.MAUI.Services;assembly=UBIK.MAUI"; 2. We need to search for both "StaticResource" and "DynamicResource"; 3. We only listed some examples here. But the same rule applies to all those templates exacted from UBIKThemes (see the first "Recommended" point).

OnPlatform and OnIdiom syntax changes

All code containing the OnPlatform and OnIdiom functionalities needs to be refactored as the syntax changed. It is recommended to use the inline syntax (see example) as a default wherever possible, but there are also other approaches. When using Bindings, Resources or other complex values in OnIdiom or OnPlatform values, it should only be used with the inline syntax. Please rely to the wiki for more details and possibilities (e.g. if the value contains multiple elements): https://wiki.augmensys.com/index.php?title=XAML_Tips#Platform_and_Device-specific_UI_with_OnPlatform_and_OnIdiom

Syncfusion control updates

It is necessary to use the default Binding with the Source reference to the parent control instead of TemplateBinding when using a SfListViewExt ControlTemplate with selectable items in the ResourceDictionary to be set in the ContentView DataTrigger. Otherwise, the pre-selected items might not appear selected anymore according to our experience.

Affected standard Xamls are: - UBIKEditDouble - UBIKEditInt - UBIKEditString - UBIKEditMinMax (For the exact syntax please refer to our latest standard Xamls.)

If the above explained is also used in any custom Xamls, please consider changing it there, too.

However, the problem only seems to occur if there is TemplateBinding in the ItemsSource & SelectedItem property. But, for example, if the TemplateBinding is only in the BindingContext property of the SfListViewExt (like it is the case in the UBIKPropertyDirectEditListPopup), there seems to be no such problem and therefore no change is necessary.

Remove default ControlTemplate in DataTriggers

To prevent an issue on Android where the direct edit Link to Object editor does not open, there is a change necessary in the UBIKPropertyDirectEditListPopup Xaml: The default ControlTemplate needs to be removed from the ContentView that contains the DataTriggers.

According to our experience, this issue only occurs to our UBIKPropertyDirectEditListPopup standard Xaml, but we can't guarantee that there is no such issue in customized Xamls. So please, if you encounter an issue on Android where a Property Editor doesn't open, report it the mobile development team, and/or try removing the default ControlTemplate from the affected control.

In our standard Xamls, we removed the default ControlTemplate in every ContentView that contains DataTriggers with ControlTemplates where the same template is already set in a DataTrigger. So please, also remove the default ControlTemplates it in the following Xamls if you use customized ones: - UBIKEditDouble - UBIKEditInt - UBIKEditString - UBIKEditMinMax (For the exact syntax please refer to our latest standard Xamls.)

If the above explained is also used in any of your other custom Xamls, please consider changing it there, too. Otherwise, some property editor might not open.

Remove HeadlessLayout style

This Style has no longer any effect in MAUI and even degrades app performance. We are keeping it in our standard UBIKThemes under the Obsolete section to maintain backward compatibility.

Additional mandatory rule

In the customizings, however, it can and should be removed entirely, as it negatively affects performance, as mentioned before. To remove the style, you can simply use VS Code or any other editor with a search function and look through all custom .xaml files for usages of {StaticResource HeadlessLayout} or {DynamicResource HeadlessLayout}. These references should be removed from the respective elements or controls.

Rename SfPullToRefresh properties

Renamed in Maui, however, currently these properties cause an issue and should not be included in customizings. SfPullToRefresh:

Rename progress colors

Renamed in Maui.

SfTabView

Namespace Update

Update Syncfusion TabView namespace. Replace the Xamarin namespace with the MAUI equivalent.

Remove Obsolete Converters

Remove ItemCountToBoolConverter from Resources. This converter is no longer usable in TabView headers.

Add StringFormatConverter

Use StringFormatConverter for combined header strings. Syncfusion MAUI TabView uses a single `Header` property instead of templates. For all tab headers, formatters should be specified to assemble the text. As a best practice, even for simple header strings.

In the above example, a previously defined formatter (that must be also added to the resource dictionary) is used to fill in the header attribute value. ⚠️ Avoid using bindings in `Parameter1` and `Parameter2` — use static strings only. For complex cases, use `EvalExpression`.

FontImageSource Styling

Add local style for FontImageSource. Global styles are not supported.

TabView Structure

Use Grid to wrap TabView. MAUI TabView requires a different structure and property set.

Property Changes

Update renamed or removed properties.

⚠️ Refer to Syncfusion migration guide for full property list.

OnPlatform + OnIdiom backup

Syntax Changes

Use inline or multi-tag syntax. Single-tag syntax is outdated and may not build.

WinPhone to WinUI

Replace WinPhone with WinUI.

GridLength and TypeArguments

Avoid x:TypeArguments with GridLength.

⚠️ Inline syntax is more reliable when using bindings or resources.

Special Characters

Wrap values in quotes if they contain commas or strings.

UWP to WinUI

Replace UWP with WinUI in all OnPlatform scopes.

⚠️ For more details, refer to the Wiki documentation.