Environnements Blazor ASP.NET Core

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

Lors de l’exécution locale d’une application, l’environnement est défini par défaut sur 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 s’attend exactement à ce nom lors de la configuration de l’application et des outils pour les exécutions de développement local d’une application.

• Pour les environnements de test, de préproduction et de production, publiez et déployez toujours l’application. Vous pouvez utiliser n'importe quel schéma de dénomination de l'environnement pour les applications publiées, mais utilisez toujours des noms de fichiers de paramètres d'application avec une casse du segment d'environnement qui correspond exactement au nom de l'environnement. Pour la mise en scène, 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 ou Blazor Server: Utilisez l’une des approches décrites dans Utiliser plusieurs environnements dans ASP.NET Core pour les applications générales ASP.NET Core.
• Toute Blazor application :
  • Blazor configuration de démarrage
  • Azure App Service
• Blazor WebAssembly: Blazor-Environment en-tête

Sur le client pour un 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 lors de la création de WebAssemblyHost dans le fichier côté Program client (WebAssemblyHostBuilder.CreateDefault).

Pour une application autonome Blazor WebAssembly exécutée localement, le serveur de développement ajoute l’en-tête Blazor-Environment avec le nom de l’environnement obtenu à partir de l’environnement d’hébergement. L’environnement d’hébergement définit l’environnement à partir de la ASPNETCORE_ENVIRONMENT variable d’environnement établie par le fichier du Properties/launchSettings.json projet. La valeur par défaut de la variable d’environnement dans un projet créé à partir du modèle de Blazor WebAssembly projet est Development. Pour plus d’informations, consultez la section Définir l’environnement côté client via la section d’en-tête .

Pour que l’application s’exécute localement dans le développement, l’application est par défaut dans l’environnement Development . En publiant l'application, l'environnement par défaut est Production.

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

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, la préversion sur le serveur fonctionne 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 la définition de l’environnement pour un 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 environment propriété remplace l’environnement défini par Blazor-Environment l’en-tête.

L'approche précédente définit l'environnement du client sans modifier la valeur de l'en-tête Blazor-Environment, ni le journal de la console du projet de serveur concernant l'environnement de démarrage pour un Blazor Web App ayant adopté le rendu global de WebAssembly interactif.

Pour consigner l’environnement dans la console, que ce soit dans une application autonome Blazor WebAssembly ou dans le projet .Client d’un Blazor Web App, placez le code C# suivant dans le fichier Program après que WebAssemblyHost ait été créé 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éfinir l’environnement côté client via l’en-tête

Blazor WebAssembly les applications peuvent définir l’environnement avec l’en-tête Blazor-Environment . Plus précisément, l'en-tête de réponse doit être défini sur le fichier _framework/blazor.boot.json, mais il n'y a aucun inconvénient à définir l'en-tête sur les réponses du serveur de fichiers pour d'autres demandes de fichiers Blazor ou sur l'ensemble du déploiement Blazor.

Bien que le framework Blazor émette le nom de l'en-tête en majuscules et minuscules (Blazor-Environment), vous pouvez utiliser des majuscules et minuscules (blazor-environment, BLAZOR-ENVIRONMENT).

Pour les exécutions de développement local avec Blazorle serveur de développement intégré, vous pouvez contrôler la valeur de l’en-tête Blazor-Environment en définissant la valeur de la ASPNETCORE_ENVIRONMENT variable d’environnement dans le fichier du Properties/launchSettings.json projet. Lors de l’exécution localement avec le serveur de développement, l’ordre de priorité pour déterminer l’environnement de l’application est la configuration (environment clé), l’en-tête de réponse (blazor.boot.json fichier), puis la variable d’environnement (launchSettings.json). Vous ne pouvez pas utiliser l’approche ASPNETCORE_ENVIRONMENT de variable d’environnement (launchSettings.json) pour une application déployée Blazor WebAssembly . La technique fonctionne uniquement avec le serveur de développement sur les exécutions locales de l’application.

IIS

