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 ASP.NET environnements d’exécution Core pour les applications générales ASP.NET Core.
• Toute Blazor application : Blazor démarrer la configuration
• Autonome Blazor WebAssembly : propriété <WasmApplicationEnvironmentName>

Sur le client pour un Blazor Web App, l’environnement est déterminé à partir du serveur via un commentaire HTML avec lequel les développeurs n’interagissent pas :

<!--Blazor-WebAssembly:{"environmentName":"Development", ...}-->

Pour une application autonome Blazor WebAssembly , définissez l’environnement avec la <WasmApplicationEnvironmentName> propriété MSBuild dans le fichier projet de l’application (.csproj). L’exemple suivant définit l’environnement Staging :

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

Les environnements par défaut sont Development destinés à la génération et Production à la publication.

Il existe plusieurs approches pour définir l’environnement dans une application autonome Blazor WebAssembly pendant les opérations de génération/publication et une approche pour une application en commençant ou en cours d’exécution sur le client :

• Définissez la valeur de la propriété quand dotnet build ou dotnet publish est exécutée. L’exemple suivant montre comment définir l’environnement Staging lorsqu’une application est publiée :

  dotnet publish -p:WasmApplicationEnvironmentName=Staging
  

• Définissez la propriété pendant la génération ou la publication en fonction de la configuration de l’application dans Visual Studio. Les groupes de propriétés suivants peuvent être utilisés dans le fichier projet de l’application ou dans n’importe quel fichier de configuration de publication (.pubxml). Ajoutez des groupes de propriétés supplémentaires pour d’autres configurations de build en cours d’utilisation.

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• L’environnement peut être défini en fonction de l’utilisation d’un profil de publication. Dans l’exemple suivant, la première condition définit l’environnement Development lorsqu’aucun profil de publication n’est utilisé (s’applique aux opérations de génération et de publication sans profil), tandis que la deuxième condition couvre la définition de l’environnement Production quand un profil de publication est utilisé :

  <PropertyGroup Condition="'$(PublishProfile)' == ''">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(PublishProfile)' != ''">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• Créez un point de terminaison d’API web côté serveur personnalisé. L’application autonome Blazor WebAssembly demande son environnement à partir de l’API web au démarrage de l’application ou à la demande pendant son exécution. La valeur doit être passée à WebAssemblyStartOptions ou avec withApplicationEnvironment.

  Remarque

  Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

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 Appenvironnement, consultez ASP.NET environnements d’exécution 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.

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.

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. Pour plus d’informations et un exemple d’implémentation, consultez l’implémentation de service personnalisé dans la section serveur de l’article Prerendering , qui apparaît plus loin dans la Blazor documentation.

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
• environnements d’exécution ASP.NET Core
• Dépôt GitHub d’exemples Blazor (dotnet/blazor-samples) (Comment télécharger)