chemin de base de l’application ASP.NET Core Blazor

Cet article explique le chemin de base de l’application dans les applications ASP.NET Core Blazor , y compris les instructions de configuration.

Le chemin de base de l’application est le chemin URL racine de l’application. Le routage réussi dans les applications Blazor nécessite la configuration de l’infrastructure pour tout chemin d’URL racine qui n’est pas au chemin / de base de l’application par défaut.

Prenez en compte l’application ASP.NET Core et la sous-application Blazor suivantes :

• L’application ASP.NET Core est nommée MyApp :
  • L’application réside physiquement dans d:/MyApp.
  • Les demandes sont reçues à l’adresse https://www.contoso.com/{MYAPP RESOURCE}.
• Une application Blazor nommée CoolApp est une sous-application de MyApp :
  • La sous-application réside physiquement dans d:/MyApp/CoolApp.
  • Les demandes sont reçues à l’adresse https://www.contoso.com/CoolApp/{COOLAPP RESOURCE}.

Sans configuration supplémentaire pour CoolApp, la sous-application de ce scénario n’a aucune connaissance de l’emplacement où elle réside sur le serveur. Par exemple, l’application ne peut pas construire des URL relatives correctes pour ses ressources sans savoir qu’elle réside à l’emplacement du chemin URL relatif /CoolApp/. Ce scénario s’applique également dans divers scénarios de proxy inverse et d’hébergement quand une application n’est pas hébergée à l’emplacement d’un chemin URL racine.

Contexte

La destination d’une balise d’ancrage (href) peut être composée d’un des deux points de terminaison suivants :

• Emplacements absolus qui incluent un schéma (par défaut, le schéma de la page s’il est omis), l’hôte, le port et le chemin d’accès ou simplement une barre oblique (/) suivie du chemin d’accès.

  Exemples : https://example.com/a/b/c or /a/b/c

• Emplacements relatifs qui contiennent uniquement un chemin d’accès et ne commencent pas par une barre oblique (/). Celles-ci sont résolues par rapport à l’URL du document actuel ou à la valeur de la balise <base>, le cas échéant.

  Exemple : a/b/c

La présence d’une barre oblique de fin (/) dans un chemin d’accès de base d’une application configuré est importante pour calculer le chemin de base des URL de l’application. Par exemple, https://example.com/a a un chemin d’accès de base de https://example.com/, tandis qu’avec https://example.com/a/ une barre oblique de fin a un chemin d’accès de base de https://example.com/a.

Pour les sources de liens qui se rapportent à Blazor dans les applications ASP.NET Core :

• Les URL des composants Razor (.razor) sont généralement relatives.
• Les URL dans les scripts, telles que les scripts Blazor (blazor.*.js) sont relatifs au document.

Si vous affichez une application Blazor à partir de différents documents (par exemple, /Admin/B/C/ et /Admin/D/E/), vous devez prendre en compte le chemin d’accès de base de l’application, sinon le chemin d’accès de base sera différent lors du rendu de l’application dans chaque document et les ressources seront extraites des URL incorrectes.

Il existe deux approches pour résoudre correctement le problème des liens relatifs :

• Mappez dynamiquement les ressources en utilisant le document sur lequel elles ont été rendues en tant que racine.
• Définissez un chemin d’accès de base cohérent pour le document et mappez les ressources sous ce chemin d’accès de base.

La première option est plus compliquée et n’est pas l’approche la plus classique, car elle rend la navigation différente pour chaque document. Prenons l’exemple suivant pour le rendu d’une page /Something/Else :

• Rendue sous /Admin/B/C/, la page est rendue avec un chemin d’accès /Admin/B/C/Something/Else.
• Rendu sous /Admin/D/E/, la page est rendue au même chemin d’accès de /Admin/B/C/Something/Else.

Dans la première approche, le routage propose IDynamicEndpointMetadata et MatcherPolicy, qui, combinés, peuvent être la base de l’implémentation d’une solution complètement dynamique qui détermine au moment de l’exécution la façon dont les requêtes sont routées.

Pour la deuxième option, qui est l’approche habituelle adoptée, l’application définit le chemin d’accès de base dans le document et mappe les points de terminaison du serveur aux chemins d’accès sous la base. Les conseils suivants adoptent cette approche.

Blazor côté serveur

Mappez le hub SignalR d’une application Blazor côté serveur en transmettant le chemin d’accès MapBlazorHub au fichier Program :

app.MapBlazorHub("base/path");

L’avantage de l’utilisation de MapBlazorHub est que vous pouvez mapper des modèles, tels que "{tenant}" et pas seulement des chemins concrets.

Vous pouvez également mapper le hub SignalR lorsque l’application se trouve dans un dossier virtuel avec un pipeline de middlewares ramifiés. Dans l’exemple suivant, les requêtes vers /base/path/ sont traitées par le hub Blazor de SignalR :

