la configuration d’une application ;

Conseil

Ce contenu est un extrait du livre électronique, Blazor pour les développeurs ASP NET Web Forms pour Azure, disponible dans la documentation .NET ou au format PDF à télécharger gratuitement pour le lire hors connexion.

Télécharger le PDF

La principale façon de charger la configuration de l'application dans les formulaires web consiste à utiliser des entrées dans le fichier web.config, soit sur le serveur, soit dans un fichier de configuration connexe référencé par web.config. Vous pouvez utiliser l'objet statique ConfigurationManager pour interagir avec les paramètres de l'application, les chaînes de connexion du référentiel de données et d'autres fournisseurs de configuration étendue qui sont ajoutés à l'application. Il est fréquent de voir des interactions avec la configuration de l'application, notamment dans le code suivant :

var configurationValue = ConfigurationManager.AppSettings["ConfigurationSettingName"];
var connectionString = ConfigurationManager.ConnectionStrings["MyDatabaseConnectionName"].ConnectionString;

Avec ASP.NET Core et Blazor côté serveur, le fichier web.config peut être présent si votre application est hébergée sur un serveur Windows IIS. Mais il n’existe aucune interaction ConfigurationManager avec cette configuration et vous pouvez recevoir une configuration d’application plus structurée à partir d’autres sources. Voyons comment la configuration est collectée et comment il est possible de toujours accéder aux informations de configuration à partir d’un fichier web.config.

Sources de configuration

ASP.NET Core reconnaît qu’il existe de nombreuses sources de configuration que vous pouvez utiliser pour votre application. L’infrastructure tente de vous offrir les fonctionnalités par défaut. La configuration est lue et agrégée à partir de ces différentes sources par ASP.NET Core. Les valeurs chargées ultérieurement pour la même clé de configuration sont prioritaires sur les valeurs antérieures.

ASP.NET Core a été conçu pour prendre en charge le cloud et faciliter la configuration des applications pour les opérateurs et les développeurs. ASP.NET Core prend en compte l’environnement et identifie s’il est en cours d’exécution dans votre environnement Production ou Development. L’indicateur d’environnement est défini dans la variable d’environnement système ASPNETCORE_ENVIRONMENT. Si aucune valeur n’est configurée, l’application s’exécute par défaut dans l’environnement Production.

Votre application peut déclencher et ajouter une configuration à partir de plusieurs sources en fonction du nom de l’environnement. Par défaut, la configuration est chargée à partir des ressources suivantes dans l’ordre indiqué :

1. Fichier appsettings.json, s’il est présent
2. Fichier appsettings.{ENVIRONMENT_NAME}.json, s’il est présent
3. Fichier de secrets utilisateur sur le disque, s’il est présent
4. Variables d'environnement
5. Arguments de ligne de commande

Format du fichier appsettings.json et accès à celui-ci

Le fichier appsettings.json peut être hiérarchique, avec des valeurs structurées comme l’exemple JSON suivant :

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  }
}

Lorsqu’il est présenté avec le modèle JSON précédent, le système de configuration aplatit les valeurs enfants et référence leurs chemins hiérarchiques complets. Un caractère deux-points (:) sépare chaque propriété de la hiérarchie. Par exemple, la clé configuration section1:key0 permet d’accéder à la valeur du section1littéral de l’objetkey0.

Secrets utilisateur

Les secrets utilisateur sont les suivants :

• Valeurs de configuration stockées dans un fichier JSON sur la station de travail du développeur, en dehors du dossier de développement de l’application.
• Chargé uniquement lors de l’exécution dans l’environnement Development.
• Associé à une application spécifique.
• Géré avec la commande user-secrets de l’interface CLI .NET.

Configurez votre application pour le stockage des secrets en exécutant la commande user-secrets :

dotnet user-secrets init

La commande précédente ajoute un élément UserSecretsId au fichier projet. L’élément contient un GUID, utilisé pour associer des secrets à l’application. Vous pouvez ensuite définir un secret avec la commande set. Par exemple :

dotnet user-secrets set "Parent:ApiKey" "12345"

La commande précédente met à disposition la clé de configuration sur la station de travail Parent:ApiKey d’un développeur avec la valeur 12345.

Pour plus d’informations sur la création, le stockage et la gestion des secrets utilisateur, consultez le document Stockage sécurisé des secrets d’application en développement dans ASP.NET Core.

Variables d'environnement

