Fichier web.config

  • Article

Le fichier web.config est un fichier lu par IIS et le module ASP.NET Core pour configurer une application hébergée avec IIS.

Emplacement du fichier web.config

Pour que la configuration du module ASP.NET Core soit réussie, le fichier web.config doit être présent dans le chemin de la racine du contenu (généralement le chemin de base) de l’application déployée. Il s’agit du même emplacement que le chemin physique du site Web fourni à IIS. Le fichier web.config est nécessaire à la racine de l’application pour permettre la publication de plusieurs applications à l’aide de Web Deploy.

Il existe des fichiers sensibles dans le chemin physique de l’application, par exemple {ASSEMBLY}.runtimeconfig.json, {ASSEMBLY}.xml (commentaires de documentation XML) et {ASSEMBLY}.deps.json, où l’espace réservé {ASSEMBLY} correspond au nom de l’assembly. Quand le fichier web.config est présent et que le site démarre normalement, IIS ne traite pas ces fichiers sensibles s’ils sont demandés. Si le fichier web.config est manquant, s’il est nommé de manière incorrecte ou s’il ne permet pas de configurer le site pour un démarrage normal, IIS peut traiter les fichiers sensibles de manière publique.

Le fichier web.config doit être présent à tout moment dans le déploiement, il doit être correctement nommé et permettre la configuration du site pour un démarrage normal. Ne retirez jamais le fichier web.config d’un déploiement de production.

Si le projet ne contient pas de fichier web.config, celui-ci est créé avec le processPath et les arguments appropriés pour configurer le module ASP.NET Core, puis il est déplacé vers la sortie publiée.

Si le projet contient un fichier web.config, celui-ci est transformé avec le processPath et les arguments appropriés pour configurer le module ASP.NET Core, puis il est déplacé vers la sortie publiée. La transformation ne modifie pas les paramètres de configuration IIS dans le fichier.

Le fichier web.config peut fournir des paramètres de configuration IIS supplémentaires qui contrôlent les modules IIS actifs. Pour plus d’informations sur les modules IIS capables de traiter les requêtes avec des applications ASP.NET Core, consultez la rubrique Modules IIS.

La création, la transformation et la publication du fichier web.config sont gérées par une cible MSBuild (_TransformWebConfig) au moment de la publication du projet. Cette cible est présente dans les cibles du SDK web (Microsoft.NET.Sdk.Web). Le SDK est défini en haut du fichier projet :

<Project Sdk="Microsoft.NET.Sdk.Web">

Pour empêcher le kit SDK web de transformer le fichier web.config, utilisez la propriété <IsTransformWebConfigDisabled> dans le fichier projet :

<PropertyGroup>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

Quand vous désactivez le kit SDK web pour empêcher la transformation du fichier, processPath et arguments doivent être définis manuellement par le développeur. Pour plus d’informations, consultez Module ASP.NET Core (ANCM) pour IIS.

Configuration du module ASP.NET Core avec web.config

Le module ASP.NET Core est configuré avec la section aspNetCore du nœud system.webServer dans le fichier web.config du site.

Le fichier web.config suivant est publié pour un déploiement dépendant du framework et configure le module ASP.NET Core pour gérer les demandes du site :

<?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="dotnet"
                  arguments=".\MyApp.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

Le fichier web.config suivant est publié pour un déploiement autonome :

<?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 propriété InheritInChildApplications est définie sur false pour indiquer que les paramètres spécifiés dans l’élément <location> ne sont pas hérités par les applications qui résident dans un sous-répertoire de l’application.

Lorsqu’une application est déployée sur Azure App Service, le chemin d’accès stdoutLogFile est défini sur \\?\%home%\LogFiles\stdout. Le chemin enregistre les journaux stdout dans le dossier LogFiles, un emplacement automatiquement créé par le service.

Pour obtenir des informations sur la configuration d’une sous-application IIS, consultez Configuration avancée.

Attributs de l’élément aspNetCore

Attribut Description Default
arguments

