refactor: Update performance and security guidelines in MAUI documentation

Author: PureWeen

agents/dotnet-maui.agent.md

@@ -137,12 +137,7 @@ await Shell.Current.GoToAsync("details?id=123");
 
 ### Performance
 1. Use compiled bindings (`x:DataType`)
-2. Enable `<TrimMode>full</TrimMode>`
-3. Enable `<PublishAot>true</PublishAot>` (.NET 9+)
-4. Profile release builds only
-5. Lazy load resources
-6. Unsubscribe events, dispose resources
-7. Use Grid > StackLayout, CollectionView > ListView, Border > Frame
+2. Use Grid > StackLayout, CollectionView > ListView, Border > Frame
 
 ### Security
 ```csharp

instructions/dotnet-maui.instructions.md

@@ -9,8 +9,8 @@ applyTo: '**/*.xaml, **/*.cs'
 
 - Write idiomatic and efficient .NET MAUI and C# code.
 - Follow .NET and .NET MAUI conventions.
-- Prefer inline functions for smaller components but separate complex logic into code-behind or service classes.
-- Async/await should be used where applicable to ensure non-blocking UI operations.
+- 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
 
@@ -21,38 +21,79 @@ applyTo: '**/*.xaml, **/*.cs'
 ## .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}.
+- Use data binding effectively with `{Binding}` and MVVM patterns.
 - Structure .NET MAUI components and services following Separation of Concerns.
-- Always use the latest version C#, currently C# 13 features like record types, pattern matching, and global usings.
+- 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 error tracking in the backend and consider capturing UI-level errors in MAUI with tools like MAUI Community Toolkit's Logger.
+- 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
 
-- Utilize MAUI's built-in features for component lifecycle (e.g. OnAppearing, OnDisappearing).
-- Use asynchronous methods (async/await) for API calls or UI actions that could block the main thread.
-- Optimize MAUI components by reducing unnecessary renders and using OnPropertyChanged() efficiently.
-- Minimize the component render tree by avoiding re-renders unless necessary, using BatchBegin() and BatchCommit() where appropriate.
+- 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.
 
-## Caching Strategies
+## Resources and Assets
 
-- Implement in-memory caching for frequently used data, especially for MAUI apps. Use IMemoryCache for lightweight caching solutions.
-- Consider Distributed Cache strategies (like Redis or SQL Server Cache) for larger applications that need shared state across multiple users or clients.
-- Cache API calls by storing responses to avoid redundant calls when data is unlikely to change, thus improving the user experience.
+- 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 Libraries
+## State Management
 
-- Use dependency injection and the .NET MAUI Community Toolkit for state sharing across components.
+- 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.
@@ -63,7 +104,10 @@ applyTo: '**/*.xaml, **/*.cs'
 - 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.
 
-## API Documentation and Swagger
+## Common Pitfalls
 
-- Use Swagger/OpenAPI for API documentation for your backend API services.
-- Ensure XML documentation for models and API methods for enhancing Swagger documentation.
+- 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.