L’ensemble suivant de valeurs chargées dans la configuration de votre application représente les variables d’environnement du système. Tous les paramètres de variable d’environnement de votre système sont désormais accessibles via l’API de configuration. Les valeurs hiérarchiques sont aplaties et séparées par un caractère deux-points lors de la lecture depuis votre application. Toutefois, certains systèmes d’exploitation n’autorisent pas les noms de variables d’environnement contenant le caractère deux-points. ASP.NET Core résout cette limitation en convertissant les valeurs comportant des traits de soulignement doubles (__) en deux-points lorsqu’elles sont accessibles. La valeur Parent:ApiKey de la section des secrets d'utilisateur ci-dessus peut être remplacée par la variable d'environnement Parent__ApiKey.

Arguments de ligne de commande

La configuration peut également être fournie sous forme d'arguments de ligne de commande lors du démarrage de votre application. Utilisez le double tiret (--) ou la barre oblique (/) pour indiquer le nom de la valeur de configuration à définir et la valeur à configurer. La syntaxe ressemble aux commandes suivantes :

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run Parent:ApiKey=67890

Retour de web.config

Si vous avez déployé votre application pour Windows sur IIS, le fichier web.config configure toujours IIS pour gérer votre application. Par défaut, IIS ajoute une référence au module ASP.NET Core (ANCM). ANCM est un module IIS natif qui héberge votre application à la place du serveur web Kestrel. Cette section web.config ressemble au balisage XML suivant :

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

La configuration spécifique à l'application peut être définie en imbriquant un élément environmentVariables dans l'élément aspNetCore. Les valeurs définies dans cette section sont présentées à l'application ASP.NET Core sous forme de variables d'environnement. Les variables d'environnement se chargent de manière appropriée pendant ce segment du démarrage de l'application.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="Parent:ApiKey" value="67890" />
  </environmentVariables>
</aspNetCore>

Lire la configuration dans l’application

ASP.NET Core permet de configurer les applications via l'interface IConfiguration. Cette interface de configuration doit être sollicitée par vos composants Blazor, vos pages Blazor et toute autre classe gérée par ASP.NET Core qui doit accéder à la configuration. Le framework ASP.NET Core remplira automatiquement cette interface avec la configuration résolue configurée précédemment. Sur une page Blazor ou un balisage Razor d'un composant, vous pouvez injecter l'objet IConfiguration avec une directive @inject en haut du fichier .razor, comme ceci :

@inject IConfiguration Configuration

Cette déclaration précédente rend l'objet IConfiguration disponible comme variable Configuration dans le reste du modèle Razor.

Les paramètres de configuration individuels peuvent être lus en spécifiant la hiérarchie des paramètres de configuration recherchée comme paramètre d'indexation :

var mySetting = Configuration["section1:key0"];

Vous pouvez récupérer des sections entières de configuration en utilisant la méthode GetSection de récupération d'une collection de clés à un emplacement spécifique, avec une syntaxe similaire à celle de GetSection("section1") afin de récupérer la configuration pour la section1 de l'exemple précédent.

Configuration fortement typée

Avec Web Forms, il était possible de créer un type de configuration fortement typé qui héritait du type ConfigurationSection et des types associés. Un type ConfigurationSection vous permettait de configurer certaines règles de gestion et le traitement de ces valeurs de configuration.

Dans ASP.NET Core, vous pouvez spécifier une hiérarchie de classes qui recevra les valeurs de configuration. Ces classes :

• Il n'est pas nécessaire d'hériter d'une classe parente.
• Doit inclure des propriétés public qui correspondent aux propriétés et aux références de type pour la structure de configuration que vous souhaitez capturer.

Pour l'exemple appsettings.json précédent, vous pourriez définir les classes suivantes pour capturer les valeurs :

public class MyConfig
{
    public MyConfigSection section0 { get; set;}

    public MyConfigSection section1 { get; set;}
}

public class MyConfigSection
{
    public string key0 { get; set; }

    public string key1 { get; set; }
}

Cette hiérarchie de classes peut être renseignée en ajoutant la ligne suivante à la méthode Startup.ConfigureServices (ou à l'emplacement approprié dans le fichier Program.cs en utilisant la propriété builder.Services au lieu de services) :

services.Configure<MyConfig>(Configuration);

Dans le reste de l'application, vous pouvez ajouter un paramètre d'entrée aux classes ou une directive @inject dans les modèles Razor de type IOptions<MyConfig> pour recevoir les paramètres de configuration fortement typés. La propriété IOptions<MyConfig>.Value renverra la valeur MyConfig obtenue à partir des paramètres de configuration.

@inject IOptions<MyConfig> options
@code {
    var MyConfiguration = options.Value;
    var theSetting = MyConfiguration.section1.key0;
}

Pour plus d’informations sur la fonctionnalité Options, consultez le document Modèle d’options dans ASP.NET Core.

PrécédentSuivant