app.Map("/base/path/", subapp => {
    subapp.UsePathBase("/base/path/");
    subapp.UseRouting();
    subapp.UseEndpoints(endpoints => endpoints.MapBlazorHub());
});

Configurez la balise <base>, conformément aux instructions de la section Configurer le chemin d’accès de base de l’application.

Autonome Blazor WebAssembly

Dans une application Blazor WebAssembly autonome, seule la balise <base> est configurée, conformément aux instructions de la section Configurer le chemin d’accès de base de l’application.

Configurer le chemin d’accès de base de l’application

Pour fournir la configuration du chemin de base de l’applicationBlazor, définissez le chemin de base de l’application https://www.contoso.com/CoolApp/, également appelé chemin racine relatif.<base>

En configurant le chemin d’accès de base de l’application, un composant qui ne figure pas dans le répertoire racine peut construire des URL relatives au chemin racine de l’application. Des composants situés à différents niveaux de la structure de répertoires peuvent générer des liens vers d’autres ressources à des emplacements quelconques dans l’application. Le chemin de base de l’application sert également à intercepter les liens hypertextes sélectionnés où la cible href du lien figure dans l’espace d’URI du chemin de base de l’application. Le composant Router gère la navigation interne.

Placez la balise <base> dans le marquage <head> (emplacementdu contenu <head>) avant les éléments ayant des attributs dont les valeurs sont des URL, telles que les attributs href des éléments <link>.

Dans de nombreux scénarios d’hébergement, le chemin URL relatif vers l’application est la racine de l’application. Dans ces cas par défaut, le chemin de base de l’URL relative de l’application est / configuré comme <base href="/" /> dans le contenu <head>.

Remarque

Dans certains scénarios d’hébergement, tels que GitHub Pages et les sous-applications IIS, le chemin d’accès de base de l’application doit être défini sur le chemin URL relatif du serveur de l’application.

