Module ASP.NET Core (ANCM) pour IIS

Article
11/06/2024

Remarque

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 8 de cet article.

Avertissement

Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la Stratégie de prise en charge de .NET et .NET Core. Pour la version actuelle, consultez la version .NET 8 de cet article.

Important

Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Pour la version actuelle, consultez la version .NET 8 de cet article.

Le module ASP.NET Core (ANCM) est un module IIS natif qui se connecte au pipeline IIS, ce qui permet aux applications ASP.NET Core de fonctionner avec IIS. Exécutez les applications ASP.NET Core avec IIS en procédant d’une des manières suivantes :

Hébergez une application ASP.NET Core à l’intérieur du processus de travail IIS (w3wp.exe), appelé modèle d’hébergement in-process.
Transférez les demandes web à une application ASP.NET Core back-end exécutant le serveur Kestrel, appelée modèle d’hébergement hors processus.

Chaque modèle d’hébergement présente des avantages et des inconvénients. Le modèle d’hébergement in-process est utilisé par défaut, en raison de meilleurs diagnostics et performances.

Pour plus d’informations et pour obtenir de l’aide sur la configuration, consultez les rubriques suivantes :

Implémentations de serveurs web dans ASP.NET Core

Installer le module ASP.NET Core (ANCM)

Le module ASP.NET Core (ANCM) est installé avec le runtime .NET Core à partir du bundle d’hébergement .NET Core. Le module ASP.NET Core assure la compatibilité descendante et ascendante avec les versions avec support technique de .NET.

Les changements cassants et les avis de sécurité sont signalés dans le dépôt Annonces. Les annonces peuvent être limitées à une version spécifique en sélectionnant un filtre Étiquette.

Téléchargez le programme d’installation à l’aide du lien suivant :

Programme d’installation du bundle d’hébergement .NET Core actuel (téléchargement direct)

Pour plus d’informations, notamment l’installation d’une version antérieure du module, consultez Bundle d’hébergement.

Pour accéder à un tutoriel sur la publication d’une application ASP.NET Core sur un serveur IIS, consultez Publier une application ASP.NET Core sur IIS.

Le module ASP.NET Core (ANCM) est un module IIS natif qui se connecte dans le pipeline IIS pour effectuer l’une des opérations suivantes :

Héberger une application ASP.NET Core à l’intérieur du processus de travail IIS (w3wp.exe), appelé modèle d’hébergement in-process.
Transférer les demandes web à une application ASP.NET Core back-end exécutant le serveur Kestrel, appelée modèle d’hébergement hors processus.

Versions de Windows prises en charge :

Windows 7 ou version ultérieure
Windows Server 2012 R2 ou version ultérieure

Lors de l’hébergement in-process, le module utilise une implémentation du serveur in-process pour IIS, nommée serveur HTTP IIS (IISHttpServer).

Lors de l’hébergement hors processus, le module fonctionne uniquement avec Kestrel. Le module ne fonctionne pas avec HTTP.sys.

Modèles d'hébergement

Modèle d’hébergement in-process

Les applications ASP.NET Core utilisent par défaut le modèle d’hébergement in-process.

Les caractéristiques suivantes s’appliquent lors de l’hébergement in-process :

Le serveur IIS HTTP (IISHttpServer) est utilisé à la place du serveur Kestrel. Pour in-process, CreateDefaultBuilder appelle UseIIS pour :
- Enregistrer IISHttpServer.
- Configurer le port et le chemin de base sur lesquels le serveur doit écouter lors de l’exécution derrière le module ASP.NET Core.
- Configurer l’hôte pour capturer des erreurs de démarrage.
L’attribut requestTimeout ne s’applique pas à l’hébergement in-process.
Le partage d’un pool d’applications entre les applications n’est pas pris en charge. Utilisez un pool d’applications par application.
Lorsque vous utilisez Web Deploy ou que vous placez manuellement un fichier app_offline.htm dans le déploiement, l’application peut ne pas s’arrêter immédiatement si une connexion est ouverte. Par exemple, une connexion WebSocket peut retarder l’arrêt de l’application.
L’architecture (nombre de bits) de l’application et le runtime installé (x64 ou x86) doivent correspondre à l’architecture du pool d’applications.
Les déconnexions du client sont détectées. Le jeton d’annulation HttpContext.RequestAborted est annulé lors de la déconnexion du client.
Dans ASP.NET Core 2.2.1 ou version antérieure, GetCurrentDirectory retourne le répertoire de travail du processus démarré par IIS, et non le répertoire de l’application (par exemple, C:\Windows\System32\inetsrv pour w3wp.exe).

