Configuration Blazor de ASP.NET Core

Cet article explique comment configurer des applications Blazor, notamment les paramètres de l’application, l’authentification et la configuration de la journalisation.

Cette aide s’applique à la configuration de projet côté client dans une Blazor Web App ou une application Blazor WebAssembly autonome.

Comportement par défaut dans Blazor Web Apps :

• Pour la configuration côté serveur :
  • Consultez Configuration dans ASP.NET Core pour plus d’informations.
  • Seule la configuration des fichiers de paramètres de l’application dans la racine du projet est chargée.
  • Le reste de cet article s’applique uniquement à la configuration côté client dans le projet .Client.
• Pour la configuration côté client (projet .Client), la configuration est chargée à partir des fichiers de configuration de l’application suivants :
  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json, où l’espace réservé {ENVIRONMENT} est l’environnement d’exécution de l’application.

Dans les applications autonomes Blazor WebAssembly, la configuration est chargée à partir des fichiers de configuration de l’application suivants :

• wwwroot/appsettings.json.
• wwwroot/appsettings.{ENVIRONMENT}.json, où l’espace réservé {ENVIRONMENT} est l’environnement d’exécution de l’application.

Remarque

La configuration de la journalisation placée dans un fichier de paramètres d’application dans wwwroot n’est pas chargée par défaut. Pour plus d’informations, consultez la section Configuration de la journalisation plus loin dans cet article.

Dans certains scénarios, comme avec les services Azure, il est important d’utiliser un segment de nom de fichier d’environnement qui correspond exactement au nom de l’environnement. Par exemple, utilisez le nom de fichier appsettings.Staging.json avec un « S » majuscule pour l’environnement Staging. Pour connaître les conventions recommandées, consultez les remarques d’ouverture des environnements Blazor ASP.NET Core.

D’autres fournisseurs de configuration inscrits par l’application peuvent également fournir une configuration, mais tous les fournisseurs ou fonctionnalités de fournisseur ne conviennent pas :

• Fournisseur de configuration Azure Key Vault : le fournisseur n’est pas pris en charge pour les scénarios d’identity managée et d’ID d’application (ID client) avec une clé secrète client. L’ID d’application avec une clé secrète client n’est pas recommandé pour une application ASP.NET Core, en particulier pour les applications côté client, car la clé secrète client ne peut pas être sécurisée côté client pour accéder au service Azure Key Vault.
• Fournisseur Azure App Configuration : le fournisseur n’est pas approprié pour les applications côté client, car elles ne s’exécutent pas sur un serveur dans Azure.

Pour plus d’informations sur les fournisseurs de configuration, consultez Configuration dans ASP.NET Core.

Avertissement

Les fichiers de configuration et de paramètres dans la racine web (dossier wwwroot) sont visibles par les utilisateurs sur le client, et les utilisateurs peuvent falsifier les données. Ne stockez pas de secrets d’application, d’informations d’identification ou autres données sensibles dans un fichier racine web.

Configuration des paramètres de l’application

La configuration dans les fichiers de paramètres d’application est chargée par défaut. Dans l’exemple suivant, une valeur de configuration de l’interface utilisateur est stockée dans un fichier de paramètres d’application et chargée automatiquement par l’infrastructure Blazor. La valeur est lue par un composant.

wwwroot/appsettings.json:

{
    "h1FontSize": "50px"
}

Injectez une instance IConfiguration dans un composant pour accéder aux données de configuration.

ConfigExample.razor:

@page "/config-example"
@inject IConfiguration Configuration

<PageTitle>Configuration</PageTitle>

<h1 style="font-size:@Configuration["h1FontSize"]">
    Configuration example (50px)
</h1>

Les restrictions de sécurité du client empêchent l’accès direct aux fichiers via le code utilisateur, y compris les fichiers de paramètres pour la configuration de l’application. Pour lire les fichiers de configuration en plus de appsettings.json/appsettings.{ENVIRONMENT}.json du dossier wwwroot dans la configuration, utilisez un HttpClient.

Avertissement

Les fichiers de configuration et de paramètres dans la racine web (dossier wwwroot) sont visibles par les utilisateurs sur le client, et les utilisateurs peuvent falsifier les données. Ne stockez pas de secrets d’application, d’informations d’identification ou autres données sensibles dans un fichier racine web.

L’exemple suivant lit un fichier de configuration (cars.json) dans la configuration de l’application.

wwwroot/cars.json:

{
    "size": "tiny"
}

Ajoutez l’espace de noms pour Microsoft.Extensions.Configuration au fichier Program :

using Microsoft.Extensions.Configuration;

Modifiez l’inscription de service HttpClient existante pour utiliser le client afin de lire le fichier :

var http = new HttpClient()
{
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
};

builder.Services.AddScoped(sp => http);

using var response = await http.GetAsync("cars.json");
using var stream = await response.Content.ReadAsStreamAsync();

builder.Configuration.AddJsonStream(stream);

L’exemple précédent définit l’adresse de base avec builder.HostEnvironment.BaseAddress (IWebAssemblyHostEnvironment.BaseAddress). Cette propriété récupère l’adresse de base de l’application. Elle est généralement dérivée de la valeur href de la balise <base> dans la page hôte.

Source de configuration de la mémoire