Dans l’exemple suivant pour IIS, l’en-tête personnalisé (Blazor-Environment) est ajouté au fichier publié web.config . Le fichier web.config est situé dans le dossier bin/Release/{TARGET FRAMEWORK}/publish, où l'espace réservé {TARGET FRAMEWORK} correspond au 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 personnalisé web.config pour IIS qui n’est pas remplacé lorsque l’application est publiée dans le répertoire publish, consultez Héberger et déployer ASP.NET Core Blazor WebAssembly avec IIS.

Nginx

Pour les serveurs Nginx, utilisez la add_header directive à partir de :ngx_http_headers_module

http {
    server {
        ...
        location / {
            ...
            add_header Blazor-Environment "Staging";
        }
    }
}

Pour plus d’informations, consultez les ressources suivantes :

• Documentation Nginx
• Héberger et déployer ASP.NET Core Blazor WebAssembly avec Nginx

Apache

Pour les serveurs Apache, utilisez la Header directive du mod_headers module :

<VirtualHost *:80>
    ...
    Header set Blazor-Environment "Staging"
    ...
</VirtualHost>

Pour plus d’informations, consultez les ressources suivantes :

• Documentation Apache (recherchez la dernière version pour «mod_headers »)
• Héberger et déployer ASP.NET Core Blazor WebAssembly avec Apache

Définir l’environnement pour Azure App Service

Pour une application autonomeBlazor WebAssembly, vous pouvez définir l’environnement manuellement via la configuration de démarrage ou l’en-têteBlazor-Environment.

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

1. Confirmez que la casse des segments d'environnement dans les noms des fichiers d'application correspond exactement à la casse de leur 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 du fichier est appsettings.staging.json (en minuscules «s »), 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 dans l’emplacement de déploiement Staging.

3. Dans le portail Azure pour l’emplacement de déploiement de l’environnement, définissez l’environnement avec le ASPNETCORE_ENVIRONMENT paramètre d’application. Pour une application nommée BlazorAzureAppSample, le slot de service d'application intermédiaire est nommé BlazorAzureAppSample/Staging. Pour la configuration de l’emplacement Staging , créez un paramètre d’application pour ASPNETCORE_ENVIRONMENT lequel la valeur est Staging. L'option d'emplacement de déploiement est activée pour ce paramètre.

Quand elle est demandée dans un navigateur, l’application BlazorAzureAppSample/Staging se charge dans l’environnement à l’adresse Staginghttps://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 appsettings.Staging.json fichier sont chargés.

Lire 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 un Blazor Web App

En supposant que la préversion n’est pas désactivée pour un composant ou l’application, un composant du .Client projet est pré-enderé sur le serveur. Étant donné que le serveur n’a pas de service inscrit IWebAssemblyHostEnvironment , il n’est pas possible d’injecter le service et d’utiliser les méthodes et propriétés de l’extension de l’environnement hôte de l’implémentation de service pendant le prérendering 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 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 du Program projet de serveur, inscrivez le service :

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

À ce stade, le service IWebAssemblyHostEnvironment peut être injecté dans un composant interactif WebAssembly ou Auto et utilisé comme illustré 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 un Blazor Web App, il est préférable de faire correspondre les environnements serveur et .Client projet. Considérez le scénario suivant dans une application de test :

• Mettez en œuvre 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 section configuration de démarrage .
• Ne modifiez pas le fichier côté Properties/launchSettings.json serveur. Laissez la environmentVariables section avec la variable d’environnement ASPNETCORE_ENVIRONMENT définie sur Development.

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

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

Environment:Development

Lorsque le composant est rendu une ou deux secondes plus tard, après le téléchargement du bundle Blazor et l'activation du runtime .NET WebAssembly, 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 vous recommandons de définir l’environnement serveur pour 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 figure plus loin dans la documentation Blazor.

Lire l'environnement côté client au démarrage

Au démarrage, le WebAssemblyHostBuilder expose la propriété IWebAssemblyHostEnvironment via le HostEnvironment, ce qui permet d'implémenter 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 IWebAssemblyHostEnvironment.BaseAddress propriété peut être utilisée au démarrage lorsque le NavigationManager service 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)