Pour connaître l’exemple de code qui définit le répertoire actuel de l’application, consultez la classe CurrentDirectoryHelpers. Appelez la méthode SetCurrentDirectory . Les appels suivants à GetCurrentDirectory fournissent le répertoire de l’application.
Dans le cas d’un hébergement in-process, AuthenticateAsync n’est pas appelé en interne pour initialiser un utilisateur. Par conséquent, une implémentation de IClaimsTransformation utilisée pour transformer les revendications après chaque authentification n’est pas activée par défaut. Si vous transformez les revendications avec une implémentation de IClaimsTransformation, appelez AddAuthentication pour ajouter des services d’authentification :
```
public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}
```
- Les déploiements de package web (fichier unique) ne sont pas pris en charge.

Modèle d’hébergement out-of-process

Pour configurer une application pour l’hébergement hors processus, définissez la valeur de la propriété <AspNetCoreHostingModel> sur OutOfProcess dans le fichier projet (.csproj) :

<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

L’hébergement in-process est défini avec InProcess, qui est la valeur par défaut.

La valeur de <AspNetCoreHostingModel> ne respecte pas la casse, inprocess et outofprocess sont donc des valeurs valides.

Le serveur Kestrel est utilisé à la place du serveur HTTP IIS (IISHttpServer).

Pour le cas hors processus, CreateDefaultBuilder appelle UseIISIntegration pour :

Configurer le port et le chemin de base sur lesquels le serveur doit écouter lors de l’exécution derrière le module ASP.NET Core.
Configurer l’hôte pour capturer des erreurs de démarrage.

Modifications du modèle d’hébergement

Si le paramètre hostingModel est modifié dans le fichier web.config (comme expliqué dans la section Configuration avec web.config), le module recycle le processus de travail pour IIS.

Pour IIS Express, le module ne recycle pas le processus de travail, mais déclenche plutôt un arrêt approprié du processus IIS Express en cours. La requête suivante à l’application génère un nouveau processus IIS Express.

Nom du processus

Process.GetCurrentProcess().ProcessName signale w3wp/iisexpress (in-process) ou dotnet (out-of-process).

De nombreux modules natifs, comme l’authentification Windows, restent actifs. Pour obtenir plus d’informations sur les modules IIS actifs avec le module ASP.NET Core, consultez Modules IIS avec ASP.NET Core.

Le module ASP.NET Core peut également :

Définir des variables d’environnement pour le processus de travail.
Journaliser la sortie de stdout dans un stockage de fichiers pour résoudre les problèmes de démarrage.
Transférer des jetons d’authentification Windows.

Comment installer et utiliser le module ASP.NET Core (ANCM)

Pour obtenir des instructions sur l’installation du module ASP.NET Core, consultez Installer le bundle d’hébergement .NET Core. Le module ASP.NET Core assure la compatibilité descendante et ascendante avec les versions avec support technique de .NET.

Les changements cassants et les avis de sécurité sont signalés dans le dépôt Annonces. Les annonces peuvent être limitées à une version spécifique en sélectionnant un filtre Étiquette.

Configuration 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 de sous-application IIS, consultez Héberger ASP.NET Core sur Windows avec IIS.

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`).	`InProcess` `inprocess`
`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 affiche 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, les attributs stdout et stderr du 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 d’accès relatif ou absolu pour lequel les attributs 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. Avec des traits de soulignement de séparation, 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 05/02/2018 à 19:41:32 avec l’ID de processus 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.

`app_offline.htm`

Si un fichier portant le nom app_offline.htm est détecté dans le répertoire racine d’une application, le module ASP.NET Core tente d’arrêter normalement l’application, puis interrompt le traitement des demandes entrantes. Si l’application est toujours active après le nombre de secondes défini dans shutdownTimeLimit, le module ASP.NET Core met fin au processus en cours d’exécution.

Tant que le fichier app_offline.htm est présent, le module ASP.NET Core répond aux requêtes en renvoyant le contenu du fichier app_offline.htm. Lorsque le fichier app_offline.htm est supprimé, la requête suivante démarre l’application.

Lorsque vous utilisez le modèle d’hébergement out-of-process, l’application peut ne pas s’arrêter immédiatement s’il existe une connexion ouverte. Par exemple, une connexion WebSocket peut retarder l’arrêt de l’application.

Page d’erreur de démarrage

Les hébergements in-process et out-of-process produisent des pages d’erreurs personnalisées quand ils ne parviennent pas à démarrer l’application.

Si le module ASP.NET Core ne trouve pas le gestionnaire de requêtes in-process ou out-of-process, une page de code d’état 500.0 - Échec de chargement du gestionnaire in-process/out-of-process s’affiche.

Pour l’hébergement in-process, si le module ASP.NET Core ne peut pas démarrer l’application, une page de code d’état 500.30 - Échec de démarrage s’affiche.

Pour l’hébergement out-of-process, si le module ASP.NET Core ne peut pas lancer le processus backend ou que ce dernier démarre mais ne parvient pas à écouter sur le port configuré, une page de code d’état 502.5 - Échec du processus s’affiche.

Pour supprimer cette page et revenir à la page IIS de codes d’état 5xx par défaut, utilisez l’attribut disableStartUpErrorPage. Pour plus d’informations sur la configuration des messages d’erreur personnalisés, consultez Erreurs HTTP <httpErrors>.

