routage ASP.NET Core Blazor

Cet article explique le routage des demandes d’application Blazor avec des conseils sur le routage statique et interactif, l'intégration du routage des points de terminaison d'ASP.NET Core, les événements de navigation, ainsi que les modèles et contraintes de routage pour les composants Razor.

Le routage dans Blazor est réalisé en fournissant un modèle de routage à chaque composant accessible de l'application par le biais d'une directive @page. Quand un fichier Razor avec une directive @page est compilé, la classe générée reçoit un RouteAttribute spécifiant le modèle de routage. Au moment de l’exécution, le routeur recherche les classes de composant avec un RouteAttribute et génère le rendu du composant dont le modèle de routage correspond à l’URL demandée.

Le composant suivant HelloWorld utilise un modèle d’itinéraire de /hello-world, et la page web rendue pour le composant est atteinte à l’URL /hello-worldrelative.

HelloWorld.razor :

@page "/hello-world"

<h1>Hello World!</h1>

Le composant précédent se charge dans le navigateur à /hello-world, que le composant soit ou non ajouté à la navigation de l’interface utilisateur de l’application en tant que lien.

Routage statique contre routage interactif

Cette section s’applique à Blazor Web App.

Si le pré-rendu est activé, le Blazor routeur (composant Router, <Router> dans Routes.razor) effectue un routage statique des composants pendant le rendu statique côté serveur (SSR statique). Ce type de routage est appelé routage statique.

Lorsqu’un mode de rendu interactif est attribué au Routes composant, le Blazor routeur devient interactif après le SSR statique avec routage statique sur le serveur. Ce type de routage est appelé routage interactif.

Les routeurs statiques utilisent le routage des points de terminaison et le chemin de requête HTTP pour déterminer le composant à afficher. Lorsque le routeur devient interactif, il utilise l’URL du document (l’URL dans la barre d’adresses du navigateur) pour déterminer le composant à afficher. Cela signifie que le routeur interactif peut changer dynamiquement le composant rendu si l’URL du document change dynamiquement pour une autre URL interne valide, et ce sans effectuer de requête HTTP pour récupérer le nouveau contenu de la page.

Le routage interactif empêche également le prérendu, car le nouveau contenu de la page n’est pas demandé auprès du serveur avec une demande de page normale. Pour plus d’informations, consultez ASP.NET Core persistance d'état pré-rendueBlazor.

Intégration du routage d'endpoint ASP.NET Core

Cette section s’applique aux Blazor Web Apps fonctionnant sur un circuit.

Une Blazor Web App est intégrée au routage de points de terminaison ASP.NET Core. Une application ASP.NET Core est configurée avec des points de terminaison pour les composants routables et le composant racine à rendre pour ces points de terminaison dans le fichier MapRazorComponentsProgram. Le composant racine par défaut (premier composant chargé) est le composant App (App.razor) :

app.MapRazorComponents<App>();

Modèles de route

Le composant Router active le routage vers les composants Razor et se trouve dans le composant Routes (Components/Routes.razor) de l’application.

Quand un composant Razor (.razor) avec une directive @page est compilé, la classe de composant générée reçoit un RouteAttribute spécifiant le modèle de route du composant.

Au démarrage de l’application, l’assembly spécifié en tant que AppAssembly du routeur est analysé afin de permettre la collecte des informations de route pour les composants de l’application ayant un RouteAttribute.

Au moment de l’exécution, le composant RouteView :

• Reçoit le RouteData de Router avec tous les paramètres de route.
• Affiche le composant spécifié avec sa disposition ainsi que toutes les autres dispositions imbriquées.

Spécifiez éventuellement un paramètre DefaultLayout avec une classe de disposition pour les composants qui ne spécifient pas de disposition avec la directive @layout. Les modèles de projet Blazor du framework spécifient le composant MainLayout (MainLayout.razor) en tant que disposition par défaut de l’application. Pour plus d'informations sur les layouts, consultez ASP.NET Core layoutsBlazor.

