Rock Mobile Docs
App Factory
  • Welcome 👋
  • 📱Getting Started
    • Building Your First App
      • Creating An App
      • App Configuration
      • Adding Content
      • Deploying Your App
    • Lexicon
  • 🧱Essentials
    • Animations
    • Blocks
      • CMS
        • Content
        • Content Channel Item View
        • Content Collection View
        • Daily Challenge Entry
        • Hero
        • Lava Item List
        • Login
          • Using Auth0
          • Using Entra
        • Profile Details
        • Register
        • Structured Content View
        • Workflow Entry
      • Check-in
        • Check-in
      • Communication
        • Communication Entry
        • Communication List Subscribe
        • Communication View
        • SMS Conversation List
        • SMS Conversation
      • Connection
        • Add Connection Request
        • Connection Type List
        • Connection Opportunity List
        • Connection Request List
        • Connection Request Detail
      • Core
        • Attribute Values
        • Notes
        • Search
        • Smart Search
        • Quick Note
        • My Notes
      • CRM
        • Group Members
        • Person Profile
      • Events
        • Live Experience Occurrences
        • Live Experience
        • Calendar Event Item Occurrence View
        • Calendar Event List
        • Calendar View
        • Event Item Occurrence List By Audience Lava
      • Finance
        • Giving
        • Scheduled Transaction List
        • Transaction Detail
        • Transaction List
      • Groups
        • Group Attendance Entry
        • Group Edit
        • Group Finder
        • Group Member Edit
        • Group Member List
        • Group Member View
        • Group Registration
        • Group View
        • Schedule Preference
        • Schedule Sign Up
        • Schedule Toolbox
        • Schedule Unavailability
      • Prayer
        • Answer To Prayer
        • My Prayer Requests
        • Prayer Card View
        • Prayer Request Details
        • Prayer Session
        • Prayer Session Setup
      • Reminders
        • Reminder Edit
        • Reminder List
        • Reminder Dashboard
      • Security
        • Onboard Person
    • Codex
      • Application Strategy
      • XAML Styling
      • Resources
      • Documentation
    • Commands
      • Communication Commands
      • Navigation Commands
      • Media Commands
      • Utility Commands
    • Controls
      • Behaviors
        • Event To Command Behavior
        • Touch Behavior
      • Content Controls
        • Activity Indicator
        • Application Info
        • Avatar
        • Bible Audio
        • Bible Browser
        • Bible Reader
        • Campus Context Picker
          • Camera Code Reader
        • Cards
          • Block Card
          • Contained Card
          • Inline Card
          • Elements of a Card
          • Masks
          • Styling Cards With CSS
        • Context Menu
        • Countdown
        • Cover Sheet
        • Divider
        • Expander
        • Field Container
        • Flip View
        • Following Icon
        • Geo Boundary View
        • HTML
        • Icon
        • Icon Button
        • Image
        • Interaction
        • Items Collection
        • Login Status
        • Login Status Photo
        • Lottie View
        • Markdown
        • Media Player
          • Legacy
        • Notification Box
        • Paragraph Text
        • QR Code
        • Ratio View
        • Redirect
        • Responsive Column
        • Responsive Layout
        • Scroll View
        • Segment Picker
        • Styled Border
        • Styled View
        • Tag
        • Toggle Button
        • Web View
      • Developer Controls
        • Execute Command
        • Bible Book And Chapter Picker
        • Command Reference
        • Field Stack
        • Media Cast Button
        • Media Progress Bar
        • Parameter
        • Scan Code
        • Validator
        • Volume Control
        • Zone
      • Effects
        • Blur Effect
        • Safe Area Padding Effect
      • Form Fields
        • Attribute Value Editor
        • Address
        • Campus Picker
        • Check Box
        • Check Box List
        • Currency Box
        • Date Picker
        • Email Box
        • Literal
        • Marital Status Picker
        • Multi Picker
        • Number Box
        • Phone Number Box
        • Picker
        • Text Box
        • Text Editor
      • XAML Extensions
        • Boolean Value Converter
        • From Json
        • Inverse Boolean Converter
        • Nullable Guid Converter
        • On Device Platform
        • On Device Type
        • Palette Color
        • Seconds To Time String Converter
    • Field Types
    • Lava
      • Context in Lava
    • Performance
    • Tips and Tricks
      • Custom Site Attributes
      • Migrating to .NET MAUI (V6)
      • Page Anchors
    • Troubleshooting
    • Advanced Topics
      • Dynamic Content
      • Deep Linking
  • 🎨Styling
    • Introduction
    • Style Guide
      • Walkthrough
      • Colors
      • Typography
      • Utilities
      • Shell Components
      • Migrating
    • Legacy
      • Colors
      • Borders
        • Border Color
        • Border Radius
        • Border Width
      • Text
        • Background Color
        • Text Size
        • Alignment
        • Color
        • Line Height
        • Weights & Styles
      • iOS Shadows
      • Styling Components
        • Tags
        • Bible
        • Button
        • Form Fields
        • Modals
      • Custom CSS
  • 👨‍💻Developers
    • Fundamentals
    • Core & Shell Dependencies
    • Custom Blocks
    • OS Version Requirements
  • 🏭App Factory
    • Overview
    • Android Keystore
    • App Store Product Page
    • Developer Accounts
    • Image Resources
    • In-App Giving
    • Publishing Requirements
    • Push Notifications
    • Rock Logins
    • Shell Update Requirements
