Héberger et déployer ASP.NET Core Blazor

Cet article explique comment héberger et déployer des applications Blazor.

Publier l’application

Les applications sont publiées pour le déploiement dans la configuration Release.

Visual Studio

1. Sélectionnez la commande Publier {APPLICATION} dans le menu Générer, où l’espace réservé {APPLICATION} est le nom de l’application.
2. Sélectionnez l’onglet Cible de publication. Pour publier localement, sélectionnez Dossier.
3. Acceptez l’emplacement par défaut dans le champ Choisir un dossier ou spécifiez un autre emplacement. Sélectionnez le bouton Publish.

CLI .NET Core

Utilisez la commande dotnet publish pour publier l’application avec une configuration Release :

dotnet publish -c Release

La publication de l’application déclenche une restauration des dépendances du projet et crée le projet avant de créer les ressources pour le déploiement. Dans le cadre du processus de génération, les assemblys et méthodes inutilisés sont supprimés pour réduire la durée du chargement et la taille du téléchargement de l’application.

Emplacements de publication :

• Application web Blazor : par défaut, l’application est publiée dans le dossier /bin/Release/{TARGET FRAMEWORK}/publish. Déployez le contenu du dossier publish sur l’hôte.
• Blazor WebAssembly : par défaut, l’application est publiée dans le dossier bin\Release\net8.0\browser-wasm\publish\. Pour déployer l’application en tant que site statique, copiez le contenu du dossier wwwroot sur l’hôte de site statique.

Dans les chemins d’accès précédents, {TARGET FRAMEWORK} désigne la version cible de .Net Framework (par exemple, net8.0).

IIS

Pour héberger une application Blazor dans IIS, consultez les ressources suivantes :

• Hébergement IIS
  • Publier une application ASP.NET Core sur IIS
  • Héberger ASP.NET Core sur Windows avec IIS
• Héberger et déployer des applications Blazor ASP.NET Core côté serveur : applications serveur s’exécutant sur IIS, y compris IIS avec des machines virtuelles Azure exécutant le système d’exploitation Windows et Azure App Service.
• Héberger et déployer ASP.NET Core Blazor WebAssembly : Inclut des conseils supplémentaires pour Blazor WebAssembly applications hébergées sur IIS, notamment l’hébergement de sites statiques, les fichiers personnalisésweb.config, la réécriture d’URL, les sous-applications, la compression et l’hébergement de fichiers statiques dans le stockage Azure.
• Hébergement de sous-applications IIS
  • Suivez les conseils de la section Chemin d’accès de base de l’application pour l’application Blazor avant de publier l’application. Les exemples utilisent /CoolApp comme chemin de base de l’application et montrent comment obtenir le chemin de base à partir des paramètres d’application ou d’autres fournisseurs de configuration.
  • Suivez les instructions de configuration de sous-application dans la Configuration avancée. Le chemin d’accès du dossier de la sous-application sous le site racine devient le chemin d’accès virtuel de la sous-application. Pour un chemin d’accès de base d’application de /CoolApp, l’application Blazor est placée dans un dossier nommé CoolApp sous le site racine et la sous-application prend un chemin d’accès virtuel de /CoolApp.

Le partage d’un pool d’applications entre des applications ASP.NET Core n’est pas pris en charge, y compris pour les applications Blazor. Utilisez un pool d’applications par application lors de l’hébergement avec IIS et évitez d’utiliser les répertoires virtuels d’IIS pour héberger plusieurs applications.

Chemin de base de l’application

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.

Arrière-plan

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.

Il existe trois 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 SignalR de Blazor :

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.

Blazor WebAssembly autonome

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 Blazorchemin d’accès de base de https://www.contoso.com/CoolApp/, définissez le chemin d’accès de base de l’application, également appelé chemin racine relatif.

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.

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 de WebApplication (consultez Migrer de ASP.NET Core 5.0 vers 6.0), app.UseRouting doit être appelé après UsePathBase afin que l’Intergiciel de routage puisse observer le chemin d’accès modifié avant la mise en correspondance des 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 JSassistances ON (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 run à partir du répertoire de l’application avec l’option --pathbase :

dotnet run --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 run --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 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 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 :

• C ASP.NET Core Blazor
• Configuration dans ASP.NET Core

Configuration Blazor ServerMapFallbackToPage

Cette section s’applique uniquement aux applications Blazor Server. MapFallbackToPage n’est pas pris en charge dans Blazor Web Apps et les applications Blazor WebAssembly.

Dans les scénarios où une application nécessite une zone distincte avec des ressources et des composants Razor personnalisés :

• Créez un dossier dans le dossier Pages de l’application pour y placer les ressources. Par exemple, une section d’administrateur d’une application est créée dans un nouveau dossier nommé Admin (Pages/Admin).

• Créez une page racine (_Host.cshtml) pour la zone. Par exemple, créez un fichier Pages/Admin/_Host.cshtml à partir de la page racine principale de l’application (Pages/_Host.cshtml). Ne fournissez pas de directive @page dans la page _Host d’administration.

• Ajoutez une disposition au dossier de la zone (par exemple, Pages/Admin/_Layout.razor). Dans la disposition de la zone distincte, définissez l’étiquette <base>href pour qu’elle corresponde au dossier de la zone (par exemple, <base href="/Admin/" />). À des fins de démonstration, ajoutez ~/ aux ressources statiques dans la page. Par exemple :

  • ~/css/bootstrap/bootstrap.min.css
  • ~/css/site.css
  • ~/BlazorSample.styles.css (l’espace de noms de l’exemple d’application est BlazorSample)
  • ~/_framework/blazor.server.js (script Blazor)

• Si la zone doit avoir son propre dossier de ressources statiques, ajoutez le dossier et spécifiez son emplacement sur Middleware de fichiers statiques dans Program.cs (par exemple, app.UseStaticFiles("/Admin/wwwroot")).

• Les composants Razor sont ajoutés dans le dossier de la zone. Au minimum, ajoutez un composant Index au dossier de zone avec la directive @page correcte pour cette zone. Par exemple, ajoutez un fichier Pages/Admin/Index.razor en fonction du fichier Pages/Index.razor par défaut de l’application. Indiquez la zone Administration comme modèle de route en haut du fichier (@page "/admin"). Ajoutez des composants supplémentaires si nécessaire. Par exemple, Pages/Admin/Component1.razor avec une directive @page et un modèle de route @page "/admin/component1.

• Dans Program.cs, appelez MapFallbackToPage pour le chemin de demande de la zone immédiatement avant le chemin de la page racine de secours vers la page _Host :

  ...
  app.UseRouting();
  
  app.MapBlazorHub();
  app.MapFallbackToPage("~/Admin/{*clientroutes:nonfile}", "/Admin/_Host");
  app.MapFallbackToPage("/_Host");
  
  app.Run();
  

Déploiement

Pour obtenir des conseils de déploiement, consultez les rubriques suivantes :

• Héberger et déployer ASP.NET Core Blazor WebAssembly
• Héberger et déployer des applications Blazor ASP.NET Core côté serveur