Les composants prennent en charge plusieurs modèles de route à l’aide de plusieurs directives @page. L’exemple de composant suivant se charge quand /blazor-route et /different-blazor-route sont demandés.

BlazorRoute.razor :

@page "/blazor-route"
@page "/different-blazor-route"

<h1>Routing Example</h1>

<p>
    This page is reached at either <code>/blazor-route</code> or 
    <code>/different-blazor-route</code>.
</p>

Importante

Pour que les URL soient résolues correctement, l’application doit inclure une balise <base> (emplacement du contenu <head>) avec le chemin de base de l’application spécifié dans l’attribut href. Pour plus d’informations, consultez chemin de base de l’application ASP.NET CoreBlazor.

Au lieu de spécifier le modèle de route sous forme de littéral de chaîne avec la directive @page, vous pouvez spécifier des modèles de route basés sur des constantes avec la directive @attribute.

Dans l’exemple suivant, la directive @page d’un composant est remplacée par la directive @attribute et le modèle de route basé sur des constantes dans Constants.CounterRoute, qui a la valeur « /counter » ailleurs dans l’application :

- @page "/counter"
+ @attribute [Route(Constants.CounterRoute)]

Définir le focus sur un élément dans la navigation

Le composant FocusOnNavigate définit le focus de l’IU sur un élément en fonction d’un sélecteur CSS, après avoir navigué d’une page à une autre.

<FocusOnNavigate RouteData="routeData" Selector="h1" />

Quand le composant Router accède à une nouvelle page, le composant FocusOnNavigate définit le focus sur l’en-tête de premier niveau de la page (<h1>). Il s’agit d’une stratégie courante permettant de garantir l’annonce de la navigation d’une page à une autre en cas d’utilisation d’ un lecteur d’écran.

Fournir du contenu personnalisé quand le contenu est introuvable

Pour les demandes où le contenu est introuvable, un Razor composant peut être affecté au Router paramètre du NotFoundPage composant. Le paramètre fonctionne en concert avec NavigationManager.NotFound, une méthode appelée dans le code du développeur qui déclenche une réponse introuvable. NavigationManager.NotFoundest décrit dans l’article suivant, ASP.NET Core Blazornavigation.

Le Blazor modèle de projet inclut une NotFound.razor page. Cette page s’affiche automatiquement chaque fois qu’elle NavigationManager.NotFound est appelée, ce qui permet de gérer les itinéraires manquants avec une expérience utilisateur cohérente.

NotFound.razor :

@page "/not-found"
@layout MainLayout

<h3>Not Found</h3>
<p>Sorry, the content you are looking for does not exist.</p>

Le NotFound composant est affecté au paramètre du NotFoundPage routeur. NotFoundPagePrend en charge le routage qui peut être utilisé dans le middleware de réexécution des pages de code d’état, y compris le middleware non Blazor.

Dans l’exemple suivant, le composant précédent NotFound est présent dans le dossier de Pages l’application et transmis au NotFoundPage paramètre :

<Router AppAssembly="@typeof(Program).Assembly" NotFoundPage="typeof(Pages.NotFound)">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" />
        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
    </Found>
</Router>

Pour plus d’informations, consultez l’article suivant sur la navigation ASP.NET CoreBlazor.

Effectuer un routage vers les composants à partir de plusieurs assemblys

Cette section s’applique à Blazor Web App.

Utilisez le Router paramètre du composant et le générateur AdditionalAssemblies de conventions de point de terminaison AddAdditionalAssemblies pour découvrir les composants routables dans des assemblys supplémentaires. Les sous-sections suivantes expliquent quand et comment utiliser chaque API.

Routage statique

Pour découvrir des composants routables à partir d’assemblages supplémentaires pour le rendu statique côté serveur (SSR statique), même si le routeur devient ensuite interactif pour le rendu interactif, les assemblages doivent être divulgués à l’infrastructure Blazor. Appeler la méthode AddAdditionalAssemblies avec les assemblages supplémentaires enchaînés à MapRazorComponents dans le fichier Program du projet serveur.