Création et redirection de journal

Le module ASP.NET Core redirige la sortie de console stdout et stderr vers le disque si les attributs stdoutLogEnabled et stdoutLogFile de l’élément aspNetCore sont définis. Tous les dossiers du chemin stdoutLogFile sont créés par le module au moment de la création du fichier journal. Le pool d’applications doit avoir un accès en écriture à l’emplacement auquel les journaux sont écrits (utilisez IIS AppPool\<app_pool_name> pour fournir les autorisations d’écriture).

Aucune rotation n’est appliquée aux journaux, sauf en cas de recyclage/redémarrage du processus. Il incombe à l’hébergeur de limiter l’espace disque utilisé par les journaux.

L’utilisation du journal stdout est recommandée uniquement pour résoudre les problèmes de démarrage d’application lors de l’hébergement sur IIS ou lors de l’utilisation de la prise en charge au moment du développement pour IIS avec Visual Studio, et non lors du débogage local et de l’exécution de l’application avec IIS Express.

N’utilisez pas le journal stdout à des fins de journalisation d’application générale. Pour les opérations de journalisation courantes dans une application ASP.NET Core, utilisez une bibliothèque de journalisation qui limite la taille du fichier journal et applique une rotation aux journaux. Pour plus d’informations, consultez Fournisseurs de journalisation tiers.

Un horodatage et une extension de fichier sont ajoutés automatiquement quand le fichier journal est créé. Le nom du fichier journal est créé en ajoutant l’horodatage, un ID de processus et une extension de fichier (.log) au dernier segment du chemin d’accès stdoutLogFile (généralement stdout), séparés par des traits de soulignement. Si le chemin d’accès stdoutLogFile se termine par stdout, un journal pour une application avec un PID de 1934 créé le 5/2/2018 à 19:42:32 affiche le nom de fichier stdout_20180205194132_1934.log.

Si stdoutLogEnabled a la valeur false, les erreurs qui se produisent au moment du démarrage de l’application sont capturées et émises dans le journal des événements (30 Ko maximum). Après le démarrage, tous les journaux supplémentaires sont ignorés.

L’exemple d’élément aspNetCore suivant configure la journalisation stdout au niveau du chemin d’accès relatif .\log\. Vérifiez que l’identity de l’utilisateur AppPool à l’autorisation d’écrire dans le chemin d’accès fourni.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout"
    hostingModel="inprocess">
</aspNetCore>

Lors de la publication d’une application pour le déploiement d’Azure App Service, le SDK web définit la valeur stdoutLogFile sur \\?\%home%\LogFiles\stdout. La variable d’environnement %home est prédéfinie pour les applications hébergées par Azure App Service.

Pour créer des règles de filtre de journalisation, consultez la section Appliquer des règles de filtre de journal dans le code de la documentation de journalisation ASP.NET Core.

Pour plus d’informations sur les formats de chemin d’accès, consultez Formats de chemin d’accès aux fichiers sur les systèmes Windows.

Journaux de diagnostic améliorés

Le module ASP.NET Core est configurable pour proposer des journaux de diagnostic améliorés. Ajoutez l’élément <handlerSettings> à l’élément <aspNetCore> dans web.config. L’affectation de la valeur TRACE à debugLevel expose une fidélité plus élevée des informations de diagnostic :

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

Tous les dossiers dans le chemin d’accès (logs dans l’exemple précédent) sont créés par le module lorsque le fichier journal est créé. Le pool d’applications doit avoir un accès en écriture à l’emplacement où les journaux sont écrits (utilisez IIS AppPool\{APP POOL NAME}, où l’espace réservé {APP POOL NAME} est le nom du pool d’applications, pour fournir les autorisations d’écriture).

Les valeurs du niveau de débogage (debugLevel) peuvent inclure à la fois le niveau et l’emplacement.

Niveaux (dans l’ordre du moins au plus détaillé) :

ERROR
WARNING
INFO
TRACE

Emplacements (plusieurs emplacements sont autorisés) :

CONSOLE
EVENTLOG
FILE

Les paramètres de gestionnaire peuvent également être fournis par le biais de variables d’environnement :

ASPNETCORE_MODULE_DEBUG_FILE : Chemin du fichier journal de débogage. (Valeur par défaut : aspnetcore-debug.log)
ASPNETCORE_MODULE_DEBUG : Paramètre du niveau de débogage.

Avertissement

Ne laissez pas la journalisation du débogage activée dans le déploiement plus longtemps que nécessaire pour résoudre un problème. La taille du journal n’est pas limitée. Si vous laissez la journalisation du débogage activée, vous risquez d’épuiser l’espace disque disponible et de bloquer le serveur ou le service d’application.

Consultez Configuration avec web.config pour obtenir un exemple d’élément aspNetCore dans le fichier web.config.

Modifier la taille de pile

S’applique uniquement lors de l’utilisation du modèle d’hébergement in-process.

