[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M756HM77RHK2ZJ53415Q3FST":3,"skill-same:01M756HM77RHK2ZJ53415Q3FST":51},{"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":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M756HM77RHK2ZJ53415Q3FST","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.","weiflycc-cmd\u002Fskills","weiflycc-cmd","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F250846518?v=4","01M756C4PFGZJWKK04WFB9S5XF","威飛工作室","01M756C4QJJ66QDXN2RN6SXY87",0,"MIT","https:\u002F\u002Fgithub.com\u002Fweiflycc-cmd\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdotnet-maui\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 [.NET MAUI deep linking docs](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Ffundamentals\u002Fapp-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## 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. Register detail-page routes in the `AppShell` constructor\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\"\n                          ContentTemplate=\"{DataTemplate views:DomesticCatsPage}\" \u002F>\n            \u003CShellContent Title=\"Wild\"\n                          ContentTemplate=\"{DataTemplate views:WildCatsPage}\" \u002F>\n        \u003C\u002FTab>\n        \u003CTab Title=\"Dogs\" Icon=\"dogs.png\">\n            \u003CShellContent ContentTemplate=\"{DataTemplate views:DogsPage}\" \u002F>\n        \u003C\u002FTab>\n    \u003C\u002FFlyoutItem>\n\n    \u003CTabBar>\n        \u003CShellContent Title=\"Home\" Icon=\"home.png\"\n                      ContentTemplate=\"{DataTemplate views:HomePage}\" \u002F>\n        \u003CShellContent Title=\"Settings\" Icon=\"settings.png\"\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 directly on the page class:\n\n```csharp\n[QueryProperty(nameof(AnimalId), \"id\")]\npublic partial class AnimalDetailsPage : ContentPage\n{\n    public string AnimalId { get; set; }\n}\n```\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 [.NET MAUI deep linking docs](https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Fmaui\u002Ffundamentals\u002Fapp-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## 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. Register detail-page routes in the `AppShell` constructor\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\"\n                          ContentTemplate=\"{DataTemplate views:DomesticCatsPage}\" \u002F>\n            \u003CShellContent Title=\"Wild\"\n                          ContentTemplate=\"{DataTemplate views:WildCatsPage}\" \u002F>\n        \u003C\u002FTab>\n        \u003CTab Title=\"Dogs\" Icon=\"dogs.png\">\n            \u003CShellContent ContentTemplate=\"{DataTemplate views:DogsPage}\" \u002F>\n        \u003C\u002FTab>\n    \u003C\u002FFlyoutItem>\n\n    \u003CTabBar>\n        \u003CShellContent Title=\"Home\" Icon=\"home.png\"\n                      ContentTemplate=\"{DataTemplate views:HomePage}\" \u002F>\n        \u003CShellContent Title=\"Settings\" Icon=\"settings.png\"\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 directly on the page class:\n\n```csharp\n[QueryProperty(nameof(AnimalId), \"id\")]\npublic partial class AnimalDetailsPage : ContentPage\n{\n    public string AnimalId { get; set; }\n}\n```\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},"main","5810d492c9b301d8227f932bf87b5c954c4fa4d6","plugins\u002Fdotnet-maui\u002Fskills\u002Fmaui-shell-navigation","https:\u002F\u002Fgithub.com\u002Fweiflycc-cmd\u002Fskills","https:\u002F\u002Fgithub.com\u002Fweiflycc-cmd","weiflycc.com","2026-11-10 03:26:55",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add weiflycc-cmd\u002Fskills --skill maui-shell-navigation",{"tool":37,"command":38},"bunx","bunx skills add weiflycc-cmd\u002Fskills --skill maui-shell-navigation",{"tool":40,"command":41},"pnpm","pnpm dlx skills add weiflycc-cmd\u002Fskills --skill maui-shell-navigation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fweiflycc-cmd\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdotnet-maui\u002Fskills\u002Fmaui-shell-navigation\u002FSKILL.md",true,[45],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Fshell-navigation-api.md","REFERENCE","参考文档",9219,"https:\u002F\u002Fgithub.com\u002Fweiflycc-cmd\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdotnet-maui\u002Fskills\u002Fmaui-shell-navigation\u002Freferences\u002Fshell-navigation-api.md",[52,59,66,73,80,87],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":19},"01M76SGT4WG5682JQJ0V3NSK6X","system-text-json-net11","Provides guidance on new System.Text.Json APIs introduced in .NET 11. It covers typed JsonTypeInfo access via GetTypeInfo\u003CT> and TryGetTypeInfo\u003CT> on JsonSerializerOptions, and the new JsonNamingPolicy.PascalCase static property. Use when serializing or deserializing JSON in .NET 11 applications and needing typed metadata access or PascalCase property naming.","https:\u002F\u002Fgithub.com\u002Fweiflycc-cmd\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdotnet11\u002Fskills\u002Fsystem-text-json-net11\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M76SGPNZYYV9BCZJW7BF7J8A","nuget-trusted-publishing","Set up NuGet trusted publishing (OIDC) on a GitHub Actions repo — replaces long-lived API keys with short-lived tokens. USE FOR: trusted publishing, NuGet OIDC, keyless NuGet publish, migrate from NuGet API key, NuGet\u002Flogin, secure NuGet publishing. DO NOT USE FOR: publishing to private feeds or Azure Artifacts (OIDC is nuget.org only). INVOKES: shell (powershell or bash), edit, create, ask_user for guided repo setup.","https:\u002F\u002Fgithub.com\u002Fweiflycc-cmd\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdotnet\u002Fskills\u002Fnuget-trusted-publishing\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M76SGHVNBNVM1DMVDYTMAE5G","dotnet-pinvoke","Correctly call native (C\u002FC++) libraries from .NET using P\u002FInvoke and LibraryImport. Covers function signatures, string marshalling, memory lifetime, SafeHandle, and cross-platform patterns. USE FOR: writing new P\u002FInvoke or LibraryImport declarations, reviewing or debugging existing native interop code, wrapping a C or C++ library for use in .NET, diagnosing crashes, memory leaks, or corruption at the managed\u002Fnative boundary. DO NOT USE FOR: COM interop, C++\u002FCLI mixed-mode assemblies, or pure managed code with no native dependencies.","https:\u002F\u002Fgithub.com\u002Fweiflycc-cmd\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdotnet\u002Fskills\u002Fdotnet-pinvoke\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M76SGDB9Z3GSB1CFW314NC84","csharp-scripts","Run file-based C# apps with the .NET CLI when the user explicitly wants C#\u002F.NET code without creating a project. Use for C# language\u002FAPI experiments, one-file C# apps, small multi-file C# apps composed with `#:include`\u002F`#:exclude`, or C# file-based apps linked with `#:ref`. Do not use for language-agnostic throwaway scripts, generic computations, Python\u002FPowerShell-style automation, full projects, or existing app integration.","https:\u002F\u002Fgithub.com\u002Fweiflycc-cmd\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdotnet\u002Fskills\u002Fcsharp-scripts\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M76SG805T8W764WAKB1NP3CJ","thread-abort-migration","Guides migration of .NET Framework Thread.Abort usage to cooperative cancellation in modern .NET. USE FOR: modernizing code that calls Thread.Abort, catching ThreadAbortException, replacing Thread.ResetAbort, replacing Thread.Interrupt for thread termination, resolving PlatformNotSupportedException or SYSLIB0006 after retargeting to .NET 6+, migrating ASP.NET Response.End or Response.Redirect(url, true) which internally call Thread.Abort. DO NOT USE FOR: code that only uses Thread.Join, Thread.Sleep, or Thread.Start without any abort, interrupt, or ThreadAbortException usage — these APIs work identically in modern .NET and need no migration. Also not for projects staying on .NET Framework, or Thread.Abort usage inside third-party libraries you do not control.","https:\u002F\u002Fgithub.com\u002Fweiflycc-cmd\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdotnet-upgrade\u002Fskills\u002Fthread-abort-migration\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M76SG2588ZJBE5C51HYJJSKV","migrate-nullable-references","Enable nullable reference types in a C# project and systematically resolve all warnings. USE FOR: adopting NRTs in existing codebases, file-by-file or project-wide migration, fixing CS8602\u002FCS8618\u002FCS86xx warnings, annotating APIs for nullability, cleaning up null-forgiving operators, upgrading dependencies with new nullable annotations. DO NOT USE FOR: projects already fully migrated with zero warnings (unless auditing suppressions), fixing a handful of nullable warnings in code that already has NRTs enabled, suppressing warnings without fixing them, C# 7.3 or earlier projects. INVOKES: Get-NullableReadiness.ps1 scanner script.","https:\u002F\u002Fgithub.com\u002Fweiflycc-cmd\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdotnet-upgrade\u002Fskills\u002Fmigrate-nullable-references\u002FSKILL.md",[],[]]