Add .NET MAUI Controls Expert custom agent

[Copilot]

Creates a custom GitHub Copilot agent with deep expertise in .NET MAUI controls, their proper usage, performance optimization, and common pitfalls.

Agent Capabilities

Comprehensive Controls Reference (30+ controls)

• Activity & Status Indicators (ActivityIndicator, ProgressBar)
• Layout Controls (Border, ContentView, Frame, ScrollView)
• Shape Controls (BoxView, Ellipse, Line, Path, Polygon, Polyline, Rectangle, RoundRectangle)
• User Input Controls (Button, CheckBox, DatePicker, Editor, Entry, ImageButton, Picker, RadioButton, SearchBar, Slider, Stepper, Switch, TimePicker)
• List & Data Display (CollectionView, CarouselView, IndicatorView, BindableLayout)
• Interactive Controls (RefreshView, SwipeView)
• Display Controls (Image, Label, GraphicsView, WebView, Map)

Obsolete Controls (NEVER USE)

• ⚠️ ListView - marked as obsolete and will be deleted. Always use CollectionView instead
• ⚠️ TableView - marked as obsolete. Use custom layouts with Grid or VerticalStackLayout instead
• ⚠️ AndExpand layout options - obsolete and should never be used

Control Selection Best Practices

• Use CollectionView for all list scenarios (ListView is obsolete)
• Prefer Border over Frame for better performance (Frame still useful for shadows)
• Use Grid instead of StackLayout for complex layouts
• ⚠️ NEVER use BackgroundColor if Background property exists - always use Background
• XAML examples and usage patterns for every control

Critical Layout Warnings

• ⚠️ NEVER place ScrollView inside StackLayout controls - breaks scrolling completely (StackLayouts allow infinite space)
• ⚠️ NEVER place CollectionView inside StackLayout controls - breaks virtualization and causes severe performance issues

Data Binding Best Practices

• Compiled bindings in XAML with x:DataType (8-20x improvement)
• Expression-based compiled bindings in C# code:
  • Use SetBinding(property, static (ViewModel vm) => vm.Property) over string-based SetBinding(property, "Property")
  • Use Binding.Create(static (ViewModel vm) => vm.Property) over new Binding("Property")
  • Provides type safety, compile-time error checking, IntelliSense support, and better performance

Handler Customization

• Put handler customizations inside ConfigureHandlers call on builder in MauiProgram.cs
• Use Mapper.AppendToMapping for per-control customizations

Performance Critical

• Full trimming and Native AOT configuration
• Layout optimization (Grid vs StackLayout, CollectionView only)

Common Pitfalls

• Don't mix Shell with NavigationPage/TabbedPage/FlyoutPage
• Prefer handlers over renderers (modern approach)
• Always set MainPage once, don't nest tabs
• CRITICAL: Image resources must be referenced as PNG (SVG only for generation)

Platform-Specific

• Conditional compilation patterns
• SecureStorage, Preferences, DeviceInfo APIs
• Handler mappers for cross-platform customization

Configuration

Located at .github/agents/maui-expert.agent.md with all tools enabled. Based on official Microsoft Learn documentation and control documentation from dotnet/docs-maui. Focused specifically on .NET MAUI controls expertise rather than general architecture patterns.

Original prompt

I want to create a MAUI coding expert Agent

Can you please create a custom agent based on everything you know about .NET MAUI and areas where users might run into issues?

The best places for you to find areas that an expert agent would be successful would be to check the conceptual docs

https://github.com/dotnet/docs-maui

Anything in those docs that are marked as "tips" or "important" will be important things to call out.

Refer to the docs here on custom agents
https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[PureWeen]

@copilot this is looking good

Can you explore every single control that you can use in .NET MAUI

https://github.com/dotnet/docs-maui/tree/main/docs/user-interface/controls

And include something about those controls that you think a maui expert would find useful

[Copilot]

@copilot this is looking good

Can you explore every single control that you can use in .NET MAUI ...

Added comprehensive coverage of every .NET MAUI control organized by category:

• Activity & Status Indicators (ActivityIndicator, ProgressBar)
• Layout Controls (Border, ContentView, ScrollView)
• Shape Controls (BoxView, Ellipse, Line, Path, Polygon, Polyline, Rectangle, RoundRectangle)
• User Input Controls (Button, CheckBox, DatePicker, Editor, Entry, ImageButton, Picker, RadioButton, SearchBar, Slider, Stepper, Switch, TimePicker)
• List Controls (CollectionView, CarouselView, IndicatorView, TableView, BindableLayout)
• Interactive Controls (RefreshView, SwipeView)
• Display Controls (Image, Label, GraphicsView, WebView, Map)

Each control includes usage guidance, XAML examples, and important tips like when to use CollectionView vs ListView, Border vs Frame, and proper image referencing. (2682cc5)

[simonrozsival]

@copilot add mention of using expression-based SetBinding over string-based SetBindings and use the expression-based Binding.Create factory method over string-based new Binding("...") constructor:

