mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-20 18:35:14 +00:00
b1278eb7ed
* feat: Add MAUI Expert agent for .NET cross-platform app development * refactor: Update performance and security guidelines in MAUI documentation * refactor: Update UI update guidelines for background threads in MAUI agent documentation
114 lines
5.5 KiB
Markdown
114 lines
5.5 KiB
Markdown
---
|
|
description: '.NET MAUI component and application patterns'
|
|
applyTo: '**/*.xaml, **/*.cs'
|
|
---
|
|
|
|
# .NET MAUI
|
|
|
|
## .NET MAUI Code Style and Structure
|
|
|
|
- Write idiomatic and efficient .NET MAUI and C# code.
|
|
- Follow .NET and .NET MAUI conventions.
|
|
- Keep UI (Views) focused on layout and bindings; keep logic in ViewModels and services.
|
|
- Use async/await for I/O and long-running work to keep the UI responsive.
|
|
|
|
## Naming Conventions
|
|
|
|
- Follow PascalCase for component names, method names, and public members.
|
|
- Use camelCase for private fields and local variables.
|
|
- Prefix interface names with "I" (e.g., IUserService).
|
|
|
|
## .NET MAUI and .NET Specific Guidelines
|
|
|
|
- Utilize .NET MAUI's built-in features for component lifecycle (e.g. OnAppearing, OnDisappearing).
|
|
- Use data binding effectively with `{Binding}` and MVVM patterns.
|
|
- Structure .NET MAUI components and services following Separation of Concerns.
|
|
- Use the language version supported by the repo's target .NET SDK and settings; avoid requiring preview language features unless the project is already configured for them.
|
|
|
|
## Critical Rules (Consistency)
|
|
|
|
- NEVER use ListView (deprecated). Use CollectionView.
|
|
- NEVER use TableView (deprecated). Prefer CollectionView or layouts such as Grid/VerticalStackLayout.
|
|
- NEVER use Frame (deprecated). Use Border instead.
|
|
- NEVER use `*AndExpand` layout options (deprecated). Use Grid and explicit sizing instead.
|
|
- NEVER place ScrollView or CollectionView inside StackLayout/VerticalStackLayout/HorizontalStackLayout (can break scrolling and virtualization). Use Grid as the parent layout.
|
|
- NEVER reference images as `.svg` at runtime. Use PNG/JPG resources.
|
|
- NEVER mix Shell navigation with NavigationPage/TabbedPage/FlyoutPage.
|
|
- NEVER use renderers. Use handlers.
|
|
- NEVER set `BackgroundColor`; use `Background` (supports gradients/brushes and is the preferred modern API).
|
|
|
|
## Layout and Control Selection
|
|
|
|
- Prefer `VerticalStackLayout`/`HorizontalStackLayout` over `StackLayout Orientation="..."` (more performant).
|
|
- Use `BindableLayout` for small, non-scrollable lists (≤20 items). Use `CollectionView` for larger or scrollable lists.
|
|
- Prefer `Grid` for complex layouts and when you need to subdivide space.
|
|
- Prefer `Border` over `Frame` for containers with borders/backgrounds.
|
|
|
|
## Shell Navigation
|
|
|
|
- Use Shell as the primary navigation host.
|
|
- Register routes with `Routing.RegisterRoute(...)` and navigate with `Shell.Current.GoToAsync(...)`.
|
|
- Set `MainPage` once at startup; avoid changing it frequently.
|
|
- Don't nest tabs inside Shell.
|
|
|
|
## Error Handling and Validation
|
|
|
|
- Implement proper error handling for .NET MAUI pages and API calls.
|
|
- Use logging for app-level errors; log and surface user-friendly messages for recoverable failures.
|
|
- Implement validation using FluentValidation or DataAnnotations in forms.
|
|
|
|
## MAUI API and Performance Optimization
|
|
|
|
- Prefer compiled bindings for performance and correctness.
|
|
- In XAML, set `x:DataType` on pages/views/templates.
|
|
- Prefer expression-based bindings in C# where possible.
|
|
- Consider enabling stricter XAML compilation in project settings (for example `MauiStrictXamlCompilation=true`), especially in CI.
|
|
- Avoid deep layout nesting (especially nested StackLayouts). Prefer Grid for complex layouts.
|
|
- Keep bindings intentional:
|
|
- Use `OneTime` when values don't change.
|
|
- Use `TwoWay` only for editable values.
|
|
- Avoid binding static constants; set them directly.
|
|
- Update UI from background work using `Dispatcher.Dispatch()` or `Dispatcher.DispatchAsync()`:
|
|
- Prefer `BindableObject.Dispatcher` when you have a reference to a Page, View, or other BindableObject.
|
|
- Inject `IDispatcher` via DI when working in services or ViewModels without direct BindableObject access.
|
|
- Use `MainThread.BeginInvokeOnMainThread(...)` as a fallback only when no Dispatcher is available.
|
|
- **Avoid** obsolete `Device.BeginInvokeOnMainThread` patterns.
|
|
|
|
## Resources and Assets
|
|
|
|
- Place images in `Resources/Images/`, fonts in `Resources/Fonts/`, and raw assets in `Resources/Raw/`.
|
|
- Reference images as PNG/JPG (e.g., `<Image Source="logo.png" />`), not `.svg`.
|
|
- Use appropriately sized images to avoid memory bloat.
|
|
|
|
## State Management
|
|
|
|
- Prefer DI-managed services for shared state and cross-cutting concerns; keep ViewModels scoped to navigation/page lifetimes.
|
|
|
|
## API Design and Integration
|
|
|
|
- Use HttpClient or other appropriate services to communicate with external APIs or your own backend.
|
|
- Implement error handling for API calls using try-catch and provide proper user feedback in the UI.
|
|
|
|
## Storage and Secrets
|
|
|
|
- Use `SecureStorage` for secrets (tokens, refresh tokens), and handle exceptions (unsupported device, key changes, corruption) by clearing/resetting and re-authenticating.
|
|
- Avoid storing secrets in Preferences.
|
|
|
|
## Testing and Debugging
|
|
|
|
- Test components and services using xUnit, NUnit, or MSTest.
|
|
- Use Moq or NSubstitute for mocking dependencies during tests.
|
|
|
|
## Security and Authentication
|
|
|
|
- Implement Authentication and Authorization in the MAUI app where necessary using OAuth or JWT tokens for API authentication.
|
|
- Use HTTPS for all web communication and ensure proper CORS policies are implemented.
|
|
|
|
## Common Pitfalls
|
|
|
|
- Changing `MainPage` frequently can cause navigation issues.
|
|
- Gesture recognizers on both parent and child views can conflict; use `InputTransparent = true` where needed.
|
|
- Memory leaks from unsubscribed events; always unsubscribe and dispose resources.
|
|
- Deeply nested layouts hurt performance; flatten the visual hierarchy.
|
|
- Testing only on emulators misses real-device edge cases; test on physical devices.
|