L’exemple suivant inclut les composants routables dans l’assembly BlazorSample.Client du projet à l’aide du fichier du _Imports.razor projet :

app.MapRazorComponents<App>()
    .AddAdditionalAssemblies(typeof(BlazorSample.Client._Imports).Assembly);

Remarque

Les instructions précédentes s’appliquent également dans les scénarios de bibliothèque de classes de composants. Des conseils importants supplémentaires pour les bibliothèques de classes et le SSR statique se trouvent dans ASP.NET Bibliothèques de classes principales Razor (RCL) avec rendu statique côté serveur (SSR statique).

Routage interactif

Un mode de rendu interactif peut être attribué au composant Routes (Routes.razor) pour que le routeur Blazor devienne interactif après le SSR statique et le routage statique sur le serveur. Par exemple, <Routes @rendermode="InteractiveServer" /> attribue un rendu interactif côté serveur (SSR interactif) au Routes composant. Le composant Router hérite du rendu interactif côté serveur (SSR interactif) du composant Routes. Le routeur devient interactif après le routage statique sur le serveur.

La navigation interne pour le routage interactif n’implique pas de demander le nouveau contenu de la page auprès du serveur. Par conséquent, le prérendu ne se produit pas pour les requêtes de pages internes. Pour plus d’informations, consultez ASP.NET Core persistance d'état pré-rendueBlazor.

Si le Routes composant est défini dans le projet serveur, le AdditionalAssemblies paramètre du Router composant doit inclure l’assembly .Client du projet. Cela permet au routeur de fonctionner correctement lorsqu’il est rendu de manière interactive.

Dans l’exemple suivant, le Routes composant se trouve dans le projet serveur et le _Imports.razor fichier du BlazorSample.Client projet indique l’assembly pour rechercher des composants routables :

<Router
    AppAssembly="..."
    AdditionalAssemblies="[ typeof(BlazorSample.Client._Imports).Assembly ]">
    ...
</Router>

Les assemblages supplémentaires sont analysés en plus de l'assemblage spécifié à AppAssembly.

Remarque

Les instructions précédentes s’appliquent également dans les scénarios de bibliothèque de classes de composants.

Par ailleurs, les composants routables n’existent que dans le projet .Client avec le rendu automatique ou WebWassembly interactif global appliqué, et le composant Routes est défini dans le projet .Client, et non dans le projet serveur. Dans ce cas, il n’existe pas d’assemblys externes avec des composants routables. Il n’est donc pas nécessaire de spécifier une valeur pour AdditionalAssemblies.

Paramètres de routage

Le routeur utilise des paramètres de route pour remplir les paramètres de composant correspondants avec le même nom. Les noms de paramètres de route ne respectent pas la casse. Dans l’exemple suivant, le paramètre text affecte la valeur du segment de route à la propriété Text du composant. Lorsqu’une demande est faite pour /route-parameter-1/amazing, le contenu est rendu sous forme de Blazor is amazing!.

RouteParameter1.razor :

@page "/route-parameter-1/{text}"

<h1>Route Parameter Example 1</h1>

<p>Blazor is @Text!</p>

@code {
    [Parameter]
    public string? Text { get; set; }
}

Les paramètres facultatifs sont pris en charge. Dans l’exemple suivant, le paramètre facultatif text affecte la valeur du segment de routage à la propriété Text du composant. Si le segment n’est pas présent, la valeur de Text est fantastic.

RouteParameter2.razor :

@page "/route-parameter-2/{text?}"

<h1>Route Parameter Example 2</h1>

<p>Blazor is @Text!</p>

@code {
    [Parameter]
    public string? Text { get; set; }

    protected override void OnParametersSet() => Text = Text ?? "fantastic";
}

Lorsque la méthode du cycle de vie OnInitialized{Async} est utilisée au lieu de la méthode du cycle de vie OnParametersSet{Async}, l’affectation par défaut de la propriété Text à fantastic ne se produit pas si l’utilisateur navigue dans le même composant. Par exemple, cette situation se produit lorsque l’utilisateur accède à /route-parameter-2/amazing depuis /route-parameter-2. À mesure que l’instance de composant persiste et accepte de nouveaux paramètres, la méthode OnInitialized n’est pas rappelée.

