Enhances XAML Navigation and Dialog Features

Adds attached properties for tabbed page navigation and appearance.
Introduces the ability to specify navigation types when going back.
Adds logging for navigation failures and provides a way to add services
required by markup extensions to prevent runtime errors.

Author: dansiegel

src/Maui/Prism.Maui/Dialogs/Xaml/ShowDialogExtension.cs

@@ -1,4 +1,4 @@
-using System.Windows.Input;
+using System.Windows.Input;
 using Microsoft.Extensions.Logging;
 using Prism.Ioc;
 using Prism.Navigation.Xaml;
@@ -7,6 +7,7 @@
 namespace Prism.Dialogs.Xaml;
 
 [ContentProperty(nameof(Name))]
+[RequireService([typeof(IProvideValueTarget)])]
 public class ShowDialogExtension : TargetAwareExtensionBase<ICommand>, ICommand
 {
     public static readonly BindableProperty NameProperty =

src/Maui/Prism.Maui/Navigation/Regions/Xaml/RegionManager.cs

@@ -14,7 +14,7 @@ namespace Prism.Navigation.Regions.Xaml;
 /// </summary>
 public static class RegionManager
 {
-    private static readonly WeakDelegatesManager updatingRegionsListeners = new WeakDelegatesManager();
+    private static readonly WeakDelegatesManager updatingRegionsListeners = new ();
 
     private static readonly BindableProperty ObservableRegionProperty =
         BindableProperty.CreateAttached("ObservableRegion", typeof(ObservableObject<IRegion>), typeof(RegionManager), null);

src/Maui/Prism.Maui/Navigation/Xaml/GoBackExtension.cs

@@ -1,8 +1,9 @@
-
+
 namespace Prism.Navigation.Xaml;
 
 [ContentProperty(nameof(GoBackType))]
-public class GoBackExtension : NavigationExtensionBase
+[RequireService([typeof(IProvideValueTarget)])]
+public partial class GoBackExtension : NavigationExtensionBase
 {
     public static readonly BindableProperty GoBackTypeProperty =
         BindableProperty.Create(nameof(GoBackType), typeof(GoBackType), typeof(GoBackExtension), GoBackType.Default);

src/Maui/Prism.Maui/Navigation/Xaml/GoBackType.cs

@@ -1,8 +1,17 @@
-
 namespace Prism.Navigation.Xaml;
 
+/// <summary>
+/// Specifies the type of navigation to perform when going back in the navigation stack.
+/// </summary>
 public enum GoBackType
 {
+    /// <summary>
+    /// Performs the default go back operation, navigating to the previous page in the stack.
+    /// </summary>
     Default = 0,
+
+    /// <summary>
+    /// Navigates back to the root page of the navigation stack.
+    /// </summary>
     ToRoot = 1
 }

src/Maui/Prism.Maui/Navigation/Xaml/NavigateToExtension.cs

@@ -1,18 +1,30 @@
-
+using Microsoft.Extensions.Logging;
+
 namespace Prism.Navigation.Xaml;
 
+/// <summary>
+/// A markup extension that enables navigation to a specified page by name using Prism's navigation service.
+/// </summary>
 [ContentProperty(nameof(Name))]
-public class NavigateToExtension : NavigationExtensionBase
+[RequireService([typeof(IProvideValueTarget)])]
+public partial class NavigateToExtension : NavigationExtensionBase
 {
+    /// <summary>
+    /// Identifies the <see cref="Name"/> bindable property.
+    /// </summary>
     public static readonly BindableProperty NameProperty =
         BindableProperty.Create(nameof(Name), typeof(string), typeof(NavigateToExtension), null);
 
+    /// <summary>
+    /// Gets or sets the name of the page to navigate to.
+    /// </summary>
     public string Name
     {
         get => (string)GetValue(NameProperty);
         set => SetValue(NameProperty, value);
     }
 
+    /// <inheritdoc/>
     protected override async Task HandleNavigation(INavigationParameters parameters, INavigationService navigationService)
     {
         AddKnownNavigationParameters(parameters);
@@ -24,8 +36,12 @@ protected override async Task HandleNavigation(INavigationParameters parameters,
         }
     }
 
+    /// <inheritdoc/>
     protected override void Log(Exception ex, INavigationParameters parameters)
     {
-        // TODO: Determine a good way to log
+        if (Logger.IsEnabled(LogLevel.Error))
+        {
+            Logger.LogError(ex, "Navigation to {PageName} failed with parameters: {Parameters}", Name, parameters);
+        }
     }
 }

src/Maui/Prism.Maui/Navigation/Xaml/NavigationExtensionBase.cs

@@ -5,32 +5,60 @@
 
 namespace Prism.Navigation.Xaml;
 
+/// <summary>
+/// Provides a base class for navigation extensions in XAML, implementing <see cref="ICommand"/> for navigation actions.
+/// </summary>
 public abstract class NavigationExtensionBase : TargetAwareExtensionBase<ICommand>, ICommand
 {
+    /// <summary>
+    /// Identifies the <see cref="Animated"/> bindable property.
+    /// </summary>
     public static readonly BindableProperty AnimatedProperty =
         BindableProperty.Create(nameof(Animated), typeof(bool), typeof(NavigationExtensionBase), true);
 
+    /// <summary>
+    /// Identifies the <see cref="UseModalNavigation"/> bindable property.
+    /// </summary>
     public static readonly BindableProperty UseModalNavigationProperty =
         BindableProperty.Create(nameof(UseModalNavigation), typeof(bool?), typeof(NavigationExtensionBase), null);
 
+    /// <summary>
+    /// Gets a value indicating whether a navigation operation is currently in progress.
+    /// </summary>
     protected internal bool IsNavigating { get; private set; }
 
+    /// <summary>
+    /// Gets or sets a value indicating whether navigation should be animated.
+    /// </summary>
     public bool Animated
     {
         get => (bool)GetValue(AnimatedProperty);
         set => SetValue(AnimatedProperty, value);
     }
 
+    /// <summary>
+    /// Gets or sets a value indicating whether modal navigation should be used.
+    /// </summary>
     public bool? UseModalNavigation
     {
         get => (bool?)GetValue(UseModalNavigationProperty);
         set => SetValue(UseModalNavigationProperty, value);
     }
 
+    /// <summary>
+    /// Determines whether the command can execute in its current state.
+    /// </summary>
+    /// <param name="parameter">Data used by the command. If the command does not require data, this object can be set to null.</param>
+    /// <returns>true if the command can execute; otherwise, false.</returns>
     public bool CanExecute(object parameter) => Page is not null && !IsNavigating;
 
+    /// <inheritdoc/>
     public event EventHandler CanExecuteChanged;
 
+    /// <summary>
+    /// Executes the navigation command.
+    /// </summary>
+    /// <param name="parameter">The navigation parameters.</param>
     public async void Execute(object parameter)
     {
         var parameters = parameter.ToNavigationParameters(TargetElement);
@@ -51,19 +79,44 @@ public async void Execute(object parameter)
         }
     }
 
+    /// <summary>
+    /// Provides the value of the extension, which is the command itself.
+    /// </summary>
+    /// <param name="serviceProvider">The service provider.</param>
+    /// <returns>The command instance.</returns>
     protected override ICommand ProvideValue(IServiceProvider serviceProvider) =>
         this;
 
+    /// <summary>
+    /// Logs navigation errors.
+    /// </summary>
+    /// <param name="ex">The exception that occurred.</param>
+    /// <param name="parameters">The navigation parameters.</param>
     protected virtual void Log(Exception ex, INavigationParameters parameters)
     {
-        // TODO: Determine a good way to log
-        Logger.LogError(ex, "Error Navigating: \n[exception]");
+        if (Logger.IsEnabled(LogLevel.Error))
+        {
+            Logger.LogError(ex, "Error Navigating: \n[exception]");
+        }
     }
 
+    /// <summary>
+    /// Handles the navigation logic. Must be implemented by derived classes.
+    /// </summary>
+    /// <param name="parameters">The navigation parameters.</param>
+    /// <param name="navigationService">The navigation service.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     protected abstract Task HandleNavigation(INavigationParameters parameters, INavigationService navigationService);
 
+    /// <summary>
+    /// Raises the <see cref="CanExecuteChanged"/> event.
+    /// </summary>
     protected void RaiseCanExecuteChanged() => CanExecuteChanged?.Invoke(this, EventArgs.Empty);
 
+    /// <summary>
+    /// Adds known navigation parameters such as <see cref="KnownNavigationParameters.Animated"/> and <see cref="KnownNavigationParameters.UseModalNavigation"/> to the provided <see cref="INavigationParameters"/>.
+    /// </summary>
+    /// <param name="parameters">The navigation parameters to which known values will be added.</param>
     protected void AddKnownNavigationParameters(INavigationParameters parameters)
     {
         parameters.Add(KnownNavigationParameters.Animated, Animated);
@@ -72,6 +125,10 @@ protected void AddKnownNavigationParameters(INavigationParameters parameters)
             parameters.Add(KnownNavigationParameters.UseModalNavigation, UseModalNavigation);
     }
 
+    /// <summary>
+    /// Called when a property value changes.
+    /// </summary>
+    /// <param name="propertyName">The name of the property that changed.</param>
     protected override void OnPropertyChanged([CallerMemberName] string propertyName = null)
     {
         base.OnPropertyChanged(propertyName);

src/Maui/Prism.Maui/Navigation/Xaml/TabbedPage.cs

@@ -1,31 +1,88 @@
-namespace Prism.Navigation.Xaml;
+namespace Prism.Navigation.Xaml;
 
+/// <summary>
+/// Provides attached properties for tabbed page navigation and appearance in .NET MAUI applications.
+/// </summary>
 public static class TabbedPage
 {
+    /// <summary>
+    /// Identifies the <c>TitleBindingSource</c> attached property.
+    /// Determines the source for the tab title binding.
+    /// </summary>
     public static BindableProperty TitleBindingSourceProperty =
-        BindableProperty.CreateAttached("TitleBindingSource", typeof(TabBindingSource), typeof(TabbedPage), TabBindingSource.RootPage);
+        BindableProperty.CreateAttached(
+            "TitleBindingSource",
+            typeof(TabBindingSource),
+            typeof(TabbedPage),
+            TabBindingSource.RootPage);
 
+    /// <summary>
+    /// Identifies the <c>Title</c> attached property.
+    /// Sets the title for a tab in a <see cref="Microsoft.Maui.Controls.TabbedPage"/>.
+    /// </summary>
     public static BindableProperty TitleProperty =
-        BindableProperty.CreateAttached("Title", typeof(string), typeof(TabbedPage), null);
+        BindableProperty.CreateAttached(
+            "Title",
+            typeof(string),
+            typeof(TabbedPage),
+            null);
 
+    /// <summary>
+    /// Identifies the <c>IconImageSource</c> attached property.
+    /// Sets the icon image source for a tab in a <see cref="Microsoft.Maui.Controls.TabbedPage"/>.
+    /// </summary>
     public static BindableProperty IconImageSourceProperty =
-        BindableProperty.CreateAttached("IconImageSource", typeof(ImageSource), typeof(TabbedPage), null);
+        BindableProperty.CreateAttached(
+            "IconImageSource",
+            typeof(ImageSource),
+            typeof(TabbedPage),
+            null);
 
+    /// <summary>
+    /// Gets the value of the <c>TitleBindingSource</c> attached property from the specified <see cref="Page"/>.
+    /// </summary>
+    /// <param name="page">The page from which to get the property value.</param>
+    /// <returns>The <see cref="TabBindingSource"/> value.</returns>
     public static TabBindingSource GetTitleBindingSource(Page page) =>
         (TabBindingSource)page.GetValue(TitleBindingSourceProperty);
 
+    /// <summary>
+    /// Sets the value of the <c>TitleBindingSource</c> attached property on the specified <see cref="Page"/>.
+    /// </summary>
+    /// <param name="page">The page on which to set the property value.</param>
+    /// <param name="bindingSource">The <see cref="TabBindingSource"/> value to set.</param>
     public static void SetTitleBindingSource(Page page, TabBindingSource bindingSource) =>
         page.SetValue(TitleBindingSourceProperty, bindingSource);
 
+    /// <summary>
+    /// Gets the value of the <c>Title</c> attached property from the specified <see cref="Page"/>.
+    /// </summary>
+    /// <param name="page">The page from which to get the property value.</param>
+    /// <returns>The title string.</returns>
     public static string GetTitle(Page page) =>
         (string)page.GetValue(TitleProperty);
 
+    /// <summary>
+    /// Sets the value of the <c>Title</c> attached property on the specified <see cref="Page"/>.
+    /// </summary>
+    /// <param name="page">The page on which to set the property value.</param>
+    /// <param name="title">The title string to set.</param>
     public static void SetTitle(Page page, string title) =>
         page.SetValue(TitleProperty, title);
 
+    /// <summary>
+    /// Gets the value of the <c>IconImageSource</c> attached property from the specified <see cref="Page"/>.
+    /// </summary>
+    /// <param name="page">The page from which to get the property value.</param>
+    /// <returns>The <see cref="ImageSource"/> for the tab icon.</returns>
     public static ImageSource GetIconImageSource(Page page) =>
         (ImageSource)page.GetValue(IconImageSourceProperty);
 
+    /// <summary>
+    /// Sets the value of the <c>IconImageSource</c> attached property on the specified <see cref="Page"/>.
+    /// </summary>
+    /// <param name="page">The page on which to set the property value.</param>
+    /// <param name="imageSource">The <see cref="ImageSource"/> to set as the tab icon.</param>
     public static void SetIconImageSource(Page page, ImageSource imageSource) =>
         page.SetValue(IconImageSourceProperty, imageSource);
-}
+}