L’exemple suivant utilise un MemoryConfigurationSource dans le fichier Program pour fournir une configuration supplémentaire.

Ajoutez l’espace de noms pour Microsoft.Extensions.Configuration.Memory dans le fichier Program :

using Microsoft.Extensions.Configuration.Memory;

Dans le fichier Program :

var vehicleData = new Dictionary<string, string?>()
{
    { "color", "blue" },
    { "type", "car" },
    { "wheels:count", "3" },
    { "wheels:brand", "Blazin" },
    { "wheels:brand:type", "rally" },
    { "wheels:year", "2008" },
};

var memoryConfig = new MemoryConfigurationSource { InitialData = vehicleData };

builder.Configuration.Add(memoryConfig);

Injectez une instance IConfiguration dans un composant pour accéder aux données de configuration.

MemoryConfig.razor:

@page "/memory-config"
@inject IConfiguration Configuration

<PageTitle>Memory Configuration</PageTitle>

<h1>Memory Configuration Example</h1>

<h2>General specifications</h2>

<ul>
    <li>Color: @Configuration["color"]</li>
    <li>Type: @Configuration["type"]</li>
</ul>

<h2>Wheels</h2>

<ul>
    <li>Count: @Configuration["wheels:count"]</li>
    <li>Brand: @Configuration["wheels:brand"]</li>
    <li>Type: @Configuration["wheels:brand:type"]</li>
    <li>Year: @Configuration["wheels:year"]</li>
</ul>

Obtenez une section de la configuration en code C# avec IConfiguration.GetSection. L’exemple suivant obtient la section wheels de la configuration de l’exemple précédent :

@code {
    protected override void OnInitialized()
    {
        var wheelsSection = Configuration.GetSection("wheels");

        ...
    }
}

Configuration de l'authentification

Fournissez une configuration d’authentification publique dans un fichier de paramètres d’application.

wwwroot/appsettings.json:

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

Chargez la configuration d’un fournisseur Identity avec ConfigurationBinder.Bind dans le fichier Program. L’exemple suivant charge la configuration d’un fournisseur OIDC :

builder.Services.AddOidcAuthentication(options =>
    builder.Configuration.Bind("Local", options.ProviderOptions));

Avertissement

Les fichiers de configuration et de paramètres dans la racine web (dossier wwwroot) sont visibles par les utilisateurs sur le client, et les utilisateurs peuvent falsifier les données. Ne stockez pas de secrets d’application, d’informations d’identification ou autres données sensibles dans un fichier racine web.

Configuration de la journalisation

Cette section s’applique aux applications qui configurent la journalisation via un fichier de paramètres d’application dans le dossier wwwroot.

Ajoutez le package Microsoft.Extensions.Logging.Configuration à l’application.

Remarque

Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles figurant sous Installer et gérer des packages dans Flux de travail de la consommation des packages (documentation NuGet). Vérifiez les versions du package sur NuGet.org.

Dans le fichier de paramètres de l’application, indiquez la configuration de journalisation. La configuration de journalisation est chargée dans le fichier Program.

wwwroot/appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Dans le fichier Program :

builder.Logging.AddConfiguration(
    builder.Configuration.GetSection("Logging"));

Configuration de build de l’hôte

Lisez la configuration de build de l’hôte à partir de WebAssemblyHostBuilder.Configuration dans le fichier Program :

var hostname = builder.Configuration["HostName"];

Configuration mise en cache

Les fichiers de configuration sont mis en cache pour une utilisation hors connexion. Avec les Applications web progressives (PWA), vous pouvez uniquement mettre à jour les fichiers de configuration lors de la création d’un nouveau déploiement. La modification des fichiers de configuration entre les déploiements n’a aucun effet, car :

• Les utilisateurs ont mis en cache des versions des fichiers qu’ils continuent d’utiliser.
• Les fichiers service-worker.js et service-worker-assets.js de la PWA doivent être regénérés lors de la compilation, ce qui signale à l’application, lors de la prochaine visite en ligne de l’utilisateur, que l’application a été redéployée.

Pour plus d’informations sur la façon dont les mises à jour en arrière-plan sont gérées par les PWA, consultez Application web progressive (PWA) Blazor ASP.NET Core.

Configuration des options

La configuration des options nécessite l’ajout d’une référence de package pour le package NuGet Microsoft.Extensions.Options.ConfigurationExtensions.

Remarque

Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles figurant sous Installer et gérer des packages dans Flux de travail de la consommation des packages (documentation NuGet). Vérifiez les versions du package sur NuGet.org.

Exemple :

builder.Services.Configure<MyOptions>(
    builder.Configuration.GetSection("MyOptions"));

Les Fonctionnalités des options ASP.NET Core ne sont pas toutes prises en charge dans les composants Razor. Par exemple, la configuration IOptionsSnapshot<TOptions> et IOptionsMonitor<TOptions> est prise en charge, mais le recalcul des valeurs d’option pour ces interfaces n’est pas prise en charge en dehors du rechargement de l’application, soit en requérant l’application dans un nouvel onglet du navigateur, soit en sélectionnant le bouton de rechargement du navigateur. Le simple fait d’appeler StateHasChanged ne met pas à jour les valeurs de l’instantané ou des options surveillées lorsque la configuration sous-jacente change.