Contraintes d'itinéraire

Une contrainte de route impose la correspondance de type d'un segment de route à un composant.

Dans l’exemple suivant, la route vers le composant User correspond uniquement si :

• Un segment de route Id est présent dans l’URL de requête.
• Le segment Id est un type entier (int).

User.razor :

@page "/user/{Id:int}"

<h1>User Example</h1>

<p>User Id: @Id</p>

@code {
    [Parameter]
    public int Id { get; set; }
}

Les contraintes de route affichées dans le tableau suivant sont disponibles. Si vous souhaitez connaître les contraintes de route qui correspondent à la culture invariante, consultez l’avertissement situé sous le tableau pour plus d’informations.

Contrainte	Exemple	Exemples de correspondances	Invariant culture rapprochement
bool	{active:bool}	true, FALSE	Non
datetime	{dob:datetime}	2016-12-31, 2016-12-31 7:32pm	Oui
decimal	{price:decimal}	49.99, -1,000.01	Oui
double	{weight:double}	1.234, -1,001.01e8	Oui
float	{weight:float}	1.234, -1,001.01e8	Oui
guid	{id:guid}	00001111-aaaa-2222-bbbb-3333cccc4444, {00001111-aaaa-2222-bbbb-3333cccc4444}	Non
int	{id:int}	123456789, -123456789	Oui
long	{ticks:long}	123456789, -123456789	Oui
nonfile	{parameter:nonfile}	Pas BlazorSample.styles.css, pas favicon.ico	Oui

Avertissement

Les contraintes de routage qui vérifient que l’URL peut être convertie en type CLR (comme int ou DateTime) utilisent toujours la culture invariant. ces contraintes partent du principe que l’URL n’est pas localisable.

Les contraintes de route fonctionnent également avec les paramètres facultatifs. Dans l’exemple suivant, Id est obligatoire, mais Option est un paramètre de route booléen facultatif.

User.razor :

@page "/user/{id:int}/{option:bool?}"

<p>
    Id: @Id
</p>

<p>
    Option: @Option
</p>

@code {
    [Parameter]
    public int Id { get; set; }

    [Parameter]
    public bool Option { get; set; }
}

Éviter la capture de fichiers dans un paramètre de route

Le modèle de route suivant capture par inadvertance les chemins d’accès à la ressource statique dans son paramètre de route facultatif (Optional). Par exemple, la feuille de style de l’application (.styles.css) est capturée, ce qui interrompt les styles de l’application :

@page "/{optional?}"

...

@code {
    [Parameter]
    public string? Optional { get; set; }
}

Pour restreindre un paramètre de route à la capture des chemins d’accès autres que des fichiers, utilisez la contrainte :nonfile dans le modèle de route :

@page "/{optional:nonfile?}"

Paramètres de route fourre-tout

Les paramètres de route fourre-tout, qui capturent les chemins au-delà de plusieurs limites de dossiers, sont pris en charge dans les composants.

Les paramètres de route fourre-tout sont :

• Nommés pour correspondre au nom du segment de route. Le nommage ne respecte pas la casse.
• Type string. Le framework ne fournit pas de cast automatique.
• À la fin de l’URL.

CatchAll.razor :

@page "/catch-all/{*pageRoute}"

<h1>Catch All Parameters Example</h1>

<p>Add some URI segments to the route and request the page again.</p>

<p>
    PageRoute: @PageRoute
</p>

@code {
    [Parameter]
    public string? PageRoute { get; set; }
}

Pour l’URL /catch-all/this/is/a/test avec le modèle de route /catch-all/{*pageRoute}, la valeur de PageRoute est this/is/a/test.

Les barres obliques et les segments du chemin capturé sont décodés. Pour le modèle de route /catch-all/{*pageRoute}, l’URL /catch-all/this/is/a%2Ftest%2A donne this/is/a/test*.

Gérer les événements de navigation asynchrones avec OnNavigateAsync