// DO:
label.SetBinding(Label.TextProperty, static (ViewModel vm) => vm.FullName?.FirstName);
var binding = Binding.Create(static (ViewModel vm) => vm.FullName?.FirstName);

// DO NOT:
label.SetBinding(Label.TextProperty, "FullName.FirstName");
var binding = new Binding("FullName.FirstName");

Refer to https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/data-binding/compiled-bindings?view=net-maui-10.0#compiled-bindings-in-code for more information

[Copilot]

@copilot add mention of using expression-based SetBinding over string-based SetBindings and use the expression-based Binding.Create factory method over string-based new Binding("...") construc...

Added guidance on expression-based compiled bindings in C# code to the Data Binding Best Practices section. The agent now recommends using SetBinding with lambda expressions and Binding.Create factory method over string-based approaches for type safety and compile-time error checking. (a5badc0)

[PureWeen]

@copilot

For scrollview and collectionview

Emphasize NEVER placing these controls inside any of the stacklayout controls

All the *stacklayout controls allow for infinite space so they will invalidate all the virtualization that happens with collectionview amd it will make scrollview not scroll

[Copilot]

@copilot

For scrollview and collectionview ...

Added critical warnings for both ScrollView and CollectionView that they should NEVER be placed inside any StackLayout controls (StackLayout, HorizontalStackLayout, VerticalStackLayout). These layouts allow infinite space which breaks scrolling completely for ScrollView and invalidates virtualization for CollectionView. (0f96fe2)

[kubaflo]

@copilot can you add these instructions?

## Non‑Negotiables (Always Do This)
- Grid for page layout; no nested StackLayouts for complex UIs.
- CollectionView for lists; never ListView/TableView.
- No ScrollView or CollectionView inside any StackLayout.
- Use Background, not BackgroundColor, when available.
- Use compiled bindings everywhere (`x:DataType` on pages and DataTemplates).
- OneWay by default; avoid TwoWay unless editing.
- Centralize converters and styles in `App.xaml` or `Resources/Styles`.
- Images: reference PNGs (`logo.png`) even if SVG sources exist.
- Stick to Shell navigation;

## Instant Anti‑Pattern Detector
- StackLayout wrapping a scrollable: fix to Grid rows (`*, Auto`).
- Multiple nested layouts for simple row/column: replace with one Grid.
- Missing `x:DataType`: add it; catch binding errors at build time.
- Per‑control inline styles/brushes repeated: move to `Styles.xaml`.
- Long `CodeBehind` UI logic: move to ViewModel + Commands.

## Quick Design Review
1) Structure: Is the root a Grid with meaningful row/column definitions?
2) Lists: Are lists CollectionView inside Grid/RefreshView, not StackLayout?
3) Bindings: Does the page and each DataTemplate declare `x:DataType`?
4) Styling: Are colors/brushes/styles centralized via resources?
5) Navigation: Is Shell used consistently with routes and titles?

## Binding & Performance
- Prefer OneTime for static values; OneWay otherwise; TwoWay only for edited fields.
- Avoid bindings for constants: set them directly.
- Avoid `StringFormat` on tight loops; expose pre‑formatted properties (e.g., `FormattedTime`).
- Keep the visual tree flat; prefer Grid over nested layouts.

## Navigation & App Structure
- Shell only. Define routes; set page titles via Shell or BindingContext.
- Set `MainPage` once; no manual navigation services unless justified.
- Respect lifecycle: unsubscribe events in `OnDisappearing` if subscribed in `OnAppearing`.

## Resources, Styles, Converters
- Put converters in a shared ResourceDictionary; reference via `{StaticResource ...}`.
- Move repeated brushes and margins to styles.
- Use Border over Frame; if you need shadows, prefer Border.Shadow first.

## Diagnostics: If You See This → Do That
- Scroll stutters or memory spikes: ensure CollectionView isn’t inside StackLayout
- Colors inconsistent: migrate literals to `Resources/Styles/Colors.xaml` and `Styles.xaml`.

## When Suggesting Changes
- Be surgical: minimal edits, no broad refactors unless essential.
- Explain the anti‑pattern briefly and propose a one‑line fix.
- Prefer examples in the project’s existing style; avoid long tutorials.

[PureWeen]

@jonathanpeppers would this be useful to include in this file?

[jonathanpeppers]

the problem is this section wouldn't work for mobile, do you want to just link here instead:

• https://learn.microsoft.com/dotnet/maui/fundamentals/profiling

[PureWeen]

@copilot suggest putting this code inside the configurehandler call on builder

[Copilot]

Updated the handler customization code to show it inside builder.ConfigureHandlers() call in MauiProgram.cs. (ce16c2b)

[PureWeen]

@StephaneDelcroix any notes or additional changes you want to make to this file around bindings?

[PureWeen]

@copilot remove this section

[Copilot]

Removed the Map setup requirements section. (ce16c2b)