Environnements Blazor ASP.NET Core

Cet article explique comment configurer et lire l’environnement dans une application Blazor.

Lors de l’exécution d’une application localement, l’environnement par défaut est Development. Lorsque l’application est publiée, l’environnement est défini par défaut sur Production.

Nous vous recommandons les conventions suivantes :

• Utilisez toujours le nom d’environnement « Development » pour le développement local. Cela est dû au fait que l’infrastructure ASP.NET Core attend exactement ce nom lors de la configuration de l’application et de l’outil pour les exécutions de développement local d’une application.

• Pour les environnements de test, de mise en lots et de production, publiez et déployez toujours l’application. Vous pouvez utiliser n’importe quel schéma d’affectation de noms d’environnement que vous souhaitez pour les applications publiées, mais utilisez toujours les noms de fichiers de paramétrage d’application avec la casse du segment d’environnement qui correspond exactement au nom de l’environnement. Pour la mise en lots, utilisez « Staging » (majuscule « S ») comme nom d’environnement et nommez le fichier de paramètres de l’application à mettre en correspondance (appsettings.Staging.json). Pour la production, utilisez « Production » (majuscule « P ») comme nom d’environnement et nommez le fichier de paramètres de l’application à mettre en correspondance (appsettings.Production.json).

Définir l’environnement

L’environnement est défini à l’aide de l’une des approches suivantes :

• Blazor Web App : utilisez l’une des approches décrites dans Utiliser plusieurs environnements dans ASP.NET Core pour les applications générales ASP.NET Core.
• Blazor Web App ou Blazor WebAssembly autonome : configuration de démarrage de Blazor
• Blazor WebAssembly autonome : en-tête blazor-environment
• Blazor Web App ou Blazor WebAssembly autonome : Azure App Service

Sur le client d’une Blazor Web App, l’environnement est déterminé à partir du serveur via un intergiciel qui communique l’environnement au navigateur via un en-tête nommé blazor-environment. L’en-tête définit l’environnement lorsque WebAssemblyHost est créé dans le fichier Program côté client (WebAssemblyHostBuilder.CreateDefault).

Pour l’exécution locale d’une application autonome Blazor WebAssembly, le serveur de développement ajoute l’en-tête blazor-environment.

Pour l’exécution locale des applications en cours de développement, l’application est par défaut dans l’environnement Development. La publication de l’application définit l’environnement par défaut sur Production.

Définissez l’environnement côté client via la configuration de démarrage Blazor

L’exemple suivant démarre Blazor dans l’environnement Staging si le nom d’hôte inclut localhost. Sinon, l’environnement est défini sur sa valeur par défaut.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      webAssembly: {
        environment: "Staging"
      }
    });
  } else {
    Blazor.start();
  }
</script>

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.

Remarque

Pour les Blazor Web App qui définissent la propriété webAssembly>environment dans la configuration Blazor.start, il est judicieux de faire correspondre l’environnement côté serveur à l’environnement défini sur la propriété environment. Dans le cas contraire, le pré-rendu sur le serveur fonctionnera dans un environnement différent de celui du rendu sur le client, ce qui entraîne des effets arbitraires. Pour obtenir des conseils généraux sur le paramétrage de l’environnement d’une Blazor Web App, consultez Utiliser plusieurs environnements dans ASP.NET Core.

Blazor WebAssembly autonome :

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      environment: "Staging"
    });
  } else {
    Blazor.start();
  }
</script>

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.

L’utilisation de la propriété environment remplace l’environnement défini par l’en-tête blazor-environment.

L’approche précédente définit l’environnement du client sans modifier la valeur de l’en-tête blazor-environment, ni modifier la journalisation de la console du projet serveur de l’environnement de démarrage pour une Blazor Web App qui a adopté le rendu global WebAssembly intéractif.

Pour journaliser l’environnement dans la console d’un projet autonome Blazor WebAssembly ou d’un projet .Client Blazor Web App, placez le code C# suivant dans le fichier Program après la création de WebAssemblyHost avec WebAssemblyHostBuilder.CreateDefault et avant la ligne qui génère et exécute le projet (await builder.Build().RunAsync();) :

