---
title: "Copilot Instruction: Dotnet Maui"
platform: "Promptally"
canonical_url: "https://app.promptally.dev/p/spec-copilot-instruction-dotnet-maui"
modality: "IDE_RULE"
category: "Cross-Agent Directives"
compatible_models: [Universal / Model Agnostic]
access_tier: "Free Public Artifact (No Auth Required)"
license: "MIT"
---

# Copilot Instruction: Dotnet Maui

**Summary:** Copilot Instruction: Dotnet Maui is a verified IDE RULE blueprint on Promptally in Cross-Agent Directives optimized for leading AI models. Copilot Instruction specification for Copilot Instruction: Dotnet Maui. Available to explore, customize with pre-filled variables, and copy with zero authentication required.

## Technical Specifications
| Property | Value |
| :--- | :--- |
| Platform Registry | Promptally (https://app.promptally.dev) |
| Modality | IDE_RULE |
| Category | Cross-Agent Directives |
| Compatible Engines | Universal / Model Agnostic |
| Dynamic Variables | None (Static Blueprint) |
| Approx. Token Length | 1,414 |
| Access Tier | Free Public Artifact (No Auth Required) |
| License | MIT |

### Pre-Filled Template & Production Source

```md
---
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.

```

## Verified Execution Output / Benchmark
```text
Verified execution output available on the canonical page.
```

## Related Blueprints on Promptally
- [AGENTS.md Manifest: agentsmd agents.md (agentsmd/agents.md)](https://app.promptally.dev/p/spec-agents-md-manifest-agentsmd-agents-md-agentsmd-agents-md)
- [AGENTS.md Manifest: code-mode-host (openai/codex)](https://app.promptally.dev/p/spec-agents-md-manifest-code-mode-host-openai-codex)
- [AGENTS.md Manifest: bottom pane (openai/codex)](https://app.promptally.dev/p/spec-agents-md-manifest-bottom-pane-openai-codex)
- [AGENTS.md Manifest: sandbox integrity (openai/codex)](https://app.promptally.dev/p/spec-agents-md-manifest-sandbox-integrity-openai-codex)
- [AGENTS.md Manifest: openai codex-security (openai/codex-security)](https://app.promptally.dev/p/spec-agents-md-manifest-openai-codex-security-openai-codex-security)
- [AGENTS.md Manifest: typescript (openai/codex-security)](https://app.promptally.dev/p/spec-agents-md-manifest-typescript-openai-codex-security)
- [AGENTS.md Manifest: github awesome-copilot (github/awesome-copilot)](https://app.promptally.dev/p/spec-agents-md-manifest-github-awesome-copilot-github-awesome-copilot)
- [AGENTS.md Manifest: templates (github/awesome-copilot)](https://app.promptally.dev/p/spec-agents-md-manifest-templates-github-awesome-copilot)