Powered by GitBook

Resources

  • Release Notes
  • Community Chat
  • Ask Chip

Documentation

  • Rock Manuals
  • Lava

⚙️ Powered by Rock RMS

On this page
  • What? Why?
  • Pre-caution
  • Migrating
  • Layout changes
  • WidthRequest & HeightRequest
  • Xamarin Community Toolkit (XCT)
  • Gradient Brush Transparency
  • Changes in Rock Mobile
  • The Zone control
  • Sayonara, Frame, StyledView
  • Safe Area Padding
  • Forcing a Shell Update
  • Conclusion
  • Useful Links
Export as PDF
  1. Essentials
  2. Tips and Tricks

Migrating to .NET MAUI (V6)

A helpful guide to follow when upgrading your Rock Mobile Xamarin Forms application (V5 and lower) to .NET MAUI (V6 and later).

Last updated 1 year ago

What? Why?

In May of 2024, , the foundation of Rock Mobile, will from Microsoft. This is why, in Rock Mobile V6, we will be upgrading the framework of our shell to be built on , which is the evolution of Xamarin Forms.

There are plenty of benefits to upgrading to .NET MAUI, but to highlight some major ones:

  1. Ongoing support (as stated above)

  2. Performance

  3. Access to the latest iOS/Android SDKs

  4. New features & controls

  5. Bug fixes for old controls

Pre-caution

As with any new framework, there will be bugs to address. Lots of work has been put in up front to try to ensure this migration was as seamless as possible, but Rock Mobile has a ton of cool features, and it would be impossible for the mobile team to catch every edge case. The great news is, as you come across bugs/suspicions, the team is highly active in monitoring and fixing issues reported on our . Another great place to collaborate is the Rock Mobile channel on .

Migrating

Since .NET MAUI is built on the foundation of Xamarin Forms, most of the XAML written and pages designed should function similarly or the same. Still, there were some breaking changes in .NET MAUI that will inevitably have to be addressed in your Rock Mobile application. This guide should be your first stop when trying to figure out why something looks/behaves differently between Xamarin -> MAUI.

Layout changes

There were some breaking changes made to a handful of the Xamarin layouts. First and foremost, the Microsoft team has released an on this exact topic. It is highly recommended to read what changed and why. It goes into much more depth than this article will. The biggest breaking change to address is the behavioral functionality of . The article mentioned above does a great job explaining the changes, but in short, for any sort of complex layout you should avoid StackLayout. If you are an AndExpand abuser (which our team has been guilty of plenty of times), a is your new best friend.

Scrolling

Any layout with scrolling mechanics ( ScrollView/CollectionView/ListView etc. ) will not behave correctly if placed in any sort of StackLayout, no matter how nested. You should use Grid or an alternative.

WidthRequest & HeightRequest