Attribut de chaîne facultatif.

Arguments pour l’exécutable spécifié dans processPath.
disableStartUpErrorPage

Attribut booléen facultatif.

Si la valeur est true, la page 502.5 – Échec du processus est supprimée, et la page de code d’état 502 configurée dans le fichier web.config est prioritaire.

 false
forwardWindowsAuthToken

Attribut booléen facultatif.

Si la valeur est true, le jeton est transféré au processus enfant qui écoute sur %ASPNETCORE_PORT% sous la forme d’un en-tête « MS-ASPNETCORE-WINAUTHTOKEN » par demande. Il incombe à ce processus d’appeler CloseHandle sur ce jeton par demande.

 true
hostingModel

Attribut de chaîne facultatif.

Spécifie le modèle d’hébergement comme étant in-process (InProcess/inprocess) ou out-of-process (OutOfProcess/outofprocess).

 OutOfProcess/outofprocess lorsqu’il n’est pas présent
processesPerApplication

Attribut entier facultatif.

Spécifie le nombre d’instances du processus indiqué dans le paramètre processPath qui peuvent être lancées par application.

†Pour l’hébergement in-process, la valeur est limitée à 1.

Il est déconseillé de définir processesPerApplication. Cet attribut sera supprimé dans une version ultérieure.

 Valeur par défaut : 1
Min : 1
Max : 100†
processPath

Attribut de chaîne requis.

Chemin d’accès au fichier exécutable lançant un processus d’écoute des requêtes HTTP. Les chemins d’accès relatifs sont pris en charge. Si le chemin d’accès commence par ., il est considéré comme étant relatif par rapport à la racine du site.
rapidFailsPerMinute

Attribut entier facultatif.

Indique le nombre de fois où le processus spécifié dans processPath est autorisé à se bloquer par minute. Si cette limite est dépassée, le module arrête le lancement du processus pour le reste de la minute.

Non pris en charge avec hébergement in-process.

 Valeur par défaut : 10
Min : 0
Max : 100
requestTimeout

Attribut timespan facultatif.

Spécifie la durée pendant laquelle le module ASP.NET Core attend une réponse de la part du processus à l’écoute sur %ASPNETCORE_PORT%.

Dans les versions du module ASP.NET Core fournies avec ASP.NET Core 2.1 ou version ultérieure, la valeur requestTimeout est spécifiée en heures, minutes et secondes.

Ne s’applique pas à l’hébergement in-process. Pour l’hébergement in-process, le module attend que l’application traite la requête.

Les valeurs valides pour les segments de minutes et secondes de la chaîne sont dans la plage de 0 à 59. L’utilisation de 60 dans la valeur de minutes ou de secondes entraîne l’affichage de 500 – Erreur interne du serveur.

 Valeur par défaut : 00:02:00
Min : 00:00:00
Max : 360:00:00
shutdownTimeLimit

Attribut entier facultatif.

Durée en secondes pendant laquelle le module attend que l’exécutable s’arrête normalement quand le fichier app_offline.htm est détecté.

 Valeur par défaut : 10
Min : 0
Max : 600
startupTimeLimit

Attribut entier facultatif.

Durée en secondes pendant laquelle le module attend que le fichier exécutable démarre un processus à l’écoute sur le port. Si cette limite de temps est dépassée, le module met fin au processus.

Lors d’un hébergement in-process : le processus n’est pas redémarré et n’utilise pas le paramètre rapidFailsPerMinute.

Lors d’un hébergement hors processus : le module tente de relancer le processus lorsqu’il reçoit une nouvelle demande, puis continue d’essayer de redémarrer le processus pour les demandes entrantes suivantes, sauf si l’application ne démarre pas rapidFailsPerMinute un certain nombre de fois au cours de la dernière minute.

La valeur 0 (zéro) n’est pas considérée comme un délai infini.

 Valeur par défaut : 120
Min : 0
Max : 3600
stdoutLogEnabled

Attribut booléen facultatif.

