.NET MAUI Tips - Some Dos and Don'ts

During today's .NET MAUI Community Standup live stream, Maddy Montaquila and I shared some common tips to help developers based on mistakes we've been seeing lately.

Agree? Disagree? Share your perspective and any tips you might have as well in the comments.

Check it out:

.NET MAUI Community Standup - MAUI Catch-up and Q+A! - YouTube

Join David and Maddy to catch up on all things .NET MAUI - .NET 8 reception, .NET 9 planning, some of Maddy and David's "what not to do's", and the usual she...

youtube.com

Slides: Download

.NET MAUI Tip 1

Use Shell or TabbedPage|FlyoutPage|NavigationPage

NOT BOTH

The combination is unsupported.

.NET MAUI Tip 2

Set MainPage once

or YMMV

Consider instead how you can craft different configurations within AppShell.xaml.

.NET MAUI Tip 3

Don't nest tabs (TabbedPage > TabbedPage)

Instead evaluate the UX and consider a different, standard approach

.NET MAUI Tip 4

Reference MauiImages as PNG

(not svg)

<Image Source="dotnet_bot.png" />

The svg is only a source file that generates PNGs at the target densities and sizes.

If you need SVG, use SkiaSharp or a library like Vapolia.Svg

.NET MAUI Tip 5

Don’t nest unconstrained scrolling things inside a stack layout.

• unconstrained - it has no explicit sizing constraints like WidthRequest, HeightRequest, or the parent container size may be unknown
• scrolling things - like CollectionView, ListView, and ScrollView
• stack layout - including StackLayout, HorizontalStackLayout, and VerticalStackLayout

A VerticalStackLayout hosting an unsized/unconstrained vertical scrollable control will not scroll or virtualize unless the height is constrained.

If the layout/scroll directions are not aligned, then it’ll work (e.g. vertical layout with a horizontal scrolling child).

.NET MAUI Tip 6

Customize handlers in ConfigureHandlers()

Append/Modify etc. only run once and should be in place before the first handlers are created.

ConfigureHandlers is a builder method in MauiProgram.cs.

.NET MAUI Tip 7

Don’t nest elements with gesture recognizers

A control with gesture recognizers inside of a layout with gesture recognizers is a recipe for problems.

Similarly, beware z-index issues when implementing gestures where views overlap. Use InputTransparent to ensure gestures pass through views when necessary.

.NET MAUI Tip 8

Move simple renderers to handler modifications (Append/Modify)

While a renderer can be wired up in .NET MAUI, handlers are preferred.

Much simpler to implement and maintain long term.

.NET MAUI Tip 9

Rewrite custom controls (renderers) as handlers with mappers

Wiring up a renderer is a quick start during migration, but you may find porting the implementation to a handler faster and more reliable.

Start with wiring the handler, but don’t spend too long on it if it doesn’t work.

.NET MAUI Tip 10

Prefer Grid with explicit size and * in DataTemplates

Use of Auto, and use of stack layouts inside DataTemplates are less reliable for measure/layout.

Ask Ben Buttigieg for more info ;)

.NET MAUI Tip 11

Use MauiSplashScreen and MauiIcon only for the simple cases

Use native implementations for anything more complex if those don't immediately meet your needs.

.NET MAUI Tip 12

Prefer ProjectReference over NuGets for sharing your libraries

Safer, easier, and sharing more things is supported.

Comments

[SmartmanApps]

"Use Shell or TabbedPage|FlyoutPage|NavigationPage
NOT BOTH"

Ever since you've included shell in the default template it's so hard to find issues for NavigationPage for example. I keep seeing issues that say things like "issue with NavigationPage in shell", which makes it hard to tell if it's actually an issue with NavigationPage or an issue with shell (and I'm looking for NavigationPage issues, not shell issues).

"Customize handlers in ConfigureHandlers()"

Last I looked we still don't have any documentation on how to use handlers to create a bindable property. Literally every example I can find only shows you how to set a value with a handler once, not how to make a bindable property with it (such as a colour which can be changed when the colour scheme is changed). I need this because ToolBarItems still doesn't have bindable properties in it for text and colours (preferably fix that though!).