Routage et navigation dans ASP.NET Core Blazor Hybrid

Cet article explique comment gérer le routage et la navigation des requêtes dans les applications Blazor Hybrid.

Comportement de routage des requêtes d’URI

Comportement de routage des requêtes d’URI par défaut :

• Un lien est interne si le nom d’hôte et le schéma correspondent entre l’URI d’origine de l’application et l’URI de requête. Lorsque les noms d’hôte et les schémas ne correspondent pas ou si le lien définit target="_blank", le lien est considéré comme externe.
• Si le lien est interne, le lien est ouvert dans BlazorWebView par l’application.
• Si le lien est externe, le lien est ouvert par une application déterminée par l’appareil en fonction du gestionnaire inscrit de l’appareil pour le schéma du lien.
• Pour les liens internes qui semblent requérir un fichier, car le dernier segment de l’URI utilise la notation par points (par exemple, /file.x, /Maryia.Melnyk, /image.gif) mais qui ne pointent pas vers un contenu statique :
  • WPF et Windows Forms : le contenu de la page hôte est renvoyé.
  • .NET MAUI : une réponse 404 est renvoyée.

Pour modifier le comportement de gestion des liens pour les liens qui ne définissent pas target="_blank", inscrivez l’événement UrlLoading et définissez la propriété UrlLoadingEventArgs.UrlLoadingStrategy. L’énumération UrlLoadingStrategy permet de définir le comportement de gestion des liens sur l’une des valeurs suivantes :

• OpenExternally : chargez l’URL à l’aide d’une application déterminée par l’appareil. Il s’agit de la stratégie par défaut pour les URI avec un hôte externe.
• OpenInWebView : chargez l’URL dans le BlazorWebView. Il s’agit de la stratégie par défaut pour les URL avec un hôte correspondant à l’origine de l’application. N’utilisez pas cette stratégie pour les liens externes, sauf si vous pouvez vous assurer que l’URI de destination est entièrement fiable.
• CancelLoad : annule la tentative de chargement d’URL en cours.

La propriété UrlLoadingEventArgs.Url est utilisée pour obtenir ou définir dynamiquement l’URL.

Avertissement

Les liens externes sont ouverts dans une application déterminée par l’appareil. L’ouverture de liens externes dans un BlazorWebView peut introduire des failles de sécurité et ne doit pas être activée, sauf si vous pouvez garantir que les liens externes sont entièrement fiables.

Documentation sur l’API :

• .NET MAUI: BlazorWebView.UrlLoading
• WPF : BlazorWebView.UrlLoading
• Windows Forms : BlazorWebView.UrlLoading

L’espace de noms Microsoft.AspNetCore.Components.WebView est requis pour les exemples suivants :

using Microsoft.AspNetCore.Components.WebView;

Ajoutez le gestionnaire d’événements suivant au constructeur du Page où le BlazorWebView est créé, qui se trouve MainPage.xaml.cs dans une application créée à partir du modèle de projet .NET MAUI.

blazorWebView.UrlLoading += 
    (sender, urlLoadingEventArgs) =>
    {
        if (urlLoadingEventArgs.Url.Host != "0.0.0.0")
        {
            urlLoadingEventArgs.UrlLoadingStrategy = 
                UrlLoadingStrategy.OpenInWebView;
        }
    };

Ajoutez l’attribut UrlLoading="Handle_UrlLoading" au contrôle BlazorWebView dans le fichier .xaml :

<blazor:BlazorWebView HostPage="wwwroot\index.html" 
    Services="{StaticResource services}" 
    x:Name="blazorWebView" 
    UrlLoading="Handle_UrlLoading">

Ajoutez le gestionnaire d’événements dans le fichier .xaml.cs :

private void Handle_UrlLoading(object sender, 
    UrlLoadingEventArgs urlLoadingEventArgs)
{
    if (urlLoadingEventArgs.Url.Host != "0.0.0.0")
    {
        urlLoadingEventArgs.UrlLoadingStrategy = 
            UrlLoadingStrategy.OpenInWebView;
    }
}

Dans le constructeur du formulaire contenant le contrôle BlazorWebView, ajoutez l’inscription d’événement suivante :

blazorWebView.UrlLoading += 
    (sender, urlLoadingEventArgs) =>
    {
        if (urlLoadingEventArgs.Url.Host != "0.0.0.0")
        {
            urlLoadingEventArgs.UrlLoadingStrategy = 
                UrlLoadingStrategy.OpenInWebView;
        }
    };

Obtenir ou définir un chemin pour la navigation initiale

Utilisez la propriété BlazorWebView.StartPath pour obtenir ou définir le chemin de la navigation initiale dans le contexte de navigation Blazor quand le composant Razor est chargé. Le chemin de début par défaut est le chemin d’URL racine relatif (/).

Dans le balisage XAML MainPage (MainPage.xaml), spécifiez le chemin de début. L’exemple suivant définit le chemin sur une page d’accueil à l’adresse /welcome :

<BlazorWebView ... StartPath="/welcome" ...>
    ...
