[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75MM7D84HXMN13NQ0T5RDA0":3,"skill-same:01M75MM7D84HXMN13NQ0T5RDA0":52},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":6,"updatedAt":31,"install":32,"resources":45},"01M75MM7D84HXMN13NQ0T5RDA0","maui-shell-navigation",null,"Guide for implementing Shell-based navigation in .NET MAUI apps. Covers AppShell setup, visual hierarchy (FlyoutItem, TabBar, Tab, ShellContent), URI-based navigation with GoToAsync, route registration, query parameters, back navigation, flyout and tab configuration, navigation events, and navigation guards. Use when: setting up Shell navigation, adding tabs or flyout menus, navigating between pages with GoToAsync, passing parameters between pages, registering routes, customizing back button behavior, or guarding navigation with confirmation dialogs. Do not use for: deep linking from external URLs (see .NET MAUI deep linking documentation), data binding on pages (use maui-data-binding), dependency injection setup (use maui-dependency-injection), or NavigationPage-only apps that don't use Shell.","stanfish06\u002Fskillquarium","stanfish06","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F93099613?v=4","01M75F1CK4ZW109ZK3T26VN52F","Zhiyuan","01M75F1CM53VH6F79DZ8GXKKES",12,"MIT","https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium\u002Fblob\u002Fmaster\u002Fskills\u002Fmaui-shell-navigation\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: maui-shell-navigation\ndescription: >-\n  Guide for implementing Shell-based navigation in .NET MAUI apps. Covers AppShell\n  setup, visual hierarchy (FlyoutItem, TabBar, Tab, ShellContent), URI-based navigation\n  with GoToAsync, route registration, query parameters, back navigation, flyout and\n  tab configuration, navigation events, and navigation guards.\n  Use when: setting up Shell navigation, adding tabs or flyout menus, navigating between\n  pages with GoToAsync, passing parameters between pages, registering routes, customizing\n  back button behavior, or guarding navigation with confirmation dialogs.\n  Do not use for: deep linking from external URLs (see .NET MAUI deep linking\n  documentation), data binding on pages (use maui-data-binding), dependency injection\n  setup (use maui-dependency-injection), or NavigationPage-only apps that don't use Shell.\nlicense: MIT\n---\n\n# .NET MAUI Shell Navigation\n\nImplement page navigation in .NET MAUI apps using Shell. Shell provides URI-based navigation, a flyout menu, tab bars, and a four-level visual hierarchy — all configured declaratively in XAML.\n\n## When to Use\n\n- Setting up top-level app navigation with tabs or a flyout menu\n- Navigating between pages programmatically with `GoToAsync`\n- Passing data between pages via query parameters or object parameters\n- Registering detail-page routes for push navigation\n- Guarding navigation with confirmation dialogs (e.g., unsaved changes)\n- Customizing back button behavior per page\n\n## When Not to Use\n\n- Deep linking from external URLs or app links — see [Android app links](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Fandroid\u002Fapp-links) and [Apple universal links](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Fmacios\u002Funiversal-links)\n- Data binding on navigation target pages — use `maui-data-binding`\n- Dependency injection for pages and view models — use `maui-dependency-injection`\n- Apps using `NavigationPage` without Shell (different navigation API)\n\n## Inputs\n\n- A .NET MAUI project with `AppShell.xaml` as the root shell\n- Pages (`ContentPage`) to navigate between\n- Route names for detail pages not in the visual hierarchy\n\n## Rules That Change the Answer\n\nThese are the Shell-specific decisions that are easy to get wrong. Apply them\nwhenever they are relevant to what the user asked.\n\n| Situation | Do this | Not this |\n|---|---|---|\n| Declaring pages in `AppShell.xaml` | With `xmlns:views=\"clr-namespace:MyApp.Views\"` declared: `\u003CShellContent ContentTemplate=\"{DataTemplate views:MyPage}\" \u002F>` — the page is created on first navigation | `\u003CShellContent>\u003Cviews:MyPage \u002F>\u003C\u002FShellContent>`, which constructs **every** page at startup |\n| Navigating to a page not in the visual hierarchy | `Routing.RegisterRoute(\"details\", typeof(DetailsPage))` first | Calling `GoToAsync(\"details\")` unregistered — it throws at runtime |\n| Receiving navigation parameters | Implement `IQueryAttributable` on the **ViewModel** | Implementing it on the Page, which splits state from the BindingContext |\n| Passing a whole object | `ShellNavigationQueryParameters` | Serialising the object into the query string |\n| Any `GoToAsync` call | `await` it | Fire-and-forget — exceptions are swallowed and navigation races |\n| Confirming before back navigation | `ShellNavigatingEventArgs.GetDeferral()` … `deferral.Complete()` | Blocking synchronously on the dialog task |\n| Detecting back navigation | Check `e.Source == ShellNavigationSource.Pop` | Assuming every navigation is a back action |\n\n**Do not** propose `NavigationPage` \u002F `PushAsync` solutions for a Shell app, and do\nnot restructure a working `AppShell` hierarchy unless the user asked.\n\n**Answer narrowly, but completely.** Staying on topic does not mean being terse. When\nyou show a navigation change, include the pieces needed to run it: the `AppShell.xaml`\nmarkup *and* the `Routing.RegisterRoute` call, or the `GoToAsync` call *and* the\nreceiving `IQueryAttributable` \u002F `[QueryProperty]` code. Where two approaches are both\nvalid (query string vs `ShellNavigationQueryParameters`), show both and say when each\nfits — a single snippet the user still has to complete is a worse answer.\n\n## Shell Visual Hierarchy\n\nShell uses a four-level hierarchy. Each level wraps the one below it:\n\n```\nShell\n ├── FlyoutItem \u002F TabBar          (top-level grouping)\n │    ├── Tab                     (bottom-tab grouping)\n │    │    ├── ShellContent        (page slot → ContentPage)\n │    │    └── ShellContent        (multiple = top tabs)\n │    └── Tab\n └── FlyoutItem \u002F TabBar\n```\n\n- **FlyoutItem** — appears in the flyout menu; contains `Tab` children\n- **TabBar** — bottom tab bar with no flyout entry\n- **Tab** — groups `ShellContent`; multiple children produce top tabs\n- **ShellContent** — each points to a `ContentPage`\n\n### Implicit Conversion\n\nYou can omit intermediate wrappers. Shell auto-wraps:\n\n| You write                    | Shell creates                         |\n|------------------------------|---------------------------------------|\n| `ShellContent` only          | `FlyoutItem > Tab > ShellContent`     |\n| `Tab` only                   | `FlyoutItem > Tab`                    |\n| `ShellContent` in `TabBar`   | `TabBar > Tab > ShellContent`         |\n\n## Workflow: Set Up AppShell\n\n1. Define `AppShell.xaml` inheriting from `Shell`\n2. Add `FlyoutItem` or `TabBar` elements for top-level navigation\n3. Add `Tab` elements for bottom tabs; nest multiple `ShellContent` for top tabs\n4. **Always use `ContentTemplate`** with `DataTemplate` so pages load on demand\n5. **Give every `ShellContent` an explicit `Route`** (see below)\n6. Register detail-page routes in the `AppShell` constructor\n\n> **Set `Route=` on every `ShellContent`.** If you omit it, MAUI auto-generates a\n> name from a shared counter — `Routing.cs` produces `D_FAULT_{TypeName}{n}`. A real\n> shell with three unnamed `ShellContent` elements yields routes like\n> `D_FAULT_ShellContent2` and `D_FAULT_ShellContent5`: the numbers are not\n> sequential, they depend on how many Shell elements were constructed first, and they\n> shift when you reorder or add pages. You cannot write a stable absolute route\n> (`\u002F\u002Fdashboard`) or deep link against that. An explicit `Route=\"dashboard\"` is stable\n> forever.\n\n```xml\n\u003CShell xmlns=\"http:\u002F\u002Fschemas.microsoft.com\u002Fdotnet\u002F2021\u002Fmaui\"\n       xmlns:x=\"http:\u002F\u002Fschemas.microsoft.com\u002Fwinfx\u002F2009\u002Fxaml\"\n       xmlns:views=\"clr-namespace:MyApp.Views\"\n       x:Class=\"MyApp.AppShell\"\n       FlyoutBehavior=\"Flyout\">\n\n    \u003CFlyoutItem Title=\"Animals\" Icon=\"animals.png\">\n        \u003CTab Title=\"Cats\">\n            \u003CShellContent Title=\"Domestic\" Route=\"domesticcats\"\n                          ContentTemplate=\"{DataTemplate views:DomesticCatsPage}\" \u002F>\n            \u003CShellContent Title=\"Wild\" Route=\"wildcats\"\n                          ContentTemplate=\"{DataTemplate views:WildCatsPage}\" \u002F>\n        \u003C\u002FTab>\n        \u003CTab Title=\"Dogs\" Icon=\"dogs.png\">\n            \u003CShellContent Route=\"dogs\" ContentTemplate=\"{DataTemplate views:DogsPage}\" \u002F>\n        \u003C\u002FTab>\n    \u003C\u002FFlyoutItem>\n\n    \u003CTabBar>\n        \u003CShellContent Title=\"Home\" Icon=\"home.png\" Route=\"home\"\n                      ContentTemplate=\"{DataTemplate views:HomePage}\" \u002F>\n        \u003CShellContent Title=\"Settings\" Icon=\"settings.png\" Route=\"settings\"\n                      ContentTemplate=\"{DataTemplate views:SettingsPage}\" \u002F>\n    \u003C\u002FTabBar>\n\u003C\u002FShell>\n```\n\n```csharp\n\u002F\u002F AppShell.xaml.cs\npublic partial class AppShell : Shell\n{\n    public AppShell()\n    {\n        InitializeComponent();\n        Routing.RegisterRoute(\"animaldetails\", typeof(AnimalDetailsPage));\n        Routing.RegisterRoute(\"editanimal\", typeof(EditAnimalPage));\n    }\n}\n```\n\n## Workflow: Navigate with GoToAsync\n\nAll programmatic navigation uses `Shell.Current.GoToAsync`. Always `await` the call.\n\n### Route Prefixes\n\n| Prefix | Meaning                                     |\n|--------|---------------------------------------------|\n| `\u002F\u002F`   | Absolute route from Shell root              |\n| (none) | Relative; pushes onto the current nav stack |\n| `..`   | Go back one level                           |\n| `..\u002F`  | Go back then navigate forward               |\n\n### Navigation Examples\n\n```csharp\n\u002F\u002F 1. Absolute — switch to a specific hierarchy location\nawait Shell.Current.GoToAsync(\"\u002F\u002Fanimals\u002Fcats\u002Fdomestic\");\n\n\u002F\u002F 2. Relative — push a registered detail page\nawait Shell.Current.GoToAsync(\"animaldetails\");\n\n\u002F\u002F 3. With query string parameters\nawait Shell.Current.GoToAsync($\"animaldetails?id={animal.Id}\");\n\n\u002F\u002F 4. Go back one page\nawait Shell.Current.GoToAsync(\"..\");\n\n\u002F\u002F 5. Go back two pages\nawait Shell.Current.GoToAsync(\"..\u002F..\");\n\n\u002F\u002F 6. Go back one page, then push a different page\nawait Shell.Current.GoToAsync(\"..\u002Feditanimal\");\n```\n\n## Workflow: Pass Data Between Pages\n\n### Option 1: IQueryAttributable (Preferred)\n\nImplement on ViewModels to receive all parameters in one call:\n\n```csharp\npublic class AnimalDetailsViewModel : ObservableObject, IQueryAttributable\n{\n    public void ApplyQueryAttributes(IDictionary\u003Cstring, object> query)\n    {\n        if (query.TryGetValue(\"id\", out var id))\n            AnimalId = id.ToString();\n    }\n}\n```\n\n### Option 2: QueryProperty Attribute\n\nApply on the **ViewModel** class (or the page, if it genuinely owns the state).\nPrefer `IQueryAttributable` on the ViewModel — it keeps navigation state with the\n`BindingContext` and handles multiple parameters in one call:\n\n```csharp\n[QueryProperty(nameof(AnimalId), \"id\")]\npublic partial class AnimalDetailsViewModel : ObservableObject\n{\n    [ObservableProperty]\n    private string _animalId = string.Empty;\n}\n```\n\nShell applies query attributes *after* the page constructor sets `BindingContext`,\nso the property must raise change notification — a plain auto-property leaves the\nbinding stuck on its initial value.\n\n### Option 3: Complex Objects via ShellNavigationQueryParameters\n\nPass objects without serializing to strings:\n\n```csharp\nvar parameters = new ShellNavigationQueryParameters\n{\n    { \"animal\", selectedAnimal }\n};\nawait Shell.Current.GoToAsync(\"animaldetails\", parameters);\n```\n\nReceive via `IQueryAttributable`:\n\n```csharp\npublic void ApplyQueryAttributes(IDictionary\u003Cstring, object> query)\n{\n    Animal = query[\"animal\"] as Animal;\n}\n```\n\n## Workflow: Guard Navigation\n\nUse `GetDeferral()` in `OnNavigating` for async checks (e.g., \"save unsaved changes?\"):\n\n```csharp\n\u002F\u002F In AppShell.xaml.cs\nprotected override async void OnNavigating(ShellNavigatingEventArgs args)\n{\n    base.OnNavigating(args);\n    if (hasUnsavedChanges && args.Source == ShellNavigationSource.Pop)\n    {\n        var deferral = args.GetDeferral();\n        bool discard = await ShowConfirmationDialog();\n        if (!discard)\n            args.Cancel();\n        deferral.Complete();\n    }\n}\n```\n\n## Tab Configuration\n\n### Bottom Tabs\n\nMultiple `ShellContent` (or `Tab`) children inside a `TabBar` or `FlyoutItem` produce bottom tabs.\n\n### Top Tabs\n\nMultiple `ShellContent` children inside a single `Tab` produce top tabs:\n\n```xml\n\u003CTab Title=\"Photos\">\n    \u003CShellContent Title=\"Recent\"    ContentTemplate=\"{DataTemplate views:RecentPage}\" \u002F>\n    \u003CShellContent Title=\"Favorites\" ContentTemplate=\"{DataTemplate views:FavoritesPage}\" \u002F>\n\u003C\u002FTab>\n```\n\n### Tab Bar Appearance\n\n| Attached Property              | Type    | Purpose                        |\n|--------------------------------|---------|--------------------------------|\n| `Shell.TabBarBackgroundColor`  | `Color` | Tab bar background             |\n| `Shell.TabBarForegroundColor`  | `Color` | Selected icon color            |\n| `Shell.TabBarTitleColor`       | `Color` | Selected tab title color       |\n| `Shell.TabBarUnselectedColor`  | `Color` | Unselected tab icon\u002Ftitle      |\n| `Shell.TabBarIsVisible`        | `bool`  | Show\u002Fhide the tab bar          |\n\n```xml\n\u003C!-- Hide the tab bar on a specific page -->\n\u003CContentPage Shell.TabBarIsVisible=\"False\" ... \u002F>\n```\n\n## Flyout Configuration\n\n### FlyoutBehavior\n\nSet on `Shell`: `Disabled`, `Flyout`, or `Locked`.\n\n```xml\n\u003CShell FlyoutBehavior=\"Flyout\"> ... \u003C\u002FShell>\n```\n\n### FlyoutDisplayOptions\n\nControls how children appear in the flyout:\n\n- `AsSingleItem` (default) — one flyout entry for the group\n- `AsMultipleItems` — each child `Tab` gets its own entry\n\n```xml\n\u003CFlyoutItem Title=\"Animals\" FlyoutDisplayOptions=\"AsMultipleItems\">\n    \u003CTab Title=\"Cats\" ... \u002F>\n    \u003CTab Title=\"Dogs\" ... \u002F>\n\u003C\u002FFlyoutItem>\n```\n\n### MenuItem (Non-Navigation Flyout Entries)\n\n```xml\n\u003CMenuItem Text=\"Log Out\"\n          Command=\"{Binding LogOutCommand}\"\n          IconImageSource=\"logout.png\" \u002F>\n```\n\n## Back Button Behavior\n\nCustomize the back button per page:\n\n```xml\n\u003CShell.BackButtonBehavior>\n    \u003CBackButtonBehavior Command=\"{Binding BackCommand}\"\n                       IconOverride=\"back_arrow.png\"\n                       TextOverride=\"Cancel\"\n                       IsVisible=\"True\" \u002F>\n\u003C\u002FShell.BackButtonBehavior>\n```\n\nProperties: `Command`, `CommandParameter`, `IconOverride`, `TextOverride`, `IsVisible`, `IsEnabled`.\n\n## Inspecting Navigation State\n\n```csharp\n\u002F\u002F Current URI location\nstring location = Shell.Current.CurrentState.Location.ToString();\n\n\u002F\u002F Current page\nPage page = Shell.Current.CurrentPage;\n\n\u002F\u002F Navigation stack of the current tab\nIReadOnlyList\u003CPage> stack = Shell.Current.Navigation.NavigationStack;\n```\n\n## Navigation Events\n\nOverride in `AppShell`:\n\n```csharp\nprotected override void OnNavigated(ShellNavigatedEventArgs args)\n{\n    base.OnNavigated(args);\n    \u002F\u002F args.Current, args.Previous, args.Source\n}\n```\n\n`ShellNavigationSource` values: `Push`, `Pop`, `PopToRoot`, `Insert`, `Remove`, `ShellItemChanged`, `ShellSectionChanged`, `ShellContentChanged`, `Unknown`.\n\n## Common Pitfalls\n\n- **Eager page creation**: Using `Content` directly instead of `ContentTemplate` with `DataTemplate` creates all pages at Shell init, hurting startup time. Always use `ContentTemplate`.\n- **Duplicate route names**: `Routing.RegisterRoute` throws `ArgumentException` if a route name matches an existing route or a visual hierarchy route. Every route must be unique across the app.\n- **Relative routes without registration**: You cannot `GoToAsync(\"somepage\")` unless `somepage` was registered with `Routing.RegisterRoute`. Visual hierarchy pages use absolute `\u002F\u002F` routes.\n- **Fire-and-forget GoToAsync**: Not awaiting `GoToAsync` causes race conditions and silent failures. Always `await` the call.\n- **Wrong absolute route path**: Absolute routes must match the full path through the visual hierarchy (`\u002F\u002FFlyoutItem\u002FTab\u002FShellContent`). Wrong paths produce silent no-ops, not exceptions.\n- **Manipulating Tab.Stack directly**: The navigation stack is read-only. Use `GoToAsync` for all navigation changes.\n- **Forgetting `GetDeferral()` for async guards**: Synchronous cancellation in `OnNavigating` works, but async checks require `GetDeferral()` \u002F `deferral.Complete()` to avoid race conditions.\n\n## References\n\n- `references\u002Fshell-navigation-api.md` — Full API reference for Shell hierarchy, routes, tabs, flyout, and navigation\n- [.NET MAUI Shell Navigation](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Ffundamentals\u002Fshell\u002Fnavigation)\n- [.NET MAUI Shell Tabs](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Ffundamentals\u002Fshell\u002Ftabs)\n- [.NET MAUI Shell Flyout](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Ffundamentals\u002Fshell\u002Fflyout)\n- [.NET MAUI Shell Pages](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Ffundamentals\u002Fshell\u002Fpages)\n","# .NET MAUI Shell Navigation\n\nImplement page navigation in .NET MAUI apps using Shell. Shell provides URI-based navigation, a flyout menu, tab bars, and a four-level visual hierarchy — all configured declaratively in XAML.\n\n## When to Use\n\n- Setting up top-level app navigation with tabs or a flyout menu\n- Navigating between pages programmatically with `GoToAsync`\n- Passing data between pages via query parameters or object parameters\n- Registering detail-page routes for push navigation\n- Guarding navigation with confirmation dialogs (e.g., unsaved changes)\n- Customizing back button behavior per page\n\n## When Not to Use\n\n- Deep linking from external URLs or app links — see [Android app links](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Fandroid\u002Fapp-links) and [Apple universal links](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Fmacios\u002Funiversal-links)\n- Data binding on navigation target pages — use `maui-data-binding`\n- Dependency injection for pages and view models — use `maui-dependency-injection`\n- Apps using `NavigationPage` without Shell (different navigation API)\n\n## Inputs\n\n- A .NET MAUI project with `AppShell.xaml` as the root shell\n- Pages (`ContentPage`) to navigate between\n- Route names for detail pages not in the visual hierarchy\n\n## Rules That Change the Answer\n\nThese are the Shell-specific decisions that are easy to get wrong. Apply them\nwhenever they are relevant to what the user asked.\n\n| Situation | Do this | Not this |\n|---|---|---|\n| Declaring pages in `AppShell.xaml` | With `xmlns:views=\"clr-namespace:MyApp.Views\"` declared: `\u003CShellContent ContentTemplate=\"{DataTemplate views:MyPage}\" \u002F>` — the page is created on first navigation | `\u003CShellContent>\u003Cviews:MyPage \u002F>\u003C\u002FShellContent>`, which constructs **every** page at startup |\n| Navigating to a page not in the visual hierarchy | `Routing.RegisterRoute(\"details\", typeof(DetailsPage))` first | Calling `GoToAsync(\"details\")` unregistered — it throws at runtime |\n| Receiving navigation parameters | Implement `IQueryAttributable` on the **ViewModel** | Implementing it on the Page, which splits state from the BindingContext |\n| Passing a whole object | `ShellNavigationQueryParameters` | Serialising the object into the query string |\n| Any `GoToAsync` call | `await` it | Fire-and-forget — exceptions are swallowed and navigation races |\n| Confirming before back navigation | `ShellNavigatingEventArgs.GetDeferral()` … `deferral.Complete()` | Blocking synchronously on the dialog task |\n| Detecting back navigation | Check `e.Source == ShellNavigationSource.Pop` | Assuming every navigation is a back action |\n\n**Do not** propose `NavigationPage` \u002F `PushAsync` solutions for a Shell app, and do\nnot restructure a working `AppShell` hierarchy unless the user asked.\n\n**Answer narrowly, but completely.** Staying on topic does not mean being terse. When\nyou show a navigation change, include the pieces needed to run it: the `AppShell.xaml`\nmarkup *and* the `Routing.RegisterRoute` call, or the `GoToAsync` call *and* the\nreceiving `IQueryAttributable` \u002F `[QueryProperty]` code. Where two approaches are both\nvalid (query string vs `ShellNavigationQueryParameters`), show both and say when each\nfits — a single snippet the user still has to complete is a worse answer.\n\n## Shell Visual Hierarchy\n\nShell uses a four-level hierarchy. Each level wraps the one below it:\n\n```\nShell\n ├── FlyoutItem \u002F TabBar          (top-level grouping)\n │    ├── Tab                     (bottom-tab grouping)\n │    │    ├── ShellContent        (page slot → ContentPage)\n │    │    └── ShellContent        (multiple = top tabs)\n │    └── Tab\n └── FlyoutItem \u002F TabBar\n```\n\n- **FlyoutItem** — appears in the flyout menu; contains `Tab` children\n- **TabBar** — bottom tab bar with no flyout entry\n- **Tab** — groups `ShellContent`; multiple children produce top tabs\n- **ShellContent** — each points to a `ContentPage`\n\n### Implicit Conversion\n\nYou can omit intermediate wrappers. Shell auto-wraps:\n\n| You write                    | Shell creates                         |\n|------------------------------|---------------------------------------|\n| `ShellContent` only          | `FlyoutItem > Tab > ShellContent`     |\n| `Tab` only                   | `FlyoutItem > Tab`                    |\n| `ShellContent` in `TabBar`   | `TabBar > Tab > ShellContent`         |\n\n## Workflow: Set Up AppShell\n\n1. Define `AppShell.xaml` inheriting from `Shell`\n2. Add `FlyoutItem` or `TabBar` elements for top-level navigation\n3. Add `Tab` elements for bottom tabs; nest multiple `ShellContent` for top tabs\n4. **Always use `ContentTemplate`** with `DataTemplate` so pages load on demand\n5. **Give every `ShellContent` an explicit `Route`** (see below)\n6. Register detail-page routes in the `AppShell` constructor\n\n> **Set `Route=` on every `ShellContent`.** If you omit it, MAUI auto-generates a\n> name from a shared counter — `Routing.cs` produces `D_FAULT_{TypeName}{n}`. A real\n> shell with three unnamed `ShellContent` elements yields routes like\n> `D_FAULT_ShellContent2` and `D_FAULT_ShellContent5`: the numbers are not\n> sequential, they depend on how many Shell elements were constructed first, and they\n> shift when you reorder or add pages. You cannot write a stable absolute route\n> (`\u002F\u002Fdashboard`) or deep link against that. An explicit `Route=\"dashboard\"` is stable\n> forever.\n\n```xml\n\u003CShell xmlns=\"http:\u002F\u002Fschemas.microsoft.com\u002Fdotnet\u002F2021\u002Fmaui\"\n       xmlns:x=\"http:\u002F\u002Fschemas.microsoft.com\u002Fwinfx\u002F2009\u002Fxaml\"\n       xmlns:views=\"clr-namespace:MyApp.Views\"\n       x:Class=\"MyApp.AppShell\"\n       FlyoutBehavior=\"Flyout\">\n\n    \u003CFlyoutItem Title=\"Animals\" Icon=\"animals.png\">\n        \u003CTab Title=\"Cats\">\n            \u003CShellContent Title=\"Domestic\" Route=\"domesticcats\"\n                          ContentTemplate=\"{DataTemplate views:DomesticCatsPage}\" \u002F>\n            \u003CShellContent Title=\"Wild\" Route=\"wildcats\"\n                          ContentTemplate=\"{DataTemplate views:WildCatsPage}\" \u002F>\n        \u003C\u002FTab>\n        \u003CTab Title=\"Dogs\" Icon=\"dogs.png\">\n            \u003CShellContent Route=\"dogs\" ContentTemplate=\"{DataTemplate views:DogsPage}\" \u002F>\n        \u003C\u002FTab>\n    \u003C\u002FFlyoutItem>\n\n    \u003CTabBar>\n        \u003CShellContent Title=\"Home\" Icon=\"home.png\" Route=\"home\"\n                      ContentTemplate=\"{DataTemplate views:HomePage}\" \u002F>\n        \u003CShellContent Title=\"Settings\" Icon=\"settings.png\" Route=\"settings\"\n                      ContentTemplate=\"{DataTemplate views:SettingsPage}\" \u002F>\n    \u003C\u002FTabBar>\n\u003C\u002FShell>\n```\n\n```csharp\n\u002F\u002F AppShell.xaml.cs\npublic partial class AppShell : Shell\n{\n    public AppShell()\n    {\n        InitializeComponent();\n        Routing.RegisterRoute(\"animaldetails\", typeof(AnimalDetailsPage));\n        Routing.RegisterRoute(\"editanimal\", typeof(EditAnimalPage));\n    }\n}\n```\n\n## Workflow: Navigate with GoToAsync\n\nAll programmatic navigation uses `Shell.Current.GoToAsync`. Always `await` the call.\n\n### Route Prefixes\n\n| Prefix | Meaning                                     |\n|--------|---------------------------------------------|\n| `\u002F\u002F`   | Absolute route from Shell root              |\n| (none) | Relative; pushes onto the current nav stack |\n| `..`   | Go back one level                           |\n| `..\u002F`  | Go back then navigate forward               |\n\n### Navigation Examples\n\n```csharp\n\u002F\u002F 1. Absolute — switch to a specific hierarchy location\nawait Shell.Current.GoToAsync(\"\u002F\u002Fanimals\u002Fcats\u002Fdomestic\");\n\n\u002F\u002F 2. Relative — push a registered detail page\nawait Shell.Current.GoToAsync(\"animaldetails\");\n\n\u002F\u002F 3. With query string parameters\nawait Shell.Current.GoToAsync($\"animaldetails?id={animal.Id}\");\n\n\u002F\u002F 4. Go back one page\nawait Shell.Current.GoToAsync(\"..\");\n\n\u002F\u002F 5. Go back two pages\nawait Shell.Current.GoToAsync(\"..\u002F..\");\n\n\u002F\u002F 6. Go back one page, then push a different page\nawait Shell.Current.GoToAsync(\"..\u002Feditanimal\");\n```\n\n## Workflow: Pass Data Between Pages\n\n### Option 1: IQueryAttributable (Preferred)\n\nImplement on ViewModels to receive all parameters in one call:\n\n```csharp\npublic class AnimalDetailsViewModel : ObservableObject, IQueryAttributable\n{\n    public void ApplyQueryAttributes(IDictionary\u003Cstring, object> query)\n    {\n        if (query.TryGetValue(\"id\", out var id))\n            AnimalId = id.ToString();\n    }\n}\n```\n\n### Option 2: QueryProperty Attribute\n\nApply on the **ViewModel** class (or the page, if it genuinely owns the state).\nPrefer `IQueryAttributable` on the ViewModel — it keeps navigation state with the\n`BindingContext` and handles multiple parameters in one call:\n\n```csharp\n[QueryProperty(nameof(AnimalId), \"id\")]\npublic partial class AnimalDetailsViewModel : ObservableObject\n{\n    [ObservableProperty]\n    private string _animalId = string.Empty;\n}\n```\n\nShell applies query attributes *after* the page constructor sets `BindingContext`,\nso the property must raise change notification — a plain auto-property leaves the\nbinding stuck on its initial value.\n\n### Option 3: Complex Objects via ShellNavigationQueryParameters\n\nPass objects without serializing to strings:\n\n```csharp\nvar parameters = new ShellNavigationQueryParameters\n{\n    { \"animal\", selectedAnimal }\n};\nawait Shell.Current.GoToAsync(\"animaldetails\", parameters);\n```\n\nReceive via `IQueryAttributable`:\n\n```csharp\npublic void ApplyQueryAttributes(IDictionary\u003Cstring, object> query)\n{\n    Animal = query[\"animal\"] as Animal;\n}\n```\n\n## Workflow: Guard Navigation\n\nUse `GetDeferral()` in `OnNavigating` for async checks (e.g., \"save unsaved changes?\"):\n\n```csharp\n\u002F\u002F In AppShell.xaml.cs\nprotected override async void OnNavigating(ShellNavigatingEventArgs args)\n{\n    base.OnNavigating(args);\n    if (hasUnsavedChanges && args.Source == ShellNavigationSource.Pop)\n    {\n        var deferral = args.GetDeferral();\n        bool discard = await ShowConfirmationDialog();\n        if (!discard)\n            args.Cancel();\n        deferral.Complete();\n    }\n}\n```\n\n## Tab Configuration\n\n### Bottom Tabs\n\nMultiple `ShellContent` (or `Tab`) children inside a `TabBar` or `FlyoutItem` produce bottom tabs.\n\n### Top Tabs\n\nMultiple `ShellContent` children inside a single `Tab` produce top tabs:\n\n```xml\n\u003CTab Title=\"Photos\">\n    \u003CShellContent Title=\"Recent\"    ContentTemplate=\"{DataTemplate views:RecentPage}\" \u002F>\n    \u003CShellContent Title=\"Favorites\" ContentTemplate=\"{DataTemplate views:FavoritesPage}\" \u002F>\n\u003C\u002FTab>\n```\n\n### Tab Bar Appearance\n\n| Attached Property              | Type    | Purpose                        |\n|--------------------------------|---------|--------------------------------|\n| `Shell.TabBarBackgroundColor`  | `Color` | Tab bar background             |\n| `Shell.TabBarForegroundColor`  | `Color` | Selected icon color            |\n| `Shell.TabBarTitleColor`       | `Color` | Selected tab title color       |\n| `Shell.TabBarUnselectedColor`  | `Color` | Unselected tab icon\u002Ftitle      |\n| `Shell.TabBarIsVisible`        | `bool`  | Show\u002Fhide the tab bar          |\n\n```xml\n\u003C!-- Hide the tab bar on a specific page -->\n\u003CContentPage Shell.TabBarIsVisible=\"False\" ... \u002F>\n```\n\n## Flyout Configuration\n\n### FlyoutBehavior\n\nSet on `Shell`: `Disabled`, `Flyout`, or `Locked`.\n\n```xml\n\u003CShell FlyoutBehavior=\"Flyout\"> ... \u003C\u002FShell>\n```\n\n### FlyoutDisplayOptions\n\nControls how children appear in the flyout:\n\n- `AsSingleItem` (default) — one flyout entry for the group\n- `AsMultipleItems` — each child `Tab` gets its own entry\n\n```xml\n\u003CFlyoutItem Title=\"Animals\" FlyoutDisplayOptions=\"AsMultipleItems\">\n    \u003CTab Title=\"Cats\" ... \u002F>\n    \u003CTab Title=\"Dogs\" ... \u002F>\n\u003C\u002FFlyoutItem>\n```\n\n### MenuItem (Non-Navigation Flyout Entries)\n\n```xml\n\u003CMenuItem Text=\"Log Out\"\n          Command=\"{Binding LogOutCommand}\"\n          IconImageSource=\"logout.png\" \u002F>\n```\n\n## Back Button Behavior\n\nCustomize the back button per page:\n\n```xml\n\u003CShell.BackButtonBehavior>\n    \u003CBackButtonBehavior Command=\"{Binding BackCommand}\"\n                       IconOverride=\"back_arrow.png\"\n                       TextOverride=\"Cancel\"\n                       IsVisible=\"True\" \u002F>\n\u003C\u002FShell.BackButtonBehavior>\n```\n\nProperties: `Command`, `CommandParameter`, `IconOverride`, `TextOverride`, `IsVisible`, `IsEnabled`.\n\n## Inspecting Navigation State\n\n```csharp\n\u002F\u002F Current URI location\nstring location = Shell.Current.CurrentState.Location.ToString();\n\n\u002F\u002F Current page\nPage page = Shell.Current.CurrentPage;\n\n\u002F\u002F Navigation stack of the current tab\nIReadOnlyList\u003CPage> stack = Shell.Current.Navigation.NavigationStack;\n```\n\n## Navigation Events\n\nOverride in `AppShell`:\n\n```csharp\nprotected override void OnNavigated(ShellNavigatedEventArgs args)\n{\n    base.OnNavigated(args);\n    \u002F\u002F args.Current, args.Previous, args.Source\n}\n```\n\n`ShellNavigationSource` values: `Push`, `Pop`, `PopToRoot`, `Insert`, `Remove`, `ShellItemChanged`, `ShellSectionChanged`, `ShellContentChanged`, `Unknown`.\n\n## Common Pitfalls\n\n- **Eager page creation**: Using `Content` directly instead of `ContentTemplate` with `DataTemplate` creates all pages at Shell init, hurting startup time. Always use `ContentTemplate`.\n- **Duplicate route names**: `Routing.RegisterRoute` throws `ArgumentException` if a route name matches an existing route or a visual hierarchy route. Every route must be unique across the app.\n- **Relative routes without registration**: You cannot `GoToAsync(\"somepage\")` unless `somepage` was registered with `Routing.RegisterRoute`. Visual hierarchy pages use absolute `\u002F\u002F` routes.\n- **Fire-and-forget GoToAsync**: Not awaiting `GoToAsync` causes race conditions and silent failures. Always `await` the call.\n- **Wrong absolute route path**: Absolute routes must match the full path through the visual hierarchy (`\u002F\u002FFlyoutItem\u002FTab\u002FShellContent`). Wrong paths produce silent no-ops, not exceptions.\n- **Manipulating Tab.Stack directly**: The navigation stack is read-only. Use `GoToAsync` for all navigation changes.\n- **Forgetting `GetDeferral()` for async guards**: Synchronous cancellation in `OnNavigating` works, but async checks require `GetDeferral()` \u002F `deferral.Complete()` to avoid race conditions.\n\n## References\n\n- `references\u002Fshell-navigation-api.md` — Full API reference for Shell hierarchy, routes, tabs, flyout, and navigation\n- [.NET MAUI Shell Navigation](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Ffundamentals\u002Fshell\u002Fnavigation)\n- [.NET MAUI Shell Tabs](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Ffundamentals\u002Fshell\u002Ftabs)\n- [.NET MAUI Shell Flyout](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Ffundamentals\u002Fshell\u002Fflyout)\n- [.NET MAUI Shell Pages](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Ffundamentals\u002Fshell\u002Fpages)\n",{"name":5,"license":15,"description":7},"master","49e49abf2f670d429e0b7e2c0349739c3fdd5cbe","skills\u002Fmaui-shell-navigation",5,"https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium","https:\u002F\u002Fgithub.com\u002Fstanfish06","https:\u002F\u002Fwww.stanfish.dev\u002F","2026-11-14 21:31:37",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add stanfish06\u002Fskillquarium --skill maui-shell-navigation",{"tool":38,"command":39},"bunx","bunx skills add stanfish06\u002Fskillquarium --skill maui-shell-navigation",{"tool":41,"command":42},"pnpm","pnpm dlx skills add stanfish06\u002Fskillquarium --skill maui-shell-navigation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium\u002Fblob\u002Fmaster\u002Fskills\u002Fmaui-shell-navigation\u002FSKILL.md",true,[46],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"references\u002Fshell-navigation-api.md","REFERENCE","参考文档",9219,"https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium\u002Fblob\u002Fmaster\u002Fskills\u002Fmaui-shell-navigation\u002Freferences\u002Fshell-navigation-api.md",[53,60,69,76,83,90],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M76ZJTRVA456GD7K8Y3EP82H","zarr-python","Stores and queries chunked N-D scientific arrays with Zarr-Python 3, including codecs, sharding, S3\u002FGCS storage, and NumPy\u002FDask\u002FXarray integration. Use for array layout, bounded I\u002FO, format migration, or scientific metadata preservation.","https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium\u002Fblob\u002Fmaster\u002Fskills\u002Fzarr-python\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":64,"licenseFileUrl":65,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M76ZJQZ15Q1HKC5V85NHE325","yeet","Publish local changes to GitHub by confirming scope, committing intentionally, pushing the branch, and opening a draft PR through the GitHub app from this plugin, with `gh` used only as a fallback where connector coverage is insufficient.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium\u002Fblob\u002Fmaster\u002Fskills\u002Fyeet\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium\u002Fblob\u002Fmaster\u002Fskills\u002Fyeet\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":64,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M76ZJ8ASZ4QYQ70Y6SBA4Z4S","xarray","N-dimensional labeled arrays and datasets in Python. Built on top of NumPy and Dask. It introduces labels in the form of dimensions, coordinates, and attributes on top of raw NumPy-like arrays, making data analysis in physical sciences more intuitive and less error-prone. Use for working with multi-dimensional scientific data, NetCDF\u002FGRIB\u002FZarr files, climate\u002Fweather\u002Foceanographic datasets, remote sensing, geospatial imaging, large out-of-memory datasets with Dask, and labeled array operations.","https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium\u002Fblob\u002Fmaster\u002Fskills\u002Fxarray\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M76ZHFBXD6VXPQ02VCEG202B","writing-mstest-tests","Use when asked to fix, rewrite, update, improve, modernize, show corrected code for, or explain existing MSTest tests or MSTest-specific configuration. Use for \"review\" when corrected code or edits are wanted, even for one pasted assertion or passing tests with bad failure output. Covers expected\u002Factual labels; generic Boolean, collection, string, numeric, null, identity, exception, hard-cast, and object[] checks; TestContext\u002Flifecycle; timeout\u002Fcancellation; OS\u002FCI conditions, retry, cleanup, parallelization, MSTest.Sdk project setup, and MSTESTxxxx. Honor the installed MSTest version. DO NOT USE to design new test cases (code-testing), perform report-only audits, create project files rather than explain MSTest setup, run tests, migrate frameworks, or handle non-MSTest\u002Fnon-.NET code.","https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium\u002Fblob\u002Fmaster\u002Fskills\u002Fwriting-mstest-tests\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M76ZDFDF4N88RH6HSYGS7GP2","wgs-prs","End-to-end WGS to polygenic risk score pipeline. Takes paired-end FASTQ files (or a pre-existing VCF) through nf-core\u002Fsarek for variant calling, applies VCF QC (normalisation, hard filtering, Ti\u002FTv and Het\u002FHom checks), then computes polygenic risk scores via the PGS Catalog. Fills the FASTQ to VCF gap upstream of the gwas-prs skill.","https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium\u002Fblob\u002Fmaster\u002Fskills\u002Fwgs-prs\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":64,"licenseFileUrl":94,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":19},"01M76ZCC1SC68J42QK4MDC8RCG","webapp-testing","Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.","https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium\u002Fblob\u002Fmaster\u002Fskills\u002Fwebapp-testing\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fstanfish06\u002Fskillquarium\u002Fblob\u002Fmaster\u002Fskills\u002Fwebapp-testing\u002FSKILL.md",[],[]]