Shell Routing through attributes on page (using source generators)

[PureWeen]

Description

Today, we must register each page in the AppShell on startup such as:

	public AppShell()
	{
		InitializeComponent();

		Routing.RegisterRoute(nameof(DetailsPage), typeof(DetailsPage));
	}

However, it would be nicer to align with how ASP.NET Core routing works and make it an attribute on the page. Since this would require assembly scanning today, this should be implemented as source generators for optimal performance.

(Public) API Changes

[Route(nameof(DetailsPage))]
public partial class DetailsPage : ContentPage

{

}

This would generate code necessary to register the DetailsPage with the route of DetailsPage.

Usage Scenarios

See above :)

Backward Compatibility

Would be an added option and an upgrade from the existing mechanism.

Difficulty

Medium

[pictos]

I can see value in that... But looking the spec, our services methods do that and a little bit more... I mean, a lot of devs love to use DI can we integrate our DI code with this SG?

[egvijayanand]

I can see value in that... But looking the spec, our services methods do that and a little bit more... I mean, a lot of devs love to use DI can we integrate our DI code with this SG?

Yes, both register routes and DI registration is being taken care of in the PR which is still under review.

And services can also be registered in the same fashion with the [MauiService] attribute (and it defaults to Singleton), useful for Popups and other services such as Dialogs.

[MauiService(ServiceLifetime.Transient)]
public partial class AppThemePopup : Popup
{
}

The enum ref. can further be reduced to its value with a global static using statement.

[pictos]

Just a heads up, our Popup can't be singleton for now... Because it's disposed when dismissed

[egvijayanand]

Yes, very well aware, and have been referencing it in the toolkit too.

The MauiService attribute takes one of the ServiceLifetime enum values as its constructor arg. Generic to adapt to service reg. supported in .NET MAUI startup. The default value is Singleton if the attribute is decorated on a class without any parameters. Examples below.

// Defaults to Singleton reg.
[MauiService]
public class DialogService
{
}

// Enum value parameter with (global) static using defined
// Transient reg.
[MauiService(Transient)]
public class AppThemePopup : Popup
{
}

[egvijayanand]

Translates to the following (types names fully qualified):

builder.Services.AddSingleton<DialogService>();

builder.Services.AddTransient<AppThemePopup>();

Support for TryAdd method construct and Interface based registration is also supported.

builder.Services.AddSingleton<IDialogService, DialogService>();

builder.Services.TryAddSingleton<DialogService>();

[pictos]

and this will be called where? SG can't modify the user code, so it can't be injected on Builder method.

[egvijayanand]

Currently designed as a partial method and its definition is source generated in the partial class.

The user has to plug in the invocation call in the .NET MAUI startup pipeline within the CreateMauiApp method.

builder.ConfigureDependencies();

And for registering the Routing details of Shell enabled Apps, a similar approach, a partial method in the source generated partial class for the Shell type.

The user has to plug in the invocation call in the constructor of the Shell page.

RegisterRoutes();

Feedback is most welcome if you people have any ideas on to improve this.

[pictos]

Why not does everything in one place?

[egvijayanand]

Have seen few projects having different Shell pages for mobile and desktop. Moreover, this approach will work for class library as well. Regards, Vijay Anand E G

…