Console.WriteLine(
    $"Client Hosting Environment: {builder.HostEnvironment.Environment}");

Pour plus d’informations sur le démarrage de Blazor, consultez Démarrage d’ASP.NET Core Blazor.

Définissez l’environnement côté client via l’en-tête

Les applications Blazor WebAssembly peuvent définir l’environnement avec l’en-tête blazor-environment.

Dans l’exemple suivant pour IIS, l’en-tête personnalisé (blazor-environment) est ajouté au fichier web.config publié. Le fichier web.config se trouve dans le dossier bin/Release/{TARGET FRAMEWORK}/publish, où l’espace réservé {TARGET FRAMEWORK} est le framework cible :

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>

    ...

    <httpProtocol>
      <customHeaders>
        <add name="blazor-environment" value="Staging" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Remarque

Pour utiliser un fichier web.config personnalisé pour IIS qui n’est pas remplacé lorsque l’application est publiée dans le dossier publish, consultez Héberger et déployer ASP.NET Core Blazor WebAssembly.

Bien que l’infrastructure Blazor émette le nom de l’en-tête en lettres minuscules (blazor-environment), vous pouvez utiliser la casse de votre choix. Par exemple, un nom d’en-tête qui met en majuscule chaque mot (Blazor-Environment) est pris en charge.

Définir l’environnement pour Azure App Service

Pour une application autonome Blazor WebAssembly, vous pouvez définir l’environnement manuellement via démarrer la configuration ou via l’en-tête blazor-environment.

Pour une application côté serveur, définissez l’environnement via un paramètre d’application ASPNETCORE_ENVIRONMENT dans Azure :

1. Vérifiez que la casse des segments d’environnement dans les noms de fichier des paramètres d’application correspond exactement à leur casse de nom d’environnement. Par exemple, le nom du fichier de paramètres d’application correspondant pour l’environnement Staging est appsettings.Staging.json. Si le nom de fichier est appsettings.staging.json (« s » minuscule), le fichier n’est pas localisé et les paramètres du fichier ne sont pas utilisés dans l’environnement Staging.

2. Pour le déploiement de Visual Studio, vérifiez que l’application est déployée sur l’emplacement de déploiement approprié. Pour une application nommée BlazorAzureAppSample, l’application est déployée sur l’emplacement de déploiement Staging.

3. Dans le Portail Azure de l’emplacement de déploiement de l’environnement, définissez l’environnement avec le paramètre d’application ASPNETCORE_ENVIRONMENT. Pour une application nommée BlazorAzureAppSample, l’emplacement App Service intermédiaire est nommé BlazorAzureAppSample/Staging. Pour la configuration de l’emplacement Staging, créez un paramètre d’application pour ASPNETCORE_ENVIRONMENT avec une valeur de Staging. Le paramètre d’emplacement de déploiement est activé pour le paramètre.

Lorsqu’elle est demandée dans un navigateur, l’application BlazorAzureAppSample/Staging se charge dans l’environnement Staging à l’adresse https://blazorazureappsample-staging.azurewebsites.net.

Lorsque l’application est chargée dans le navigateur, la collection d’en-têtes de réponse pour blazor.boot.json indique que la valeur de l’en-tête blazor-environment est Staging.

Les paramètres de l’application à partir du fichier appsettings.{ENVIRONMENT}.json sont chargés par l’application, où l’espace réservé {ENVIRONMENT} est l’environnement de l’application. Dans l’exemple précédent, les paramètres du fichier appsettings.Staging.json sont chargés.

Lisez l’environnement dans une application Blazor WebAssembly

Obtenez l’environnement de l’application dans un composant en injectant IWebAssemblyHostEnvironment et en lisant la propriété Environment.

ReadEnvironment.razor:

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env

<h1>Environment example</h1>

<p>Environment: @Env.Environment</p>

Lire l’environnement côté client dans une Blazor Web App