Configurez la taille de pile managée à l’aide du paramètre stackSize en octets dans web.config. La taille par défaut est de 1 048 576 octets (1 Mo).

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="stackSize" value="2097152" />
  </handlerSettings>
</aspNetCore>

La configuration du proxy utilise le protocole HTTP et un jeton d’appariement

S’applique uniquement à l’hébergement out-of-process.

Le proxy créé entre le module ASP.NET Core et Kestrel utilise le protocole HTTP. Il n’existe aucun risque d’écoute clandestine du trafic entre le module et Kestrel à partir d’un emplacement sur le serveur.

Un jeton d’appairage est utilisé pour garantir que les demandes reçues par Kestrel ont été traitées par IIS et ne proviennent pas d’une autre source. Le jeton d’appariement est créé et défini dans une variable d’environnement (ASPNETCORE_TOKEN) par le module. Le jeton d’appariement est également défini dans un en-tête (MS-ASPNETCORE-TOKEN) sur toutes les demandes traitées. L'intergiciel IIS vérifie chaque demande qu’il reçoit pour confirmer que la valeur d’en-tête du jeton d'appariement correspond à la valeur de la variable d’environnement. Si les valeurs de jeton ne correspondent pas, la demande est connectée et rejetée. La variable d’environnement du jeton d'appairage et le trafic entre le module et Kestrel ne sont pas accessibles à partir d’un emplacement sur le serveur. Sans connaître la valeur du jeton d’appariement, un cyberattaquant ne peut pas soumettre de demandes qui contournent la vérification du middleware IIS.

Module ASP.NET Core avec une configuration partagée IIS

Le programme d’installation du module ASP.NET Core s’exécute avec les privilèges du compte TrustedInstaller. Comme le compte système local n’a pas l’autorisation de modifier le chemin de partage utilisé par la configuration partagée IIS, le programme d’installation génère une erreur d’accès refusé pendant la tentative de configuration des paramètres du module dans le fichier applicationHost.config du partage.

Quand une configuration partagée IIS est utilisée sur la même machine que l’installation IIS, il convient d’exécuter le programme d’installation du bundle d’hébergement ASP.NET Core avec le paramètre OPT_NO_SHARED_CONFIG_CHECK défini sur 1 :

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

Quand le chemin de la configuration partagée ne se trouve pas sur la même machine que l’installation IIS, effectuez ces étapes :

Désactivez la configuration partagée IIS.
Exécutez le programme d’installation.
Exportez le fichier applicationHost.config mis à jour vers le partage.
Réactivez la configuration partagée IIS.

Version du module et journaux du programme d’installation du bundle d’hébergement

Pour déterminer la version du module ASP.NET Core installé :

Sur le système d’hébergement, accédez à %windir%\System32\inetsrv.
Localisez le fichier aspnetcore.dll.
Cliquez avec le bouton droit sur le fichier, puis sélectionnez Propriétés dans le menu contextuel.
Sélectionnez l'onglet Détails. Le version du fichier et la version du produit représentent la version installée du module.

Les journaux du programme d’installation du bundle d’hébergement du module se trouvent dans C:\Users\%UserName%\AppData\Local\Temp. Le fichier est nommé dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log.

Emplacements des fichiers du module, du schéma et de configuration

Module

IIS (x86/amd64) :

%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll
%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64) :

%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

schéma

IIS

%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml

IIS Express

%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

Configuration

IIS

%windir%\System32\inetsrv\config\applicationHost.config

IIS Express

