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

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.

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

<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>

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>

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;
}

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

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)