Le composant Router prend en charge une fonctionnalité OnNavigateAsync. Le gestionnaire OnNavigateAsync est appelé quand l’utilisateur :

• Visite une route pour la première fois en y accédant directement dans son navigateur.
• Accède à une nouvelle route à l'aide d'un lien ou d'une invocation NavigationManager.NavigateTo, utilisée dans le code du développeur pour naviguer vers un URI. [ L’APINavigationManager est décrite dans l’article suivant, ASP.NET navigation principaleBlazor.]

<Router AppAssembly="typeof(App).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext args)
    {
        ...
    }
}

Pour obtenir un exemple qui utilise OnNavigateAsync, consultez Charger des assemblys en mode différé dans ASP.NET Core Blazor WebAssembly.

En cas de prérendu sur le serveur, OnNavigateAsync est exécuté deux fois :

• Une première fois quand le composant de point de terminaison demandé est affiché initialement de manière statique.
• Une deuxième fois quand le navigateur affiche le composant de point de terminaison.

Pour empêcher le code de développeur dans OnNavigateAsync de s’exécuter à deux reprises, le composant Routes peut stocker le NavigationContext afin de l’utiliser dans la méthode du cycle de vie OnAfterRender{Async}, où firstRender peut être vérifié. Pour plus d'informations, voir Prérendu avec JavaScript interop.

Gérer les annulations dans OnNavigateAsync

L’objet NavigationContext passé à la fonction de rappel de OnNavigateAsync contient un CancellationToken qui est attribué lorsqu'un nouvel événement de navigation se produit. Le rappel de OnNavigateAsync doit lever une exception au moment où ce jeton d’annulation est défini pour éviter de poursuivre l’exécution du rappel de OnNavigateAsync en cas de navigation obsolète.

Si un utilisateur accède à un point de terminaison, puis accède immédiatement après à un nouveau point de terminaison, l’application ne doit pas continuer à exécuter le rappel de OnNavigateAsync pour le premier point de terminaison.

Dans l’exemple suivant :

• Le jeton d’annulation est passé dans l’appel à PostAsJsonAsync, qui peut annuler la méthode POST si l’utilisateur quitte le point de terminaison /about.
• Le jeton d’annulation est défini durant une opération de prérécupération du produit si l’utilisateur quitte le point de terminaison /store.

@inject HttpClient Http
@inject ProductCatalog Products

<Router AppAssembly="typeof(App).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext context)
    {
        if (context.Path == "/about") 
        {
            var stats = new Stats { Page = "/about" };
            await Http.PostAsJsonAsync("api/visited", stats, 
                context.CancellationToken);
        }
        else if (context.Path == "/store")
        {
            var productIds = new[] { 345, 789, 135, 689 };

            foreach (var productId in productIds) 
            {
                context.CancellationToken.ThrowIfCancellationRequested();
                Products.Prefetch(productId);
            }
        }
    }
}

Remarque

Le fait de ne pas lever d’exception si le jeton d’annulation dans NavigationContext est annulé peut entraîner un comportement involontaire, par exemple le rendu d’un composant à partir d’une navigation précédente.

Interaction utilisateur avec du contenu <Navigating>

S’il existe un délai important pendant la navigation, par exemple pendant le chargement différé d’assemblages dans une application Blazor WebAssembly ou pour une connexion réseau lente à une application Blazor sur le côté serveur, le composant Router peut indiquer à l’utilisateur qu’une transition de page se produit.

En haut du composant qui spécifie le composant Router, ajoutez une directive @using pour l’espace de noms Microsoft.AspNetCore.Components.Routing :

@using Microsoft.AspNetCore.Components.Routing

Fournissez du contenu au paramètre Navigating à afficher lors des événements de transition de page.

Dans le contenu de l’élément routeur (<Router>...</Router>) :

<Navigating>
    <p>Loading the requested page&hellip;</p>
</Navigating>

Pour obtenir un exemple qui utilise la propriété Navigating, consultez Charger des assemblys en mode différé dans ASP.NET Core Blazor WebAssembly.