Visual Studio : {APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe CLI : %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Vous trouverez les fichiers en recherchant aspnetcore dans le fichier applicationHost.config.

Le module ASP.NET Core (ANCM) est un module IIS natif qui se connecte dans le pipeline IIS pour effectuer l’une des opérations suivantes :

Héberger une application ASP.NET Core à l’intérieur du processus de travail IIS (w3wp.exe), appelé modèle d’hébergement in-process.
Transférer les demandes web à une application ASP.NET Core back-end exécutant le serveur Kestrel, appelée modèle d’hébergement hors processus.

Versions de Windows prises en charge :

Windows 7 ou version ultérieure
Windows Server 2008 R2 ou version ultérieure

Lors de l’hébergement in-process, le module utilise une implémentation du serveur in-process pour IIS, nommée serveur HTTP IIS (IISHttpServer).

Lors de l’hébergement hors processus, le module fonctionne uniquement avec Kestrel. Le module ne fonctionne pas avec HTTP.sys.

Modèles d'hébergement

Modèle d’hébergement in-process

Pour configurer l’hébergement in-process dans une application, ajoutez la propriété <AspNetCoreHostingModel> au fichier projet de l’application en lui attribuant la valeur InProcess (l’hébergement out-of-process est défini sur OutOfProcess) :

<PropertyGroup>
  <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
</PropertyGroup>

Le modèle d’hébergement in-process n’est pas pris en charge pour les applications ASP.NET Core qui ciblent le .NET Framework.

La valeur de <AspNetCoreHostingModel> ne respecte pas la casse, inprocess et outofprocess sont donc des valeurs valides.

Si la propriété <AspNetCoreHostingModel> n’est pas présente dans le fichier, la valeur par défaut est OutOfProcess.

Les caractéristiques suivantes s’appliquent lors de l’hébergement in-process :

Le serveur IIS HTTP (IISHttpServer) est utilisé à la place du serveur Kestrel. Pour in-process, CreateDefaultBuilder appelle UseIIS pour :
- Enregistrer IISHttpServer.
- Configurer le port et le chemin de base sur lesquels le serveur doit écouter lors de l’exécution derrière le module ASP.NET Core.
- Configurer l’hôte pour capturer des erreurs de démarrage.
L’attribut requestTimeout ne s’applique pas à l’hébergement in-process.
Le partage d’un pool d’applications entre les applications n’est pas pris en charge. Utilisez un pool d’applications par application.
Lorsque vous utilisez Web Deploy ou que vous placez manuellement un fichier app_offline.htm dans le déploiement, l’application peut ne pas s’arrêter immédiatement si une connexion est ouverte. Par exemple, une connexion websocket peut retarder l’arrêt de l’application.
L’architecture (nombre de bits) de l’application et le runtime installé (x64 ou x86) doivent correspondre à l’architecture du pool d’applications.
Les déconnexions du client sont détectées. Le jeton d’annulation HttpContext.RequestAborted est annulé quand le client se déconnecte.
Dans ASP.NET Core version 2.2.1 ou antérieure, GetCurrentDirectory retourne le répertoire de travail du processus démarré par IIS, et non le répertoire de l’application (par exemple, C:\Windows\System32\inetsrv pour w3wp.exe).

Pour connaître l’exemple de code qui définit le répertoire actuel de l’application, consultez CurrentDirectoryHelpers, classe. Appelez la méthode SetCurrentDirectory . Les appels suivants à GetCurrentDirectory fournissent le répertoire de l’application.
Dans le cas d’un hébergement in-process, AuthenticateAsync n’est pas appelé en interne pour initialiser un utilisateur. Par conséquent, une implémentation de IClaimsTransformation utilisée pour transformer les revendications après chaque authentification n’est pas activée par défaut. Si vous transformez les revendications avec une implémentation de IClaimsTransformation, appelez AddAuthentication pour ajouter des services d’authentification :
```
public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}
```

Modèle d’hébergement out-of-process

Pour configurer une application pour un hébergement out-of-process, utilisez l’une des approches suivantes dans le fichier de projet :

Ne spécifiez pas la propriété <AspNetCoreHostingModel>. Si la propriété <AspNetCoreHostingModel> n’est pas présente dans le fichier, la valeur par défaut est OutOfProcess.
Définissez la valeur de la propriété <AspNetCoreHostingModel> sur OutOfProcess (l’hébergement in-process est défini avec InProcess) :

<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

La valeur ne respecte pas la casse, inprocess et outofprocess sont donc des valeurs valides.

Le serveur Kestrel est utilisé à la place du serveur HTTP IIS (IISHttpServer).

Pour out-of-process, CreateDefaultBuilder appelle UseIISIntegration pour :

Configurer le port et le chemin de base sur lesquels le serveur doit écouter lors de l’exécution derrière le module ASP.NET Core.
Configurer l’hôte pour capturer des erreurs de démarrage.

Modifications du modèle d’hébergement

Si le paramètre hostingModel est modifié dans le fichier web.config (comme expliqué dans la section Configuration avec web.config), le module recycle le processus de travail pour IIS.

Nom du processus

Process.GetCurrentProcess().ProcessName signale w3wp/iisexpress (in-process) ou dotnet (out-of-process).

Le module ASP.NET Core peut également :

Définir des variables d’environnement pour le processus de travail.
Journaliser la sortie de stdout dans un stockage de fichiers pour résoudre les problèmes de démarrage.
Transférer des jetons d’authentification Windows.

Comment installer et utiliser le module ASP.NET Core (ANCM)

Les changements cassants et les avis de sécurité sont signalés dans le dépôt Annonces. Les annonces peuvent être limitées à une version spécifique en sélectionnant un filtre Étiquette.

Configuration 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 <emplacement> ne sont pas hérités par les applications qui se trouvent 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 d’accès enregistre les journaux stdout dans le dossier LogFiles, un emplacement automatiquement créé par le service.

Pour obtenir des informations sur la configuration de sous-application IIS, consultez Héberger ASP.NET Core sur Windows avec IIS.

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 transmis 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`
`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 affiche 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, les attributs stdout et stderr du 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 05/02/2018 à 19:41:32 avec l’ID de processus 1934.	`aspnetcore-stdout`

Définition des variables d'environnement

L’exemple suivant définit deux variables d'environnement. 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>

Remarque

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

app_offline.htm

Lorsque vous utilisez le modèle d’hébergement out-of-process, l’application peut ne pas s’arrêter immédiatement s’il existe une connexion ouverte. Par exemple, une connexion websocket peut retarder l’arrêt de l’application.

Page d’erreur de démarrage

Les hébergements in-process et out-of-process produisent des pages d’erreurs personnalisées quand ils ne parviennent pas à démarrer l’application.

Pour l’hébergement in-process, si le module ASP.NET Core ne peut pas démarrer l’application, une page de code d’état 500.30 - Échec de démarrage s’affiche.

Création et redirection de journal

Le module ASP.NET Core redirige la sortie de console stdout et stderr vers le disque si les attributs stdoutLogEnabled et stdoutLogFile de l’élément aspNetCore sont définis. Tous les dossiers du chemin stdoutLogFile sont créés par le module au moment de la création du fichier journal. Le pool d’applications doit avoir un accès en écriture à l’emplacement auquel les journaux sont écrits (utilisez IIS AppPool\{APP POOL NAME} pour fournir les autorisations d’écriture, où l’espace réservé {APP POOL NAME} est le nom du pool d’applications).

Aucune rotation n’est appliquée aux journaux, sauf en cas de recyclage/redémarrage du processus. Il incombe à l’hébergeur de limiter l’espace disque utilisé par les journaux.

L’exemple d’élément aspNetCore suivant configure la journalisation stdout au niveau du chemin d’accès relatif .\log\. Vérifiez que l’identity de l’utilisateur du pool d’applications a l’autorisation d’écrire dans le chemin fourni.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout"
    hostingModel="inprocess">
</aspNetCore>

Pour plus d’informations sur les formats de chemin d’accès, consultez Formats de chemin d’accès aux fichiers sur les systèmes Windows.

Journaux de diagnostic améliorés

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

Les dossiers situés dans le chemin fourni pour la valeur <handlerSetting> (logs dans l’exemple précédent) ne sont pas créés automatiquement par le module. Ils doivent préexister dans le déploiement. Le pool d’applications doit avoir un accès en écriture à l’emplacement auquel les journaux sont écrits (utilisez IIS AppPool\{APP POOL NAME} pour fournir les autorisations d’écriture, où l’espace réservé {APP POOL NAME} est le nom du pool d’applications).

Les valeurs du niveau de débogage (debugLevel) peuvent inclure à la fois le niveau et l’emplacement.

Niveaux (dans l’ordre du moins au plus détaillé) :

ERROR
WARNING
INFO
TRACE

Emplacements (plusieurs emplacements sont autorisés) :

CONSOLE
EVENTLOG
FILE

Les paramètres de gestionnaire peuvent également être fournis par le biais de variables d’environnement :

ASPNETCORE_MODULE_DEBUG_FILE : Chemin du fichier journal de débogage. (Valeur par défaut : aspnetcore-debug.log)
ASPNETCORE_MODULE_DEBUG : Paramètre du niveau de débogage.

Avertissement

Consultez Configuration avec web.config pour obtenir un exemple d’élément aspNetCore dans le fichier web.config.

La configuration du proxy utilise le protocole HTTP et un jeton d’appariement

S’applique uniquement à l’hébergement out-of-process.

Module ASP.NET Core avec une configuration partagée IIS

Le programme d’installation du module ASP.NET Core s’exécute avec les privilèges du compte TrustedInstaller. Comme le compte système local n’a pas l’autorisation de modifier le chemin de partage utilisé par la configuration partagée IIS, le programme d’installation génère une erreur d’accès refusé pendant la tentative de configuration des paramètres du module dans le fichier applicationHost.config du partage.

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

Quand le chemin de la configuration partagée ne se trouve pas sur la même machine que l’installation IIS, effectuez ces étapes :

Désactivez la configuration partagée IIS.
Exécutez le programme d’installation.
Exportez le fichier applicationHost.config mis à jour vers le partage.
Réactivez la configuration partagée IIS.

Version du module et journaux du programme d’installation du bundle d’hébergement

Pour déterminer la version du module ASP.NET Core installé :

Sur le système d’hébergement, accédez à %windir%\System32\inetsrv.
Localisez le fichier aspnetcore.dll.
Cliquez avec le bouton droit sur le fichier, puis sélectionnez Propriétés dans le menu contextuel.
Sélectionnez l'onglet Détails. Le version du fichier et la version du produit représentent la version installée du module.

Les journaux du programme d’installation du bundle d’hébergement du module se trouvent dans C:\\Users\\%UserName%\\AppData\\Local\\Temp. Le fichier est nommé dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log, où l’espace réservé {TIMESTAMP} est le timestamp.

Emplacements des fichiers du module, du schéma et de configuration

Module

IIS (x86/amd64) :

%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll
%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64) :

