Tips & Troubleshooting · FmgLib.MauiMarkup

Practical answers to the questions that come up most when working with FmgLib.MauiMarkup.

Naming & Discoverability#

"How do I guess a method name?"

Property Foo → method .Foo(value). Always.
Event Bar → .OnBar(handler) or .OnBar(sender => …).
Attached property Owner.Prop → .OwnerProp(...) (Shell.TitleColor → ShellTitleColor), except Grid placement which drops the prefix (Grid.Row → Row). Full table: Attached Properties.
Property hidden with new in a subclass → .PropNameNew(...) (details).

"A method I expect doesn't exist."

Check the using FmgLib.MauiMarkup; (or global using) is present.
Is the property a real BindableProperty? Plain CLR properties don't get fluent methods — use InvokeOnElement or a custom extension.
Third-party control? It needs [MauiMarkup(typeof(...))] or automatic generator mode (Third-Party Controls).
Check for the New suffix (hidden properties).

Common Compile Errors#

"Ambiguous call between FmgLib method and another markup library" — remove other fluent-markup packages (e.g. CommunityToolkit.Maui.Markup) from the same file's usings, or fully qualify. Mixing both libraries in one project works, but avoid mixing in one file.

"Cannot convert lambda expression…" on a property method — the builder lambda must return the builder chain: e => e.Path("X") (expression), not e => { e.Path("X"); } (statement returning void).

Collection initializer syntax fails on MenuFlyout / Style<T> / VisualState<T> — fluent calls must come after the { … } initializer block:

new MenuFlyoutSubItem() { /* items */ }.Text("Submenu")   // ✅

Runtime Gotchas#

Binding silently does nothing

Path string typo — prefer compiled bindings (e.Getter(...)) to make these compile errors.
Wrong BindingContext — remember templates rebind to the item; use .Source(...) to escape (Property Bindings).
The bound object doesn't raise INotifyPropertyChanged.

Center() doesn't center my text — Center() positions the control in its parent; TextCenter() aligns text inside the control. See Layout Options vs Text Alignment.

Theme values don't update on OS theme change — make sure you used the builder (.TextColor(e => e.OnLight(...).OnDark(...))), not a ternary evaluated once (.TextColor(isDark ? … : …)).

Hot reload doesn't refresh the page — the handler only activates when a debugger is attached, and only pages implementing IFmgLibHotReload + calling InitializeHotReload() rebuild. Full checklist: Hot Reload.

State resets while editing with hot reload — move state out of Build() into fields/constructor.

Duplicate event handlers after hot reload — handlers attached to long-lived objects inside Build() accumulate; attach them in the constructor.

Architecture Recommendations#

One page = one class, UI in Build(), state in fields, logic in a view model. The FmgLibContentPage<TViewModel> base gives you a typed BindingContext.
Extract repeated subtrees into private methods or ContentView components — this is the biggest readability win over XAML (Complete Examples).
Centralize design tokens: a static AppColors / AppStyles class plus app-level ResourceDictionary (Styling).
Prefer compiled bindings for all view-model paths; keep string paths only for quick control-to-control wiring.
Choose the right reaction tool: constant → direct value; VM-driven → binding; state-driven visuals → visual states; condition-driven properties → triggers; reusable control logic → behaviors; one-off → event handler.

Performance Notes#

Direct values (.FontSize(14)) are plain SetValue calls — zero binding overhead. Don't bind what never changes.
Compiled bindings avoid reflection; use them in item templates especially.
CollectionView virtualizes; BindableLayout does not — keep it small.
Animate transforms (Translation, Scale, Opacity) rather than layout properties when possible (Animations).
In automatic generator mode, generation covers every referenced control — switch to explicit [MauiMarkup] attributes if compile times grow.

FAQ#

Can I mix XAML and FmgLib pages? Yes — per page. Migrate incrementally.

Does it work with Shell/Navigation/DI/Essentials? Yes; the library only changes how you construct views, not app architecture. See Shell Applications.

Do CommunityToolkit.Mvvm, ObservableObject, RelayCommand work? Fully — bind with e.Path(...)/e.Getter(...) and .Command(...) as usual.

How do I set a property the library doesn't cover? InvokeOnElement, or plain C# on the captured reference.

Where are the real-world samples? In the repo's sample/ directory — complete apps including games and shop-style UIs.

Which .NET versions are supported? The current package line targets .NET 10 (MAUI 10); the project template can scaffold .NET 9 or 10 via --netMajor.