Si la valeur est true, stdout et stderr pour le processus spécifié dans processPath sont redirigés vers le fichier spécifié dans stdoutLogFile.

 false
stdoutLogFile

Attribut de chaîne facultatif.

Spécifie le chemin relatif ou absolu pour lequel stdout et stderr du processus spécifié dans processPath sont consignés. Les chemins d’accès relatifs sont relatifs par rapport à la racine du site. Tout chemin d’accès commençant par . est relatif par rapport à la racine du site et tous les autres chemins d’accès sont traités comme des chemins d’accès absolus. Tous les dossiers fournis dans le chemin sont créés par le module au moment de la création du fichier journal. Si vous utilisez des délimiteurs de trait de soulignement, un horodatage, un ID de processus et une extension de fichier (.log) sont ajoutés au dernier segment du chemin stdoutLogFile. Si .\logs\stdout est fourni en tant que valeur, un exemple de journal stdout est enregistré en tant que stdout_20180205194132_1934.log dans le dossier logs avec un enregistrement effectué le 5 février 2018 à 19:41:32 et un ID de processus de 1934.

 aspnetcore-stdout

Définir des variables d’environnement

Des variables d’environnement peuvent être spécifiées pour le processus dans l’attribut processPath. Spécifiez une variable d’environnement à l’aide de l’élément enfant <environmentVariable> d’un élément de collection <environmentVariables>. Les variables d’environnement définies dans cette section prévalent sur les variables d’environnement système.

L’exemple suivant définit deux variables d’environnement dans web.config. ASPNETCORE_ENVIRONMENT définit l’environnement de l’application sur Development. Un développeur peut définir temporairement cette valeur dans le fichier web.config afin de forcer le chargement de la Page d’exceptions du développeur lors du débogage d’une exception d’application. CONFIG_DIR est un exemple de variable d’environnement définie par l’utilisateur, dans laquelle le développeur a écrit du code qui lit la valeur de démarrage afin de former un chemin d’accès pour le chargement du fichier de configuration 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="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

Notes

Une alternative à la définition directe de l’environnement dans web.config consiste à inclure la propriété <EnvironmentName> dans le profil de publication (.pubxml) ou le fichier projet. Cette approche définit l’environnement dans web.config lorsque le projet est publié :

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Avertissement

Affectez uniquement Development à la variable d’environnement ASPNETCORE_ENVIRONMENT sur les serveurs de test et de préproduction non accessibles aux réseaux non approuvés, par exemple Internet.

Configuration d’IIS avec web.config

La configuration d’IIS est influencée par la section <system.webServer> de web.config pour les scénarios IIS qui sont fonctionnels pour les applications ASP.NET Core avec le module ASP.NET Core. Par exemple, la configuration IIS est fonctionnelle pour la compression dynamique. Si IIS est configuré au niveau du serveur pour utiliser la compression dynamique, l’élément <urlCompression> dans le fichier web.config de l’application peut le désactiver pour une application ASP.NET Core.

Pour plus d'informations, voir les rubriques suivantes :

Pour définir les variables d’environnement d’applications individuelles s’exécutant dans des pools d’applications isolés (pris en charge pour IIS 10.0 ou version ultérieure), consultez la section Commande AppCmd.exe de la rubrique Variables d’environnement <environmentVariables> dans la documentation de référence d’IIS.

Sections de configuration de web.config

Les sections de configuration des applications ASP.NET 4.x dans web.config ne sont pas utilisées par les applications ASP.NET Core pour la configuration :

  • <system.web>
  • <appSettings>
  • <connectionStrings>
  • <location>

Les applications ASP.NET Core sont configurées à l’aide d’autres fournisseurs de configuration. Pour plus d’informations, consultez Configuration.

Transformer web.config

Si vous devez transformer web.config au moment de la publication, consultez Transformer web.config. Vous devrez peut-être transformer web.config au moment de la publication pour définir les variables d’environnement en fonction de la configuration, du profil ou de l’environnement.

Ressources supplémentaires