%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

schéma

IIS

%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml

IIS Express

%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

Configuration

IIS

%windir%\System32\inetsrv\config\applicationHost.config

IIS Express

Visual Studio : {APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe CLI : %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Vous trouverez les fichiers en recherchant aspnetcore dans le fichier applicationHost.config.

Le module ASP.NET Core (ANCM) est un module IIS natif qui se connecte au pipeline IIS pour transférer les demandes web aux applications ASP.NET Core back-end.

Versions de Windows prises en charge :

Windows 7 ou version ultérieure
Windows Server 2008 R2 ou version ultérieure

Le module fonctionne seulement avec Kestrel. Le module n’est pas compatible avec HTTP.sys.

Étant donné que les applications ASP.NET Core s’exécutent dans un processus distinct du processus de travail IIS, le module traite également la gestion des processus. Le module démarre le processus de l’application ASP.NET Core quand la première requête arrive et redémarre l’application si elle plante. Il s’agit essentiellement du même comportement que celui des applications ASP.NET 4.x qui s’exécutent in-process dans IIS et sont gérées par le service WAS (Windows Activation Service).

Le schéma suivant illustre la relation entre IIS, le module ASP.NET Core et une application :

Module ASP.NET Core

Les requêtes arrivent du web au pilote HTTP.sys en mode noyau. Le pilote route les requêtes vers IIS sur le port configuré du site web, généralement 80 (HTTP) ou 443 (HTTPS). Le module réachemine les requêtes vers Kestrel sur un port aléatoire pour l’application, qui n’est pas le port 80 ou le port 443.

Le module spécifie le port via une variable d’environnement au démarrage, et le middleware d’intégration IIS configure le serveur pour qu’il écoute sur http://localhost:{port}. Des vérifications supplémentaires sont effectuées, et les requêtes qui ne proviennent pas du module sont rejetées. Le module ne prend pas en charge le transfert HTTPS : les requêtes sont donc transférées via HTTP, même si IIS les reçoit via HTTPS.

Une fois que Kestrel a récupéré la requête en provenance du module, celle-ci est envoyée (push) vers le pipeline de middleware ASP.NET Core. Le pipeline de middlewares traite la requête et la passe en tant qu’instance de HttpContext à la logique de l’application. Le middleware ajouté par l’intégration d’IIS met à jour le schéma, l’adresse IP distante et la base du chemin pour prendre en compte le réacheminement de la requête vers Kestrel. La réponse de l’application est ensuite repassée à IIS, qui la renvoie au client HTTP à l’origine de la requête.

Le module ASP.NET Core peut également :

Définir des variables d’environnement pour le processus de travail.
Journaliser la sortie de stdout dans un stockage de fichiers pour résoudre les problèmes de démarrage.
Transférer des jetons d’authentification Windows.

Comment installer et utiliser le module ASP.NET Core (ANCM)

Pour obtenir des instructions sur l’installation du module ASP.NET Core, consultez Installer le bundle d’hébergement .NET Core.

Configuration 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>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="dotnet"
                arguments=".\MyApp.dll"
                stdoutLogEnabled="false"
                stdoutLogFile=".\logs\stdout" />
  </system.webServer>
</configuration>

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

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

Pour obtenir des informations sur la configuration de sous-application IIS, consultez Héberger ASP.NET Core sur Windows avec IIS.

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 transmis 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`
`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. 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.	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.	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. Le module tente de relancer le processus lorsqu’il reçoit une nouvelle requête, puis continue d’essayer de redémarrer le processus pour les requêtes 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, les attributs stdout et stderr du 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 d’accès relatif ou absolu pour lequel les attributs 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 spécifiés dans le chemin d’accès doivent exister pour permettre au module de créer le 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 d'accès 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 journaux avec un enregistrement effectué le 05/02/2018 à 19:41:32 et un ID de processus de 1934.	`aspnetcore-stdout`

Définition des variables d'environnement

Avertissement

Les variables d’environnement définies dans cette section sont en conflit avec les variables d’environnement système qui ont le même nom. Si une variable d’environnement est définie à la fois dans le fichier web.config et au niveau du système dans Windows, la valeur provenant du fichier web.config est ajoutée à la valeur de la variable d’environnement système (par exemple, ASPNETCORE_ENVIRONMENT: Development;Development), ce qui empêche le démarrage de l’application.

L’exemple suivant définit deux variables d'environnement. 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’exception de 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="\\?\%home%\LogFiles\stdout">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

Avertissement

app_offline.htm

Page d’erreur de démarrage

Si le module ASP.NET Core ne peut pas lancer le processus backend ou que ce dernier démarre mais ne parvient pas à écouter sur le port configuré, une page de code d’état 502.5 - Échec du processus s’affiche. Pour supprimer cette page et revenir à la page IIS de code d’état 502 par défaut, utilisez l’attribut disableStartUpErrorPage. Pour plus d’informations sur la configuration des messages d’erreur personnalisés, consultez Erreurs HTTP <httpErrors>.

Création et redirection de journal

Aucune rotation n’est appliquée aux journaux, sauf en cas de recyclage/redémarrage du processus. Il incombe à l’hébergeur de limiter l’espace disque utilisé par les journaux.

Un horodatage et une extension de fichier sont ajoutés automatiquement quand le fichier journal est créé. Le nom du fichier journal est créé en ajoutant l’horodatage, un ID de processus et une extension de fichier (.log) au dernier segment du chemin d'accès stdoutLogFile (généralement stdout), séparés par des traits de soulignement. Si le chemin d'accès stdoutLogFile se termine par stdout, un journal pour une application avec un PID de 1934 créé le 5/2/2018 à 19:42:32 affiche le nom de fichier stdout_20180205194132_1934.log.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout">
</aspNetCore>

Pour créer des règles de filtre de journalisation, consultez la section Appliquer des règles de filtre de journal dans le code de la documentation de journalisation ASP.NET Core.

Pour plus d’informations sur les formats de chemin d’accès, consultez Formats de chemin d’accès aux fichiers sur les systèmes Windows.

La configuration du proxy utilise le protocole HTTP et un jeton d’appariement

Module ASP.NET Core avec une configuration partagée IIS

Lorsque vous utilisez une configuration partagée IIS, procédez comme suit :

Désactivez la configuration partagée IIS.
Exécutez le programme d’installation.
Exportez le fichier applicationHost.config mis à jour vers le partage.
Réactivez la configuration partagée IIS.

Version du module et journaux du programme d’installation du bundle d’hébergement

Pour déterminer la version du module ASP.NET Core installé :

Sur le système hôte, accédez à %windir%\System32\inetsrv.
Recherchez le fichier aspnetcore.dll.
Cliquez avec le bouton droit sur le fichier, puis sélectionnez Propriétés dans le menu contextuel.
Sélectionnez l'onglet Détails. Le version du fichier et la version du produit représentent la version installée du module.

Les journaux du programme d’installation du pack d’hébergement du module se trouvent dans C:\Users\%UserName%\AppData\Local\Temp. Le fichier est nommé dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Emplacements des fichiers du module, du schéma et de configuration

Module

IIS (x86/amd64) :

%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll

IIS Express (x86/amd64) :

%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll

schéma

IIS

%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

IIS Express

%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

Configuration

IIS

%windir%\System32\inetsrv\config\applicationHost.config

IIS Express

Visual Studio : {RACINE DE L’APPLICATION}\.vs\config\applicationHost.config
iisexpress.exe CLI : %PROFILUTILISATEUR%\Documents\IISExpress\config\applicationhost.config

Vous trouverez les fichiers en recherchant aspnetcore dans le fichier applicationHost.config.

Ressources supplémentaires

Héberger ASP.NET Core sur Windows avec IIS
Déployer des applications ASP.NET Core sur Azure App Service
Source de référence du module ASP.NET Core [branche par défaut (main)] : utilisez la liste déroulante Branche pour sélectionner une version spécifique (par exemple, release/3.1).
Modules IIS avec ASP.NET Core

Partage via

Module ASP.NET Core (ANCM) pour IIS

Installer le module ASP.NET Core (ANCM)

Modèles d'hébergement

Modèle d’hébergement in-process

Modèle d’hébergement out-of-process

Modifications du modèle d’hébergement

Nom du processus

Comment installer et utiliser le module ASP.NET Core (ANCM)

Configuration avec web.config

Attributs de l’élément aspNetCore

Définir des variables d’environnement

app_offline.htm

Page d’erreur de démarrage

Création et redirection de journal

Journaux de diagnostic améliorés

Modifier la taille de pile

La configuration du proxy utilise le protocole HTTP et un jeton d’appariement

Module ASP.NET Core avec une configuration partagée IIS

Version du module et journaux du programme d’installation du bundle d’hébergement

Emplacements des fichiers du module, du schéma et de configuration

Module

schéma

Configuration

Modèles d'hébergement

Modèle d’hébergement in-process

Modèle d’hébergement out-of-process

Modifications du modèle d’hébergement

Nom du processus

Comment installer et utiliser le module ASP.NET Core (ANCM)

Configuration avec web.config

Attributs de l’élément aspNetCore

Définition des variables d'environnement

app_offline.htm

Page d’erreur de démarrage

Création et redirection de journal

Journaux de diagnostic améliorés

La configuration du proxy utilise le protocole HTTP et un jeton d’appariement

Module ASP.NET Core avec une configuration partagée IIS

Version du module et journaux du programme d’installation du bundle d’hébergement

Emplacements des fichiers du module, du schéma et de configuration

Module

schéma

Configuration

Comment installer et utiliser le module ASP.NET Core (ANCM)

Configuration avec web.config

Attributs de l’élément aspNetCore

Définition des variables d'environnement

app_offline.htm

Page d’erreur de démarrage

Création et redirection de journal

La configuration du proxy utilise le protocole HTTP et un jeton d’appariement

Module ASP.NET Core avec une configuration partagée IIS

Version du module et journaux du programme d’installation du bundle d’hébergement

Emplacements des fichiers du module, du schéma et de configuration

Module

schéma

Configuration

Ressources supplémentaires

Ressources supplémentaires

`app_offline.htm`