En supposant que le pré-rendu n’est pas désactivé pour un composant ou l’application, un composant du projet .Client est pré-rendu sur le serveur. Étant donné que le serveur n’a pas de service IWebAssemblyHostEnvironment inscrit, il n’est pas possible d’injecter le service et d’utiliser les méthodes et propriétés d’extension de l’environnement hôte de l’implémentation du service pendant le pré-rendu du serveur. L’injection du service dans un composant Interactif WebAssembly ou Interactive Auto entraîne l’erreur d’exécution suivante :

There is no registered service of type 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

Pour résoudre ce problème, créez une implémentation de service personnalisée pour IWebAssemblyHostEnvironment sur le serveur. Ajoutez la classe suivante au projet serveur.

ServerHostEnvironment.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Microsoft.AspNetCore.Components;

public class ServerHostEnvironment(IWebHostEnvironment env, NavigationManager nav) : 
    IWebAssemblyHostEnvironment
{
    public string Environment => env.EnvironmentName;
    public string BaseAddress => nav.BaseUri;
}

Dans le fichier Program du projet serveur, inscrivez le service :

builder.Services.TryAddScoped<IWebAssemblyHostEnvironment, ServerHostEnvironment>();

À ce stade, le service IWebAssemblyHostEnvironment peut être injecté dans un composant WebAssembly interactif ou Auto interactif et utilisé comme indiqué dans la section Lire l’environnement dans une application Blazor WebAssembly.

L’exemple précédent peut démontrer qu’il est possible d’avoir un environnement serveur différent de celui de l’environnement client, ce qui n’est pas recommandé et peut entraîner des résultats arbitraires. Lorsque vous définissez l’environnement dans une Blazor Web App, il est préférable de faire correspondre les environnements serveur et projet .Client. Considérez le scénario suivant dans une application de test :

• Implémentez la propriété d’environnement côté client (webassembly) avec l’environnement Staging via Blazor.start. Pour obtenir un exemple, consultez la section Définir l’environnement côté client via la configuration de démarrage.
• Ne modifiez pas le fichier Properties/launchSettings.json côté serveur. Laissez la section environmentVariables avec la variable d’environnement ASPNETCORE_ENVIRONMENT définie sur Development.

Vous pouvez voir la valeur de la modification de la propriété IWebAssemblyHostEnvironment.Environment dans l’interface utilisateur.

Lorsque le pré-rendu se produit sur le serveur, le composant est rendu dans l’environnement Development :

Environment: Development

Lorsque le composant est re-rendu une ou deux secondes plus tard, une fois que le pack Blazor est téléchargé et que le runtime .NET WebAssembly est activé, les valeurs changent pour refléter le fait que le client opère dans l’environnement Staging sur le client :

Environment: Staging

L’exemple précédent montre pourquoi nous recommandons de définir l’environnement serveur de manière à ce qu’il corresponde à l’environnement client pour les déploiements de développement, de test et de production.

Pour plus d’informations, consultez la section Échec de la résolution des services côté client pendant le pré-rendu de l’article Modes de rendu, qui apparaît plus loin dans la documentation Blazor.

Lisez l’environnement côté client pendant le démarrage

Au démarrage, WebAssemblyHostBuilder expose IWebAssemblyHostEnvironment via la propriété HostEnvironment, qui permet une logique spécifique à l’environnement dans le code du générateur d’hôtes.

Dans le fichier Program :

if (builder.HostEnvironment.Environment == "Custom")
{
    ...
};

Les méthodes d’extension pratiques suivantes fournies via WebAssemblyHostEnvironmentExtensions permettent de vérifier l’environnement actuel pour Development, Production, Staging et les noms d’environnement personnalisés :

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

Dans le fichier Program :

if (builder.HostEnvironment.IsStaging())
{
    ...
};

if (builder.HostEnvironment.IsEnvironment("Custom"))
{
    ...
};

La propriété IWebAssemblyHostEnvironment.BaseAddress peut être utilisée au démarrage lorsque le service NavigationManager n’est pas disponible.

Ressources supplémentaires

• Démarrage ASP.NET Core Blazor
• Utiliser plusieurs environnements dans ASP.NET Core
• Dépôt GitHub d’exemples Blazor (dotnet/blazor-samples) (Comment télécharger)