• Dans une application Blazor côté serveur, utilisez l’une des approches suivantes :

  • Option 1 : Utilisez la balise <base> pour définir le chemin d’accès de base de l’application (emplacement du <head> contenu) :

    <base href="/CoolApp/">
    

    La barre oblique de fin est requise.

  • Option 2 : Appelez UsePathBasepremier dans le pipeline de traitement des requêtes de l’application (Program.cs) immédiatement après que le WebApplicationBuilder est généré (builder.Build()) pour configurer le chemin d’accès de base pour tout intergiciel suivant qui interagit avec le chemin d’accès de requête :

    app.UsePathBase("/CoolApp");
    

    L’appel de UsePathBase est recommandé quand vous souhaitez également exécuter l’application Blazor Server localement. Par exemple, fournissez l’URL de lancement dans Properties/launchSettings.json :

    "launchUrl": "https://localhost:{PORT}/CoolApp",
    

    L’espace réservé {PORT} dans l’exemple précédent est le port qui correspond au port sécurisé dans le chemin de configuration applicationUrl. L’exemple suivant montre le profil de lancement complet d’une application sur le port 7279 :

    "BlazorSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7279;http://localhost:5279",
      "launchUrl": "https://localhost:7279/CoolApp",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
    }
    

    Pour plus d’informations sur le fichier launchSettings.json, consultez Utiliser plusieurs environnements dans ASP.NET Core. Pour plus d’informations sur les chemins d’accès et l’hébergement de base de l’applicationBlazor, consultez <base href="/" /> ou l’alternative de balise de base pour l’intégration MVC Blazor (dotnet/aspnetcore #43191).

• Blazor WebAssembly (wwwroot/index.html) autonome :

  <base href="/CoolApp/">
  

  La barre oblique de fin est requise.

Remarque

Lors de l’utilisation WebApplication (consultez Migrer de ASP.NET Core dans .NET 5 vers .NET 6), app.UseRouting doit être appelée après UsePathBase afin que l’intergiciel de routage puisse observer le chemin modifié avant de correspondre aux itinéraires. Dans le cas contraire, les routes sont mises en correspondance avant que le chemin ne soit réécrit par UsePathBase comme décrit dans les articles Ordre des intergiciels et Routage.

Ne préfixez pas les liens dans l’ensemble de l’application avec une barre oblique. Évitez d’utiliser un séparateur de segment de chemin ou utilisez la notation de chemin relatif point-barre oblique (./) :

• ❌ Incorrect : <a href="/account">
• ✔️ Correct : <a href="account">
• ✔️ Correct : <a href="./account">

Dans les demandes d’API web Blazor WebAssembly avec le service HttpClient, confirmez que les assistances JSON (HttpClientJsonExtensions) ne préfixent pas les URL avec une barre oblique (/) :

• ❌ Incorrect : var rsp = await client.GetFromJsonAsync("/api/Account");
• ✔️ Correct : var rsp = await client.GetFromJsonAsync("api/Account");

Ne préfixez pas les liens relatifs du gestionnaire de navigation avec une barre oblique. Évitez d’utiliser un séparateur de segment de chemin d’accès ou utilisez la notation de chemin d’accès relatif point-slash (./) (Navigation est un NavigationManagerinjecté) :

• ❌ Incorrect : Navigation.NavigateTo("/other");
• ✔️ Correct : Navigation.NavigateTo("other");
• ✔️ Correct : Navigation.NavigateTo("./other");

Dans les configurations standard d’hébergement Azure/IIS, une configuration supplémentaire n’est généralement pas nécessaire. Dans certains scénarios d’hébergement non IIS et d’hébergement de proxy inverse, une configuration d’intergiciel de fichiers statiques supplémentaire peut être nécessaire :

• Pour délivrer correctement les fichiers statiques (par exemple, app.UseStaticFiles("/CoolApp");).
• Pour délivrer le script Blazor (_framework/blazor.*.js). Pour plus d’informations, consultez Fichiers statiques ASP.NET CoreBlazor.

Pour une application Blazor WebAssembly avec un chemin URL relatif non racine (par exemple, <base href="/CoolApp/">), l’application ne parvient pas à trouver ses ressources quand elle est exécutée localement. Pour surmonter ce problème pendant le développement local et les tests, vous pouvez fournir un argument de base de chemin qui correspond à la valeur href de la balise <base> au moment de l’exécution. N’incluez pas de barre oblique de fin. Pour passer l’argument de base de chemin quand vous exécutez l’application localement, exécutez la commande dotnet watch (ou dotnet run) à partir du répertoire de l’application avec l’option --pathbase :

dotnet watch --pathbase=/{RELATIVE URL PATH (no trailing slash)}

Pour une application Blazor WebAssembly avec le chemin URL relatif /CoolApp/ (<base href="/CoolApp/">), la commande est :

dotnet watch --pathbase=/CoolApp

Si vous préférez configurer le profil de lancement de l’application pour spécifier pathbase automatiquement au lieu de le faire manuellement avec dotnet watch (ou dotnet run), définissez la propriété commandLineArgs dans Properties/launchSettings.json. Ce qui suit configure également l’URL de lancement (launchUrl) :

"commandLineArgs": "--pathbase=/{RELATIVE URL PATH (no trailing slash)}",
"launchUrl": "{RELATIVE URL PATH (no trailing slash)}",

Utilisation de CoolApp comme exemple :

"commandLineArgs": "--pathbase=/CoolApp",
"launchUrl": "CoolApp",

En utilisant dotnet watch (ou dotnet run) avec l’option --pathbase ou une configuration de profil de lancement qui définit le chemin de base, l’application Blazor WebAssembly répond localement à l’adresse http://localhost:port/CoolApp.

Pour plus d’informations sur le fichier launchSettings.json, consultez Utiliser plusieurs environnements dans ASP.NET Core. Pour plus d’informations sur les chemins d’accès et l’hébergement de base de l’applicationBlazor, consultez <base href="/" /> ou l’alternative de balise de base pour l’intégration MVC Blazor (dotnet/aspnetcore #43191).

Obtenir le chemin de base de l’application à partir de la configuration

L’aide suivante explique comment obtenir le chemin pour la balise <base> à partir d’un fichier de paramètres d’application pour différents environnements.

Ajoutez le fichier de paramètres d’application à l’application. L’exemple suivant concerne l’environnement Staging (appsettings.Staging.json) :

{
  "AppBasePath": "staging/"
}

Dans une application Blazor côté serveur, chargez le chemin de base à partir de la configuration dans le contenu <head> :

@inject IConfiguration Config

...

<head>
    ...
    <base href="/@(Config.GetValue<string>("AppBasePath"))" />
    ...
</head>

Une application côté serveur peut également obtenir la valeur à partir de la configuration pour UsePathBase. Placez le code suivant en premier dans le pipeline de traitement des requêtes de l’application (Program.cs), immédiatement après la génération de WebApplicationBuilder (builder.Build()). L’exemple suivant utilise la clé de configuration AppBasePath :

app.UsePathBase($"/{app.Configuration.GetValue<string>("AppBasePath")}");

Dans une application Blazor WebAssembly côté client :

• Supprimez la balise <base> de wwwroot/index.html :

  - <base href="..." />
  

• Indiquez le chemin de base de l’application via un composant HeadContent dans le composant App (App.razor) :

  @inject IConfiguration Config
  
  ...
  
  <HeadContent>
      <base href="/@(Config.GetValue<string>("AppBasePath"))" />
  </HeadContent>
  

S’il n’y a aucune valeur de configuration à charger, par exemple dans des environnements non intermédiaires, le href précédent est résolu en chemin racine /.

Les exemples de cette section se concentrent sur l’utilisation des paramètres d’application pour fournir le chemin de base de l’application, mais l’approche consistant à lire le chemin à partir de IConfiguration est valable pour tout fournisseur de configuration. Pour plus d’informations, consultez les ressources suivantes :

• Configuration ASP.NET CoreBlazor
• Configuration dans ASP.NET Core