<BlazorWebView>

Vous pouvez également définir le chemin d’accès de démarrage dans le constructeur MainPage (MainPage.xaml.cs) :

blazorWebView.StartPath = "/welcome";

Dans le concepteur MainWindow (MainWindow.xaml), spécifiez le chemin de début. L’exemple suivant définit le chemin sur une page d’accueil à l’adresse /welcome :

<blazor:BlazorWebView ... StartPath="/welcome" ...>
    ...
</blazor:BlazorWebView>

Dans le constructeur Form1 du fichier Form1.cs, spécifiez le chemin de début. L’exemple suivant définit le chemin sur une page d’accueil à l’adresse /welcome :

blazorWebView1.StartPath = "/welcome";

Navigation entre les pages et les composants Razor

Cette section explique comment naviguer entre les pages de contenu .NET MAUI et les composants Razor.

Le modèle de projet hybride .NET MAUIBlazor n’est pas une application basée sur un interpréteur de commandes. Par conséquent, la navigation basée sur l’URI pour les applications basées sur un interpréteur de commandes n’est pas adaptée à un projet basé sur le modèle de projet. Les exemples de cette section utilisent un NavigationPage pour effectuer une navigation sans modèle ou modale.

Dans l’exemple suivant :

• L’espace de noms de l’application est MauiBlazor, ce qui correspond au nom de projet suggéré dans le tutorielGénérer une .NET MAUIBlazor Hybrid application.
• Un ContentPage est placé dans un nouveau dossier ajouté à l’application nommée Views.

Dans App.xaml.cs, créez le MainPage en tant que NavigationPage en effectuant la modification suivante :

- MainPage = new MainPage();
+ MainPage = new NavigationPage(new MainPage());

Views/NavigationExample.xaml:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:MauiBlazor"
             x:Class="MauiBlazor.Views.NavigationExample"
             Title="Navigation Example"
             BackgroundColor="{DynamicResource PageBackgroundColor}">
    <StackLayout>
        <Label Text="Navigation Example"
               VerticalOptions="Center"
               HorizontalOptions="Center"
               FontSize="24" />
        <Button x:Name="CloseButton" 
                Clicked="CloseButton_Clicked" 
                Text="Close" />
    </StackLayout>
</ContentPage>

Dans le fichier de code NavigationExample suivant, le gestionnaire d’événements CloseButton_Clicked du bouton de fermeture appelle PopAsync pour désactiver ContentPage de la pile de navigation.

Views/NavigationExample.xaml.cs:

namespace MauiBlazor.Views;

public partial class NavigationExample : ContentPage
{
    public NavigationExample()
    {
        InitializeComponent();
    }

    private async void CloseButton_Clicked(object sender, EventArgs e)
    {
        await Navigation.PopAsync();
    }
}

Dans un composant Razor :

• Ajoutez l’espace de noms pour les pages de contenu de l’application. Dans l’exemple suivant, l’espace de noms est MauiBlazor.Views.
• Ajoutez un élément HTML button avec un @onclickgestionnaire d’événements pour ouvrir la page de contenu. La méthode du gestionnaire d’événements est nommée OpenPage.
• Dans le gestionnaire d’événements, appelez PushAsync pour envoyer (push) le ContentPage, NavigationExample, sur la pile de navigation.

L’exemple suivant est basé sur le composant Index dans le modèle de projet .NET MAUIBlazor.

Pages/Index.razor:

@page "/"
@using MauiBlazor.Views

<h1>Hello, world!</h1>

Welcome to your new app.

<SurveyPrompt Title="How is Blazor working for you?" />

<button class="btn btn-primary" @onclick="OpenPage">Open</button>

@code {
    private async void OpenPage()
    {
        await App.Current.MainPage.Navigation.PushAsync(new NavigationExample());
    }
}

Pour modifier l’exemple précédent en navigation modale :

• Dans la méthode CloseButton_Clicked (Views/NavigationExample.xaml.cs), remplacez PopAsync par PopModalAsync :

  - await Navigation.PopAsync();
  + await Navigation.PopModalAsync();
  

• Dans la méthode OpenPage (Pages/Index.razor), remplacez PushAsync par PushModalAsync :

  - await App.Current.MainPage.Navigation.PushAsync(new NavigationExample());
  + await App.Current.MainPage.Navigation.PushModalAsync(new NavigationExample());
  

Pour plus d’informations, consultez les ressources suivantes :

• NavigationPage article (.NET MAUI documentation)
• NavigationPage (Documentation sur l’API)

Lien d’application (lien profond)

Il est souvent souhaitable de connecter un site web et une application mobile afin que des liens sur un site web lancent l’application mobile et y affichent du contenu. Le lien d’application, également appelée lien profond, est une technique qui permet à un appareil mobile de répondre à un URI et de lancer du contenu dans une application mobile représentée par l’URI.

Pour plus d’informations, consultez les articles suivants dans la documentation .NET MAUI :

• Liens d’application Android
• Liens universels Apple