In .NET MAUI, if you set these values, they will pretty much always be respected. This is much different than Xamarin in which you could get very inconsistent results from setting these values.This has bitten our team a few times where we hard-coded a width or height, thinking that it was working correctly, but in reality the parent layout was calculating the size of the element. In MAUI, this made some things look incorrect.

Xamarin Community Toolkit (XCT)

There were some cases stumbled across during testing in which the community toolkit is referenced directly in XAML. There is logic in the shell to update the package references correctly, but you need to ensure anything that you are utilizing from XCT is also available in the MAUI Community Toolkit.

Gradient Brush Transparency

Changes in Rock Mobile

To address the .NET MAUI changes, there have been updates made to the mobile shell.

The Zone control

  1. Use of CollectionView/ListView/ScrollView

  2. The block is marked to expand internally

    1. There are a handful of blocks that are meant to vertically expand. A few examples are login, onboarding, add communication, notes, etc.

Sayonara, Frame, StyledView

Safe Area Padding

To further align with the MAUI paradigm, the SafeAreaPaddingEffect has been migrated to a SafeAreaPaddingBehavior.

The effect will still work, but all it does under the hood is add the behavior if it doesn't previously exist.

<ContentView>
    <ContentView.Behaviors>
        <Rock:SafeAreaPaddingBehavior />
    </ContentView.Behaviors>
</ContentView>

Forcing a Shell Update

Users that haven't updated their shell version to MAUI will encounter an error if you'd added any new elements to a page. In the case where you need everyone to be running MAUI before accessing the app, you can add a ShellVersion check to the Homepage Routing Logic found under the Application tab > Edit > Advanced Settings. On this page you can add a message explaining that an update is required to continue.

//- Navigate to Shell Upgrade page if version is less than v6 (MAUI)
{% assign majorShellVersion = Device.ShellVersion | Slice:'0' | AsInteger %}
{% if majorShellVersion < 6 %}{{ myUpgradeMessagePageGuid }}{% endif %}

Conclusion

The last point that will be made in terms of migration is that MAUI is much less forgiving with poorly structured XAML. General bad practices, such as nesting tons of layouts, negative margin or padding, etc., typically don't look exactly right. It might seem painful to re-write XAML, but keep in mind the light at the end of the tunnel is that it will likely be easier to read, more maintainable, more performant and fit into the correct paradigm.

Well, that is all! This article will be updated as we hit new stumbling points/discoveries. Good luck, and we all look forward to the day that every Rock Mobile app is surfing on the waves of .NET MAUI!

Useful Links

Setting a GradientStop color to Transparent worked as expected in Xamarin Forms, but you'll notice that MAUI has a default black color that shows when Transparent is used. To work around this, change the transparent color to the color you're trying to show with 0% opacity. You can use the prefix #00 for hex codes ().

The , which is used in every single layout, has been updated with specialized behavior. This control was previously inherited from StackLayout, but for reasons stated above this control was migrated to a Grid, with some unique functionality. This means (if for some reason) you had a Zone with the Orientation set to Horizontal, that would break.Each block that goes in the Zone gets a unique row. This row is typically marked with a height of Auto, to mimic the old Zone behavior. There are some cases in which the height of the row is updated to *, which are as follows:

You mark a block to expand through

The Xamarin Forms and Rock Mobile will still exist but are deprecated and won't be supported heavily. The reason is due to the release of the control. The Border is a much better alternative than Frame, in terms of performance and features, and allows for pretty much anything that the StyledView could do.The Frame control has not been consistent for our team when testing .NET MAUI. To assist with that, you can use the new StyledBorder control, that works as a good intermediary when transitioning from Frame -> Border.

- For reporting issues found in Rock Mobile.

- A great community of like-minded Rock Mobile developers.

- The .NET MAUI project.

- An article describing the layout changes between Xamarin & MAUI.

🧱
Xamarin Forms
lose support
.NET MAUI
issue board
Rocket Chat
article
StackLayout
Grid
see all
Zone
Frame
StyledView
Border
Rock Mobile Issues Board
Rock Mobile Rocket Chat Channel
.NET MAUI Project
Layout behavior changes from Xamarin.Forms
the new supported way.