________________________________ From: Pedro Jesus ***@***.***> Sent: Friday, February 24, 2023 7:52:15 AM To: CommunityToolkit/Maui ***@***.***> Cc: Vijay Anand E G ***@***.***>; Comment ***@***.***> Subject: Re: [CommunityToolkit/Maui] Shell Routing through attributes on page (using source generators) (Discussion #1004) Why not does everything in one place? — Reply to this email directly, view it on GitHub<#1004 (reply in thread)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ATRGWDBGRHNEZFHZJ345NF3WZALNPANCNFSM6AAAAAAU6ROWQE>. You are receiving this because you commented.Message ID: ***@***.***>

[pictos]

I mean, you could do the builder and routes registrations at the same place... If your SG be on our toolkit, you can use our helper methods for Shell and do everything in one go. You can see those methods here

[egvijayanand]

Description of the Proposed solution

Attribute-based shell routing and service registration in the DI container. Automated with (incremental) source generators.

Below are the two attributes that are defined to generate the source that automates the tasks while defining a shell route or to add a DI service into the .NET MAUI startup pipeline.

• Route
• MauiService

Route attribute

This can be defined on any Page inherited type so that it can be added to the Routes collection. In addition, the type will also be added to the DI service in the startup.

[Route]
public class SettingsPage : ContentPage
{
}

By default, the route name generated would be the name of the type itself. But can be modified with its properties.

Defines a constructor to help in the generalized case with two parameters for route and lifetime.

public class RouteAttribute : Attribute
{
  public RouteAttribute(string route, ServiceLifetime lifetime = ServiceLifetime.Singleton)
    => (Route, Lifetime) = (route, lifetime);
}

The Route attribute defines the following properties:

Property	Type	Remarks
Route	string	Defines a single route definition for the page.
Routes	string[]	Defines multiple route definitions for the same page and takes precedence over the Route property.
Lifetime	ServiceLifetime	Defines the lifetime of the page in the DI container. Defaults to Singleton if not defined.
ImplicitViewModel	bool	Usually, the ViewModel and the View (page here) are associated by names. In such cases, the name of the ViewModel is derived from the View, when this property is set to true.
ViewModelType	Type	Explicit definition of the ViewModel type and takes precedence over the ImplicitViewModel property.

[Route("settings")]
public class SettingsPage : ContentPage
{
}

[Route("search", ServiceLifetime.Transient, ImplicitViewModel = true)]
public class SearchPage : ContentPage
{
}

MauiService attribute

This can be defined on any type so that it can be added to the Services collection. of the MauiAppBuilder instance as a DI service in the .NET MAUI startup.

[MauiService]
public class DialogService
{
}

Defines a constructor to help in the generalized case that takes lifetime as a parameter.

[MauiService(ServiceLifetime.Transient)]
public class AppThemePopup : Popup
{
}

The MauiService attribute defines the following properties.

Property	Type	Remarks
Lifetime	ServiceLifetime	Defines the lifetime of the page in the DI container. Defaults to Singleton if not defined.
UseTryAdd	bool	Makes use of the TryAdd method construct while adding the type in the Services collection when this property is set to true.
RegisterFor	Type	Register the type for the type defined in this property, helpful for the type to be registered against an interface.

[MauiService(RegisterFor = typeof(INavigationService))]
public class NavigationService : INavigationService
{
}

[MauiService(UseTryAdd = true)]
public class MediaService
{
}

Output:

For each of the Shell pages defined, a partial method of the name RegisterRoutes with all those routes added as its method definition will get auto-generated. This method needs to be invoked in the constructor of the shell definition.

Assuming MauiApp1 as the project root namespace for the sample code.

User definition:

namespace MauiApp1;

public partial class AppShell : Shell
{
  public AppShell()
  {
    // Only relevant code is shown here. If defined as XAML, InitializeComponent(); would be here.
    RegisterRoutes();
  }
}

Source generated:

namespace MauiApp1;

partial class AppShell : Shell
{
  static partial void RegisterRoutes();

  static partial void RegisterRoutes()
  {
    Routing.RegisterRoute(nameof(global::MauiApp1.Views.SettingsPage), typeof(global::MauiApp1.Views.SettingsPage));
    Routing.RegisterRoute("search", typeof(global::MauiApp1.Views.SearchPage));
  }
}

For the services, a partial method of the name ConfigureDependencies with all those types in the Services collection as its method definition will get auto-generated. This method needs to be invoked within the CreateMauiApp() method.

User definition:

namespace MauiApp1;

public static partial class MauiProgram
{
  public static MauiApp CreateMauiApp()
  {
    // Only relevant code is shown here.
    var builder = MauiApp.CreateBuilder();
    // All other definitions
    builder.ConfigureDependencies();
    return builder;
  }
}

Source generated:

namespace MauiApp1;

static partial class MauiProgram
{
  static partial void ConfigureDependencies(this global::Microsoft.Maui.Hosting.MauiAppBuilder builder);

  static partial void ConfigureDependencies(this global::Microsoft.Maui.Hosting.MauiAppBuilder builder)
  {
    builder.Services.AddSingleton<global::MauiApp1.Services.DialogService>();
    builder.Services.AddSingleton<global::MauiApp1.Services.INavigationService, global::MauiApp1.Services.NavigationService>();
    builder.Services.TryAddSingleton<MediaService>();

    builder.Services.AddTransient<global::MauiApp1.Views.AppThemePopup>();
  }
}