ASP.NET Core-Modul (ANCM) für IIS

Das ASP.NET Core-Modul (ANCM) ist ein natives IIS-Modul, das in die IIS-Pipeline integriert wird, wodurch ermöglicht wird, dass ASP.NET Core-Anwendungen mit den Internetinformationsdiensten (IIS) arbeiten können. Für das Ausführen von ASP.NET Core-Apps mit den IIS gibt es zwei Möglichkeiten:

• Hosten einer ASP.NET Core-App innerhalb des IIS-Workerprozesses (w3wp.exe), was als In-Process-Hostingmodell bezeichnet wird.
• Weiterleiten von Webanforderungen an eine Back-End-ASP.NET Core-App, die den Kestrel-Server ausführt, was als Out-of-Process-Hostingmodell bezeichnet wird.

Für jedes der Hostingmodelle müssen Kompromisse eingegangen werden. Standardmäßig wird das In-Process-Hostingmodell verwendet, da die Leistung und Diagnose hier besser sind.

Weitere Informationen und Anleitungen zur Konfiguration finden Sie unter den folgenden Themen:

• Webserverimplementierungen in ASP.NET Core

Installieren des ASP.NET Core-Moduls (ANCM)

Das ASP.NET Core-Modul (ANCM) wird mit der .NET Core-Laufzeit aus dem .NET Core-Hostingpaket installiert. Das ASP.NET Core-Modul ist aufwärts- und abwärtskompatibel mit unterstützten Releases von .NET.

Breaking Changes und Sicherheitsempfehlungen werden im Ankündigungsrepository gemeldet. Ankündigungen können durch Auswahl eines Bezeichnungsfilters auf eine bestimmte Version beschränkt werden.

Laden Sie den Installer über folgenden Link herunter:

Aktueller Installer für das .NET Core Hosting-Paket (direkter Download)

Weitere Informationen, einschließlich zur Installation einer früheren Version des-Moduls, finden Sie unter Hostingpaket.

Ein Tutorial zum Veröffentlichen einer ASP.NET Core-App auf einem IIS-Server finden Sie unter Veröffentlichen einer ASP.NET Core-App in IIS.

Das ASP.NET Core-Modul (ANCM) ist ein natives IIS-Modul, das in die IIS-Pipeline integriert wird, um eine dieser Aktionen auszuführen:

• Hosten einer ASP.NET Core-App innerhalb des IIS-Arbeitsprozesses (w3wp.exe), was als In-Process-Hostingmodell bezeichnet wird.
• Weiterleiten von Webanforderungen an eine Back-End-ASP.NET Core-App, die den Kestrel-Server ausführt, was als Out-of-Process-Hostingmodell bezeichnet wird.

Unterstützte Windows-Versionen:

• Windows 7 oder höher
• Windows Server 2012 R2 oder höher

Beim In-Process-Hosting verwendet das Modul eine In-Process-Server-Implementierung für IIS, die als IIS-HTTP-Server (IISHttpServer) bezeichnet wird.

Beim Out-of-Process-Hosting funktioniert das Modul nur mit Kestrel. Dieses Modul funktioniert nicht mit HTTP.sys.

Hostingmodelle

In-Process-Hostingmodell

ASP.NET Core-Apps verwenden standardmäßig das In-Process-Hostingmodell.

Die folgenden Merkmale treffen für In-Process-Hosting zu:

• Der IIS-HTTP-Server (IISHttpServer) wird anstelle des Kestrel-Servers verwendet. Für In-Process ruft CreateDefaultBuilderUseIIS auf zu:

  • Registrieren des IISHttpServer.
  • Konfigurieren des Ports und des Basispfads, den der Server überwachen soll, wenn er hinter dem ASP.NET Core-Modul ausgeführt wird.
  • Konfigurieren des Hosts zum Erfassen von Startfehlern.

• Das RequestTimeout-Attribut trifft auf In-Process-Hosting nicht zu.

• Das gemeinsame Verwenden eines Anwendungspools durch mehrere Apps wird nicht unterstützt. Verwenden Sie einen Anwendungspool pro App.

• Wenn Web Deploy verwendet oder eine app_offline.htm-Datei manuell in der Bereitstellung platziert wird, wird die App möglicherweise nicht sofort beendet, wenn eine offene Verbindung vorhanden ist. Beispielsweise kann eine WebSocket-Verbindung eine Verzögerung beim Herunterfahren der App bewirken.

• Die Architektur (Bitbreite) der App und der installierten Runtime (x64 oder x86) müssen mit der Architektur des Anwendungspools übereinstimmen.

• Verbindungstrennungen von Clients werden erkannt. Das HttpContext.RequestAborted-Abbruchtoken wird abgebrochen, wenn der Client die Verbindung trennt.

• In ASP.NET Core 2.2.1 oder früher gibt GetCurrentDirectory anstelle des Anwendungsverzeichnisses das Workerverzeichnis des Prozesses zurück, der von den IIS gestartet wurde (z.B. C:\Windows\System32\inetsrv für w3wp.exe).

  Den Beispielcode zum Festlegen des aktuellen App-Verzeichnisses finden Sie unter CurrentDirectoryHelpers-Klasse. Rufen Sie die SetCurrentDirectory-Methode auf. Nachfolgende Aufrufe von GetCurrentDirectory stellen das App-Verzeichnis bereit.

• Beim In-Process-Hosting wird AuthenticateAsync nicht intern aufgerufen, um einen Benutzer zu initialisieren. Deshalb ist eine IClaimsTransformation-Implementierung, die verwendet wird, um Ansprüche nach jeder Authentifizierung zu transformieren, nicht standardmäßig aktiviert. Rufen Sie AddAuthentication auf, um Authentifizierungsdienste hinzuzufügen, wenn Ansprüche mit einer IClaimsTransformation-Implementierung transformiert werden:

  public void ConfigureServices(IServiceCollection services)
  {
      services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
      services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
  }
  
  public void Configure(IApplicationBuilder app)
  {
      app.UseAuthentication();
  }
  

  • Bereitstellungen von Webpaketen (Einzeldateien) werden nicht unterstützt.

Out-of-Process-Hostingmodell

Um eine App für Out-of-Process-Hosting zu konfigurieren, legen Sie den Wert der <AspNetCoreHostingModel>-Eigenschaft in der Projektdatei ( .csproj) auf OutOfProcess fest:

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

Das In-Process-Hosting wird mithilfe von InProcess (Standardwert) festgelegt.

Beim Wert von <AspNetCoreHostingModel> wird die Groß-/Kleinschreibung nicht beachtet, sodass inprocess und outofprocess gültige Werte sind.

Der Kestrel-Server wird anstelle des IIS-HTTP-Servers (IISHttpServer) verwendet.

Bei Out-of-Process ruft CreateDefaultBuilderUseIISIntegration auf, um Folgendes zu tun:

• Konfigurieren des Ports und des Basispfads, den der Server überwachen soll, wenn er hinter dem ASP.NET Core-Modul ausgeführt wird.
• Konfigurieren des Hosts zum Erfassen von Startfehlern.

Änderungen am Hostmodell

Wenn die Einstellung hostingModel in der Datei web.config geändert wird (wird im Abschnitt Konfiguration mit web.config erläutert), verwendet das Modul den Workerprozess für die IIS noch mal.

Bei IIS Express verwendet das Modul den Arbeitsprozess nicht erneut, sondern löst stattdessen ein ordnungsgemäßes Herunterfahren des aktuellen IIS Express-Prozesses aus. Mit der nächsten Anforderung an die App wird ein neuer IIS Express-Prozess erzeugt.

Prozessname

Process.GetCurrentProcess().ProcessName meldet w3wp/iisexpress (In-Process) oder dotnet (Out-of-Process).

Viele native Module, z.B. die Windows-Authentifizierung, bleiben aktiv. Weitere Informationen zu IIS-Modulen, die im ASP.NET Core-Modul aktiv sind, finden Sie unter IIS-Module mit ASP.NET Core.

Das ASP.NET Core-Modul kann außerdem:

• Umgebungsvariablen für den Arbeitsprozess festlegen
• Die stdout-Ausgabe im Dateispeicher protokollieren, um Probleme beim Start zu beheben
• Windows-Authentifizierungstoken weiterleiten

So installieren und verwenden Sie das ASP.NET Core-Modul (ANCM)

Anweisungen zum Installieren des ASP.NET Core-Moduls finden Sie unter Installieren des .NET Core-Hostingpakets. Das ASP.NET Core-Modul ist aufwärts- und abwärtskompatibel mit unterstützten Releases von .NET.

Breaking Changes und Sicherheitsempfehlungen werden im Ankündigungsrepository gemeldet. Ankündigungen können durch Auswahl eines Bezeichnungsfilters auf eine bestimmte Version beschränkt werden.

Konfiguration mit der Datei „web.config“

Das ASP.NET Core-Modul wurde mit dem aspNetCore-Abschnitt des system.webServer-Knotens in der Datei web.config der Site konfiguriert.

Die folgende web.config-Datei wird für eine Framework-abhängige Bereitstellung veröffentlicht und konfiguriert für da sASP.NET Core-Modul die Handhabung von Siteanforderungen:

<?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>

Die folgende web.config-Datei wird für eine eigenständige Bereitstellung veröffentlicht:

<?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>

Die InheritInChildApplications-Eigenschaft wird auf false festgelegt, um anzugeben, dass die im <location>-Element angegebenen Einstellungen nicht von Apps geerbt werden, die in einem Unterverzeichnis der App gespeichert sind.

Wenn eine App für Azure App Service bereitgestellt wird, wird der Pfad stdoutLogFile auf \\?\%home%\LogFiles\stdout gesetzt. Der Pfad speichert stdout-Protokolle zum Ordner LogFiles, einem Speicherort, der automatisch vom Dienst erstellt wird.

Informationen zur IIS-Unteranwendungskonfiguration finden Sie unter Hosten von ASP.NET Core unter Windows mit IIS.

Attribute des aspNetCore-Elements

Festlegen von Umgebungsvariablen

Umgebungsvariablen können für den Prozess im Attribut processPath angegeben werden. Geben Sie eine Umgebungsvariable mit dem untergeordneten Element <environmentVariable> eines <environmentVariables>-Auflistungselements an. In diesem Abschnitt festgelegte Umgebungsvariablen haben Vorrang vor Systemumgebungsvariablen.

Im folgenden Beispiel werden zwei Umgebungsvariablen in web.config festgelegt. ASPNETCORE_ENVIRONMENT konfiguriert die Umgebung der App als Development. Ein Entwickler setzt diesen Wert möglicherweise vorübergehend in der Datei web.config, um das Laden der Seite mit Ausnahmen für Entwickler beim Debugging einer App-Ausnahme zu erzwingen. CONFIG_DIR ist ein Beispiel für eine benutzerdefinierte Umgebungsvariable, wobei der Entwickler Code geschrieben hat, der den Wert beim Start liest, um einen Pfad zum Laden der Konfigurationsdatei der App zu bilden.

<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>

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

app_offline.htm

Wenn eine Datei mit dem Namen app_offline.htm im Stammverzeichnis einer App erkannt wird, versucht das ASP.NET Core-Modul, die App ordnungsgemäß zu beenden und die Verarbeitung eingehender Anforderungen zu stoppen. Wenn die App nach der Anzahl von Sekunden, die in shutdownTimeLimit definiert wurden, noch ausgeführt wird, beendet das ASP.NET Core-Modul den laufenden Prozess.

Wenn die Datei app_offline.htm vorhanden ist, reagiert das ASP.NET Core-Modul auf Anforderungen, indem es den Inhalt der app_offline.htm-Datei zurücksendet. Wenn die Datei app_offline.htm entfernt wurde, wird die App von der nächsten Anforderung gestartet.

Beim Verwenden des Out-of-Process-Hostingmodells wird die App möglicherweise nicht sofort heruntergefahren, wenn eine offene Verbindung besteht. Beispielsweise kann eine WebSocket-Verbindung eine Verzögerung beim Herunterfahren der App bewirken.

Startfehler-Seite

Sowohl In-Process- als auch Out-of-Process-Hosting erzeugen benutzerdefinierte Fehlerseiten, wenn die App nicht gestartet werden kann.

Wenn das ASP.NET Core-Modul weder den In-Process- noch den Out-of-Process-Anforderungshandler finden kann, wird die Statuscodeseite 500.0: Fehler beim Laden des In-Process-/Out-Of-Process-Handlers angezeigt.

Wenn das ASP.NET Core-Modul beim In-Process-Hosting die App nicht starten kann, wird die Statuscodeseite 500.30: Fehler beim Starten angezeigt.

Wenn das ASP.NET Core-Modul beim Out-of-Process-Hosting den Back-End-Prozess nicht starten kann oder der Back-End-Prozess gestartet wird, aber nicht am konfigurierten Port lauscht, wird die Statuscodeseite 502.5: Prozessfehler angezeigt.

Um diese Seite zu unterdrücken und zur standardmäßigen IIS-5xx-Statuscodeseite zurückzukehren, verwenden Sie das Attribut disableStartUpErrorPage. Weitere Informationen zum Konfigurieren von benutzerdefinierten Fehlermeldungen finden Sie unter HTTP-Fehler <httpErrors>.

Protokollerstellung und Weiterleitung

Das ASP.NET Core-Modul leitet die Konsolenausgabe „stdout“ und „stderr“ auf den Datenträger weiter, wenn die Attribute stdoutLogEnabled und stdoutLogFile des aspNetCore-Elements festgelegt werden. Ordner, die im stdoutLogFile-Pfad angegeben werden, werden vom Modul erstellt, wenn die Protokolldatei erstellt wird. Der App-Pool muss über Schreibzugriff auf den Speicherort verfügen, an dem die Protokolle geschrieben werden (verwenden Sie IIS AppPool\<app_pool_name>, um die Schreibberechtigung bereitzustellen).

Protokolle werden nur dann rotiert, wenn die Prozesswiederverwendung/der Prozessneustart stattfindet. Der Hoster ist für die Begrenzung des Speicherplatzes zuständig, den die Protokolle nutzen.

Die Verwendung des stdout-Protokolls wird nur für die Problembehandlung bei App-Startproblemen beim Hosten in IIS oder beim Verwenden von Support zum Zeitpunkt der Entwicklung für IIS in Visual Studio empfohlen, nicht aber für das lokale Debuggen und das Ausführen der App mit IIS Express.

Verwenden Sie das Protokoll „stdout“ nicht zu allgemeinen App-Protokollierungszwecken. Verwenden Sie für die routinemäßige Protokollierung in einer ASP.NET Core-App eine Protokollierungsbibliothek, die die Protokolldateigröße beschränkt und die Protokolle rotiert. Weitere Informationen finden Sie im Artikel zur Protokollierung von Drittanbietern.

Ein Zeitstempel und eine Dateierweiterung werden automatisch hinzugefügt, wenn die Protokolldatei erstellt wird. Ein Protokolldateiname wird erstellt, indem der Zeitstempel, die Prozess-ID und die Dateierweiterung ( .log) an das letzte Segment des stdoutLogFile-Pfads (in der Regel stdout), getrennt durch Unterstriche, angehängt werden. Wenn der stdoutLogFile-Pfad mit stdout endet, hat ein Protokoll für eine App mit der PID 1934, erstellt am 2.5.2018 um 19:42:32, den Dateinamen stdout_20180205194132_1934.log.

Wenn stdoutLogEnabled „false“ ist, werden Fehler beim App-Start erfasst und in das Ereignisprotokoll mit bis zu 30 KB ausgegeben. Nach dem Start werden alle zusätzlichen Protokolle verworfen.

Das folgende Beispielelement aspNetCore konfiguriert die stdout-Protokollierung im relativen .\log\-Pfad. Vergewissern Sie sich, dass die Identität der AppPool-Benutzerin bzw. des AppPool-Benutzers über die Berechtigung zum Schreiben in den angegebenen Pfad verfügt.

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

Beim Veröffentlichen einer App für die Azure App Service-Bereitstellung legt das Web SDK den Wert stdoutLogFile auf \\?\%home%\LogFiles\stdout fest. Die Umgebungsvariable %home ist für Apps vordefiniert, die von Azure App Service gehostet werden.

Informationen zum Erstellen von Protokollierungsfilterregeln finden Sie in dem Abschnitt Protokollfilterregeln in Code verwenden der Dokumentation zur ASP.NET Core-Protokollierung.

Weitere Informationen zu Pfadformaten finden Sie unter Formate von Dateipfaden unter Windows-Systemen.

Erweiterte Diagnoseprotokolle

Das ASP.NET Core-Modul kann so konfiguriert werden, dass es erweiterte Diagnoseprotokolle bereitstellt. Fügen Sie das Element <handlerSettings> zum Element <aspNetCore> in web.config hinzu. Wenn debugLevel auf TRACE festgelegt wird, werden genauere Diagnoseinformationen zur Verfügung gestellt:

<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>

Ordner, die im Pfad angegeben werden (logs im vorherigen Beispiel), werden vom Modul erstellt, wenn die Protokolldatei erstellt wird. Der App-Pool muss über Schreibzugriff auf den Speicherort verfügen, in den die Protokolle geschrieben werden (verwenden Sie IIS AppPool\{APP POOL NAME}, um die Schreibberechtigung bereitzustellen, wenn der Platzhalter {APP POOL NAME} der App-Poolname ist).

debugLevel-Werte können sowohl die Ebene als auch den Speicherort enthalten.

Ebenen (von der geringsten zur höchsten Genauigkeit):

• ERROR
• WARNING
• INFO
• TRACE

Speicherorte (mehrere Speicherorte sind zulässig):

• CONSOLE
• EVENTLOG
• DATEI

Die Handlereinstellungen können auch über Umgebungsvariablen angegeben werden:

• ASPNETCORE_MODULE_DEBUG_FILE: Dies ist der Pfad zur Debugprotokolldatei. (Standard: aspnetcore-debug.log)
• ASPNETCORE_MODULE_DEBUG: Dies ist die Einstellung der Debugebene.

Konfiguration mit der Datei „web.config“ enthält ein Beispiel für das aspNetCore-Element in der Datei web.config.

Ändern der Stapelgröße

Gilt nur bei Verwendung des In-Process-Hostingmodells.

Konfigurieren Sie die Größe des verwalteten Stapels mithilfe der stackSize-Einstellung in Byte in web.config. Die Standardgröße beträgt 1.048.576 Byte (1 MB).

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

Die Proxykonfiguration verwendet das HTTP-Protokoll und ein Paarbildungstoken

Gilt nur für Out-of-Process-Hosting.

Der Proxy, der zwischen dem ASP.NET Core-Modul und Kestrel erstellt wurde, verwendet das HTTP-Protokoll. Es gibt kein Risiko für Lauschangriffe auf den Datenverkehr zwischen dem Modul und Kestrel von einem Speicherort außerhalb des Servers.

Ein Paarbildungstoken wird verwendet, um sicherzustellen, dass die von Kestrel empfangenen Anfragen von IIS über einen Proxy gesendet wurden und nicht von einer anderen Quelle stammen. Das Paarbildungstoken wurde durch das Modul erstellt und in einer Umgebungsvariablen (ASPNETCORE_TOKEN) festgelegt. Das Paarbildungstoken ist auch bei jeder Proxyanforderung in einem Header (MS-ASPNETCORE-TOKEN) festgelegt. IIS-Middleware überprüft jede erhaltene Anforderung, um sicherzustellen, dass der Headerwert des Paarbildungstokens dem Wert der Umgebungsvariablen entspricht. Wenn die Tokenwerte nicht übereinstimmen, wird die Anforderung protokolliert und abgelehnt. Es kann nicht von einem Speicherort außerhalb des Servers auf die Umgebungsvariablen des Paarbildungstokens und den Datenverkehr zwischen dem Modul und Kestrel zugegriffen werden. Wenn Cyberkriminelle den Wert des Paarbildungstokens nicht kennen, können sie keine Anforderungen einreichen, die die IIS-Middleware-Prüfung umgehen.

ASP.NET Core-Modul mit einer IIS-Freigabekonfiguration

Das Installationsprogramm des ASP.NET Core-Moduls wird mit den Berechtigungen des TrustedInstaller-Kontos ausgeführt. Da das lokale Systemkonto keine Berechtigung zum Ändern für den von der IIS-Freigabekonfiguration verwendeten Freigabepfad hat, stößt der Installer beim Versuch, die Moduleinstellungen in der applicationHost.config-Datei auf der Freigabe zu konfigurieren, auf einen „Zugriff verweigert“-Fehler.

Wenn eine ISS-Freigabekonfiguration auf demselben Computer verwendet wird wie die ISS-Installation, führen Sie das Installationsprogramm des ASP.NET -Core-Hosting-Pakets mit auf 1 festgelegtem Parameter OPT_NO_SHARED_CONFIG_CHECK aus:

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

Wenn sich der Pfad zur freigegebenen Konfiguration nicht auf demselben Computer wie die ISS-Installation befindet, befolgen Sie die folgenden Schritte:

1. Deaktivieren Sie die IIS-Freigabekonfiguration.
2. Führen Sie den Installer aus.
3. Exportieren Sie die aktualisierte Datei applicationHost.config auf die Freigabe.
4. Aktivieren Sie die IIS-Freigabekonfiguration erneut.

Version des Moduls und Installerprotokolle des Hostingpakets

So ermitteln Sie die Version des installierten ASP.NET Core-Moduls:

1. Navigieren Sie auf dem Hostsystem zu %windir%\System32\inetsrv.
2. Suchen Sie die Datei aspnetcore.dll.
3. Klicken Sie mit der rechten Maustaste auf die Datei, und wählen Sie im Dropdownmenü die Option Eigenschaften aus.
4. Wählen Sie die Registerkarte Details aus. Die Dateiversion und die Produktversion stellen die installierte Version des Moduls dar.

Die Installationsprotokolle des Hostingbundles für das Modul finden Sie unter C:\Users\%UserName%\AppData\Local\Temp. Die Datei heißt dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log.

Dateispeicherorte für Modul, Schema und Konfiguration

Modul

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

Schema

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

Konfiguration

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

Den Speicherort dieser Dateien finden Sie, indem Sie aspnetcore in der Datei applicationHost.config suchen.

Das ASP.NET Core-Modul (ANCM) ist ein natives IIS-Modul, das in die IIS-Pipeline integriert wird, um eine dieser Aktionen auszuführen:

• Hosten einer ASP.NET Core-App innerhalb des IIS-Arbeitsprozesses (w3wp.exe), was als In-Process-Hostingmodell bezeichnet wird.
• Weiterleiten von Webanforderungen an eine Back-End-ASP.NET Core-App, die den Kestrel-Server ausführt, was als Out-of-Process-Hostingmodell bezeichnet wird.

Unterstützte Windows-Versionen:

• Windows 7 oder höher
• Windows Server 2008 R2 oder höher

Beim In-Process-Hosting verwendet das Modul eine In-Process-Server-Implementierung für IIS, die als IIS-HTTP-Server (IISHttpServer) bezeichnet wird.

Beim Out-of-Process-Hosting funktioniert das Modul nur mit Kestrel. Dieses Modul funktioniert nicht mit HTTP.sys.

Hostingmodelle

In-Process-Hostingmodell

Um eine App für In-Process-Hosting zu konfigurieren, fügen Sie der Projektdatei der App die Eigenschaft <AspNetCoreHostingModel> mit dem Wert InProcess hinzu (Out-of-Process-Hosting wird mit OutOfProcess festgelegt):

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

Das In-Process-Hostingmodell wird nicht für ASP.NET Core-Apps unterstützt, die auf .NET Framework abzielen.

Beim Wert von <AspNetCoreHostingModel> wird die Groß-/Kleinschreibung nicht beachtet, sodass inprocess und outofprocess gültige Werte sind.

Ist die <AspNetCoreHostingModel>-Eigenschaft nicht in der Datei vorhanden, ist OutOfProcess der Standardwert.

Die folgenden Merkmale treffen für In-Process-Hosting zu:

• Der IIS-HTTP-Server (IISHttpServer) wird anstelle des Kestrel-Servers verwendet. Für In-Process ruft CreateDefaultBuilderUseIIS auf zu:

  • Registrieren des IISHttpServer.
  • Konfigurieren des Ports und des Basispfads, den der Server überwachen soll, wenn er hinter dem ASP.NET Core-Modul ausgeführt wird.
  • Konfigurieren des Hosts zum Erfassen von Startfehlern.

• Das RequestTimeout-Attribut trifft auf In-Process-Hosting nicht zu.

• Das gemeinsame Verwenden eines Anwendungspools durch mehrere Apps wird nicht unterstützt. Verwenden Sie einen Anwendungspool pro App.

• Wenn Web Deploy verwendet oder eine app_offline.htm-Datei manuell in der Bereitstellung platziert wird, wird die App möglicherweise nicht sofort beendet, wenn eine offene Verbindung vorhanden ist. Beispielsweise kann eine Websocketverbindung eine Verzögerung beim Herunterfahren der App bewirken.

• Die Architektur (Bitbreite) der App und der installierten Runtime (x64 oder x86) müssen mit der Architektur des Anwendungspools übereinstimmen.

• Verbindungstrennungen von Clients werden erkannt. Das Abbruchtoken HttpContext.RequestAborted wird abgebrochen, wenn die Verbindung mit dem Client getrennt wird.

• In ASP.NET Core 2.2.1 oder früher gibt GetCurrentDirectory anstelle des Anwendungsverzeichnisses das Workerverzeichnis des Prozesses zurück, der von den IIS gestartet wurde (z.B. C:\Windows\System32\inetsrv für w3wp.exe).

  Den Beispielcode zum Festlegen des aktuellen App-Verzeichnisses finden Sie in der Klasse CurrentDirectoryHelpers. Rufen Sie die SetCurrentDirectory-Methode auf. Nachfolgende Aufrufe von GetCurrentDirectory stellen das App-Verzeichnis bereit.

• Beim In-Process-Hosting wird AuthenticateAsync nicht intern aufgerufen, um einen Benutzer zu initialisieren. Deshalb ist eine IClaimsTransformation-Implementierung, die verwendet wird, um Ansprüche nach jeder Authentifizierung zu transformieren, nicht standardmäßig aktiviert. Rufen Sie AddAuthentication auf, um Authentifizierungsdienste hinzuzufügen, wenn Ansprüche mit einer IClaimsTransformation-Implementierung transformiert werden:

  public void ConfigureServices(IServiceCollection services)
  {
      services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
      services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
  }
  
  public void Configure(IApplicationBuilder app)
  {
      app.UseAuthentication();
  }
  

Out-of-Process-Hostingmodell

Um eine App für Out-of-Process-Hosting zu konfigurieren, konfigurieren Sie die Projektdatei auf eine der folgenden Weisen:

• Geben Sie die <AspNetCoreHostingModel>-Eigenschaft nicht an. Ist die <AspNetCoreHostingModel>-Eigenschaft nicht in der Datei vorhanden, ist OutOfProcess der Standardwert.
• Legen Sie den Wert der <AspNetCoreHostingModel>-Eigenschaft auf OutOfProcess fest (In-Process-Hosting wird mit InProcess festgelegt):

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

Beim Wert wird die Groß-/Kleinschreibung nicht beachtet, sodass inprocess und outofprocess gültige Werte sind.

Der Kestrel-Server wird anstelle des IIS-HTTP-Servers (IISHttpServer) verwendet.

Für Out-of-Process ruft CreateDefaultBuilderUseIISIntegration auf zu:

• Konfigurieren des Ports und des Basispfads, den der Server überwachen soll, wenn er hinter dem ASP.NET Core-Modul ausgeführt wird.
• Konfigurieren des Hosts zum Erfassen von Startfehlern.

Änderungen am Hostmodell

Wenn die Einstellung hostingModel in der Datei web.config geändert wird (im Abschnitt Konfiguration mit web.config erläutert), verwendet das Modul den Arbeitsprozess von IIS erneut.

Bei IIS Express verwendet das Modul den Arbeitsprozess nicht erneut, sondern löst stattdessen ein ordnungsgemäßes Herunterfahren des aktuellen IIS Express-Prozesses aus. Mit der nächsten Anforderung an die App wird ein neuer IIS Express-Prozess erzeugt.

Prozessname

Process.GetCurrentProcess().ProcessName meldet w3wp/iisexpress (In-Process) oder dotnet (Out-of-Process).

Viele native Module, z.B. die Windows-Authentifizierung, bleiben aktiv. Weitere Informationen zu IIS-Modulen, die im ASP.NET Core-Modul aktiv sind, finden Sie unter IIS-Module mit ASP.NET Core.

Das ASP.NET Core-Modul kann außerdem:

• Umgebungsvariablen für den Arbeitsprozess festlegen
• Die stdout-Ausgabe im Dateispeicher protokollieren, um Probleme beim Start zu beheben
• Windows-Authentifizierungstoken weiterleiten

So installieren und verwenden Sie das ASP.NET Core-Modul (ANCM)

Anweisungen zum Installieren des ASP.NET Core-Moduls finden Sie unter Installieren des .NET Core-Hostingpakets. Das ASP.NET Core-Modul ist aufwärts- und abwärtskompatibel mit unterstützten Releases von .NET.

Breaking Changes und Sicherheitsempfehlungen werden im Ankündigungsrepository gemeldet. Ankündigungen können durch Auswahl eines Bezeichnungsfilters auf eine bestimmte Version beschränkt werden.

Konfiguration mit der Datei „web.config“

Das ASP.NET Core-Modul wurde mit dem aspNetCore-Abschnitt des system.webServer-Knotens in der Datei web.config der Site konfiguriert.

Die folgende web.config-Datei wird für eine Framework-abhängige Bereitstellung veröffentlicht und konfiguriert für da sASP.NET Core-Modul die Handhabung von Siteanforderungen:

<?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>

Die folgende web.config-Datei wird für eine eigenständige Bereitstellung veröffentlicht:

<?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>

Die InheritInChildApplications-Eigenschaft wird auf false festgelegt, um anzugeben, dass die im <location>-Element angegebenen Einstellungen nicht von Apps geerbt werden, die in einem Unterverzeichnis der App gespeichert sind.

Wenn eine App für Azure App Service bereitgestellt wird, wird der Pfad stdoutLogFile auf \\?\%home%\LogFiles\stdout gesetzt. Der Pfad speichert stdout-Protokolle zum Ordner LogFiles, einem Speicherort, der automatisch vom Dienst erstellt wird.

Informationen zur IIS-Unteranwendungskonfiguration finden Sie unter Hosten von ASP.NET Core unter Windows mit IIS.

Attribute des aspNetCore-Elements

Festlegen von Umgebungsvariablen

Umgebungsvariablen können für den Prozess im Attribut processPath angegeben werden. Geben Sie eine Umgebungsvariable mit dem untergeordneten Element <environmentVariable> eines <environmentVariables>-Auflistungselements an. In diesem Abschnitt festgelegte Umgebungsvariablen haben Vorrang vor Systemumgebungsvariablen.

Im folgenden Beispiel werden zwei Umgebungsvariablen festgelegt. ASPNETCORE_ENVIRONMENT konfiguriert die Umgebung der App als Development. Ein Entwickler setzt diesen Wert möglicherweise vorübergehend in der Datei web.config, um das Laden der Seite mit Ausnahmen für Entwickler beim Debugging einer App-Ausnahme zu erzwingen. CONFIG_DIR ist ein Beispiel für eine benutzerdefinierte Umgebungsvariable, wobei der Entwickler Code geschrieben hat, der den Wert beim Start liest, um einen Pfad zum Laden der Konfigurationsdatei der App zu bilden.

<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>

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

app_offline.htm

Wenn eine Datei mit dem Namen app_offline.htm im Stammverzeichnis einer App erkannt wird, versucht das ASP.NET Core-Modul, die App ordnungsgemäß zu beenden und die Verarbeitung eingehender Anforderungen zu stoppen. Wenn die App nach der Anzahl von Sekunden, die in shutdownTimeLimit definiert wurden, noch ausgeführt wird, beendet das ASP.NET Core-Modul den laufenden Prozess.

Wenn die Datei app_offline.htm vorhanden ist, reagiert das ASP.NET Core-Modul auf Anforderungen, indem es den Inhalt der app_offline.htm-Datei zurücksendet. Wenn die Datei app_offline.htm entfernt wurde, wird die App von der nächsten Anforderung gestartet.

Beim Verwenden des Out-of-Process-Hostingmodells wird die App möglicherweise nicht sofort heruntergefahren, wenn eine offene Verbindung besteht. Beispielsweise kann eine Websocketverbindung eine Verzögerung beim Herunterfahren der App bewirken.

Startfehler-Seite

Sowohl In-Process- als auch Out-of-Process-Hosting erzeugen benutzerdefinierte Fehlerseiten, wenn die App nicht gestartet werden kann.

Wenn das ASP.NET Core-Modul weder den In-Process- noch den Out-of-Process-Anforderungshandler finden kann, wird die Statuscodeseite 500.0: Fehler beim Laden des In-Process-/Out-Of-Process-Handlers angezeigt.

Wenn das ASP.NET Core-Modul beim In-Process-Hosting die App nicht starten kann, wird die Statuscodeseite 500.30: Fehler beim Starten angezeigt.

Wenn das ASP.NET Core-Modul beim Out-of-Process-Hosting den Back-End-Prozess nicht starten kann oder der Back-End-Prozess gestartet wird, aber nicht am konfigurierten Port lauscht, wird die Statuscodeseite 502.5: Prozessfehler angezeigt.

Um diese Seite zu unterdrücken und zur standardmäßigen IIS-5xx-Statuscodeseite zurückzukehren, verwenden Sie das Attribut disableStartUpErrorPage. Weitere Informationen zum Konfigurieren von benutzerdefinierten Fehlermeldungen finden Sie unter HTTP-Fehler <httpErrors>.

Protokollerstellung und Weiterleitung

Das ASP.NET Core-Modul leitet die Konsolenausgabe „stdout“ und „stderr“ auf den Datenträger weiter, wenn die Attribute stdoutLogEnabled und stdoutLogFile des aspNetCore-Elements festgelegt werden. Ordner, die im stdoutLogFile-Pfad angegeben werden, werden vom Modul erstellt, wenn die Protokolldatei erstellt wird. Der App-Pool muss über Schreibzugriff auf den Speicherort verfügen, in den die Protokolle geschrieben werden (verwenden Sie IIS AppPool\{APP POOL NAME}, um die Schreibberechtigung bereitzustellen, wenn der Platzhalter {APP POOL NAME} der App-Poolname ist).

Protokolle werden nur dann rotiert, wenn die Prozesswiederverwendung/der Prozessneustart stattfindet. Der Hoster ist für die Begrenzung des Speicherplatzes zuständig, den die Protokolle nutzen.

Die Verwendung des stdout-Protokolls wird nur für die Problembehandlung bei App-Startproblemen beim Hosten in IIS oder beim Verwenden von Support zum Zeitpunkt der Entwicklung für IIS in Visual Studio empfohlen, nicht aber für das lokale Debuggen und das Ausführen der App mit IIS Express.

Verwenden Sie das Protokoll „stdout“ nicht zu allgemeinen App-Protokollierungszwecken. Verwenden Sie für die routinemäßige Protokollierung in einer ASP.NET Core-App eine Protokollierungsbibliothek, die die Protokolldateigröße beschränkt und die Protokolle rotiert. Weitere Informationen finden Sie im Artikel zur Protokollierung von Drittanbietern.

Ein Zeitstempel und eine Dateierweiterung werden automatisch hinzugefügt, wenn die Protokolldatei erstellt wird. Ein Protokolldateiname wird erstellt, indem der Zeitstempel, die Prozess-ID und die Dateierweiterung ( .log) an das letzte Segment des stdoutLogFile-Pfads (in der Regel stdout), getrennt durch Unterstriche, angehängt werden. Wenn der stdoutLogFile-Pfad mit stdout endet, hat ein Protokoll für eine App mit der PID 1934, erstellt am 2.5.2018 um 19:42:32, den Dateinamen stdout_20180205194132_1934.log.

Wenn stdoutLogEnabled „false“ ist, werden Fehler beim App-Start erfasst und in das Ereignisprotokoll mit bis zu 30 KB ausgegeben. Nach dem Start werden alle zusätzlichen Protokolle verworfen.

Das folgende Beispielelement aspNetCore konfiguriert die stdout-Protokollierung im relativen .\log\-Pfad. Vergewissern Sie sich, dass die Identität der AppPool-Benutzerin bzw. des AppPool-Benutzers über die Berechtigung zum Schreiben in den angegebenen Pfad verfügt.

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

Beim Veröffentlichen einer App für die Azure App Service-Bereitstellung legt das Web SDK den Wert stdoutLogFile auf \\?\%home%\LogFiles\stdout fest. Die Umgebungsvariable %home ist für Apps vordefiniert, die von Azure App Service gehostet werden.

Weitere Informationen zu Pfadformaten finden Sie unter Formate von Dateipfaden unter Windows-Systemen.

Erweiterte Diagnoseprotokolle

Das ASP.NET Core-Modul kann so konfiguriert werden, dass es erweiterte Diagnoseprotokolle bereitstellt. Fügen Sie das Element <handlerSettings> zum Element <aspNetCore> in web.config hinzu. Wenn debugLevel auf TRACE festgelegt wird, werden genauere Diagnoseinformationen zur Verfügung gestellt:

<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>

Ordner im Pfad, die für den <handlerSetting>-Wert (logs im vorherigen Beispiel) bereitgestellt werden, werden nicht automatisch vom Modul erstellt und müssen bereits in der Bereitstellung vorhanden sein. Der App-Pool muss über Schreibzugriff auf den Speicherort verfügen, in den die Protokolle geschrieben werden (verwenden Sie IIS AppPool\{APP POOL NAME}, um die Schreibberechtigung bereitzustellen, wenn der Platzhalter {APP POOL NAME} der App-Poolname ist).

debugLevel-Werte können sowohl die Ebene als auch den Speicherort enthalten.

Ebenen (von der geringsten zur höchsten Genauigkeit):

• ERROR
• WARNING
• INFO
• TRACE

Speicherorte (mehrere Speicherorte sind zulässig):

• CONSOLE
• EVENTLOG
• DATEI

Die Handlereinstellungen können auch über Umgebungsvariablen angegeben werden:

• ASPNETCORE_MODULE_DEBUG_FILE: Dies ist der Pfad zur Debugprotokolldatei. (Standard: aspnetcore-debug.log)
• ASPNETCORE_MODULE_DEBUG: Dies ist die Einstellung der Debugebene.

Konfiguration mit der Datei „web.config“ enthält ein Beispiel für das aspNetCore-Element in der Datei web.config.

Die Proxykonfiguration verwendet das HTTP-Protokoll und ein Paarbildungstoken

Gilt nur für Out-of-Process-Hosting.

Der Proxy, der zwischen dem ASP.NET Core-Modul und Kestrel erstellt wurde, verwendet das HTTP-Protokoll. Es gibt kein Risiko für Lauschangriffe auf den Datenverkehr zwischen dem Modul und Kestrel von einem Speicherort außerhalb des Servers.

Ein Paarbildungstoken wird verwendet, um sicherzustellen, dass die von Kestrel empfangenen Anfragen von IIS über einen Proxy gesendet wurden und nicht von einer anderen Quelle stammen. Das Paarbildungstoken wurde durch das Modul erstellt und in einer Umgebungsvariablen (ASPNETCORE_TOKEN) festgelegt. Das Paarbildungstoken ist auch bei jeder Proxyanforderung in einem Header (MS-ASPNETCORE-TOKEN) festgelegt. IIS-Middleware überprüft jede erhaltene Anforderung, um sicherzustellen, dass der Headerwert des Paarbildungstokens dem Wert der Umgebungsvariablen entspricht. Wenn die Tokenwerte nicht übereinstimmen, wird die Anforderung protokolliert und abgelehnt. Es kann nicht von einem Speicherort außerhalb des Servers auf die Umgebungsvariablen des Paarbildungstokens und den Datenverkehr zwischen dem Modul und Kestrel zugegriffen werden. Wenn Cyberkriminelle den Wert des Paarbildungstokens nicht kennen, können sie keine Anforderungen einreichen, die die IIS-Middleware-Prüfung umgehen.

ASP.NET Core-Modul mit einer IIS-Freigabekonfiguration

Das Installationsprogramm des ASP.NET Core-Moduls wird mit den Berechtigungen des TrustedInstaller-Kontos ausgeführt. Da das lokale Systemkonto keine Berechtigung zum Ändern für den von der IIS-Freigabekonfiguration verwendeten Freigabepfad hat, stößt der Installer beim Versuch, die Moduleinstellungen in der applicationHost.config-Datei auf der Freigabe zu konfigurieren, auf einen „Zugriff verweigert“-Fehler.

Wenn eine ISS-Freigabekonfiguration auf demselben Computer verwendet wird wie die ISS-Installation, führen Sie das Installationsprogramm des ASP.NET -Core-Hosting-Pakets mit auf 1 festgelegtem Parameter OPT_NO_SHARED_CONFIG_CHECK aus:

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

Wenn sich der Pfad zur freigegebenen Konfiguration nicht auf demselben Computer wie die ISS-Installation befindet, befolgen Sie die folgenden Schritte:

1. Deaktivieren Sie die IIS-Freigabekonfiguration.
2. Führen Sie den Installer aus.
3. Exportieren Sie die aktualisierte Datei applicationHost.config auf die Freigabe.
4. Aktivieren Sie die IIS-Freigabekonfiguration erneut.

Version des Moduls und Installerprotokolle des Hostingpakets

So ermitteln Sie die Version des installierten ASP.NET Core-Moduls:

1. Navigieren Sie auf dem Hostsystem zu %windir%\System32\inetsrv.
2. Suchen Sie die Datei aspnetcore.dll.
3. Klicken Sie mit der rechten Maustaste auf die Datei, und wählen Sie im Dropdownmenü die Option Eigenschaften aus.
4. Wählen Sie die Registerkarte Details aus. Die Dateiversion und die Produktversion stellen die installierte Version des Moduls dar.

Die Installationsprotokolle des Hostingbundles für das Modul finden Sie unter C:\\Users\\%UserName%\\AppData\\Local\\Temp. Die Datei hat den Namen dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log, wobei der Platzhalter {TIMESTAMP} der Zeitstempel ist.

Dateispeicherorte für Modul, Schema und Konfiguration

Modul

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

Schema

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

Konfiguration

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

Den Speicherort dieser Dateien finden Sie, indem Sie aspnetcore in der Datei applicationHost.config suchen.

Das ASP.NET Core-Modul (ANCM) ist ein natives IIS-Modul, das in die IIS-Pipeline integriert wird, um Webanforderungen an ASP.NET Core-Back-End-Apps weiterzuleiten.

Unterstützte Windows-Versionen:

• Windows 7 oder höher
• Windows Server 2008 R2 oder höher

Das Modul funktioniert nur mit Kestrel. Das Modul ist nicht mit HTTP.sys kompatibel.

Da ASP.NET Core-Apps in einem Prozess getrennt vom IIS-Arbeitsprozess ausgeführt werden, führt das Modul auch Prozessverwaltung durch. Das Modul startet den Prozess für die ASP.NET Core-App, wenn die erste Anforderung eingeht und startet die App neu, wenn sie abstürzt. Dies ist im Prinzip das gleiche Verhalten wie bei ASP.NET 4.x-Apps, die prozessintern in IIS ausgeführt und durch Windows Activation Service (WAS) verwaltet werden.

Das folgende Diagramm zeigt die Beziehung zwischen IIS, dem ASP.NET Core-Modul und einer App:

Anforderungen gehen aus dem Internet an den Treiber „HTTP.sys“ ein, der im Kernelmodus betrieben wird. Der Treiber leitet die Anforderungen an IIS auf dem konfigurierten Port der Webseite weiter, normalerweise 80 (HTTP) oder 443 (HTTPS). Das Modul leitet die Anforderung über einen zufälligen Port für die App an Kestrel weiter, bei dem es sich nicht um Port 80 oder 443 handelt.

Das Modul gibt den Port über die Umgebungsvariable beim Start an. Die Middleware für die Integration von IIS konfiguriert den Server so, dass er auf http://localhost:{port} lauscht. Zusätzliche Überprüfungen werden durchgeführt. Anforderungen, die nicht vom Modul stammen, werden abgelehnt. Das Modul unterstützt die HTTPS-Weiterleitung nicht. Deshalb werden Anforderungen über HTTP weitergeleitet, selbst wenn sie von IIS über HTTPS empfangen wurden.

Nachdem Kestrel die Anforderung vom Modul empfangen hat, wird die Anforderung per Push an die Middlewarepipeline von ASP.NET Core weitergeleitet. Die Middleware-Pipeline behandelt die Anforderung und gibt sie als HttpContext-Instanz an die App-Logik weiter. Die durch die IIS-Integration hinzugefügte Middleware aktualisiert das Schema, die Remote-IP und die Pfadbasis, um die Anforderung an Kestrel weiterzuleiten. Die Antwort der App wird dann an IIS zurückgegeben, wo sie per Push an den HTTP-Client zurückgegeben wird, der die Anforderung initiiert hat.

Viele native Module, z.B. die Windows-Authentifizierung, bleiben aktiv. Weitere Informationen zu IIS-Modulen, die im ASP.NET Core-Modul aktiv sind, finden Sie unter IIS-Module mit ASP.NET Core.

Das ASP.NET Core-Modul kann außerdem:

• Umgebungsvariablen für den Arbeitsprozess festlegen
• Die stdout-Ausgabe im Dateispeicher protokollieren, um Probleme beim Start zu beheben
• Windows-Authentifizierungstoken weiterleiten

So installieren und verwenden Sie das ASP.NET Core-Modul (ANCM)

Anweisungen zum Installieren des ASP.NET Core-Moduls finden Sie unter Installieren des .NET Core-Hostingpakets.

Konfiguration mit der Datei „web.config“

Das ASP.NET Core-Modul wurde mit dem aspNetCore-Abschnitt des system.webServer-Knotens in der Datei web.config der Site konfiguriert.

Die folgende web.config-Datei wird für eine Framework-abhängige Bereitstellung veröffentlicht und konfiguriert für da sASP.NET Core-Modul die Handhabung von Siteanforderungen:

<?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>

Die folgende web.config-Datei wird für eine eigenständige Bereitstellung veröffentlicht:

<?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>

Wenn eine App für Azure App Service bereitgestellt wird, wird der Pfad stdoutLogFile auf \\?\%home%\LogFiles\stdout gesetzt. Der Pfad speichert stdout-Protokolle zum Ordner LogFiles, einem Speicherort, der automatisch vom Dienst erstellt wird.

Informationen zur IIS-Unteranwendungskonfiguration finden Sie unter Hosten von ASP.NET Core unter Windows mit IIS.

Attribute des aspNetCore-Elements

Festlegen von Umgebungsvariablen

Umgebungsvariablen können für den Prozess im Attribut processPath angegeben werden. Geben Sie eine Umgebungsvariable mit dem untergeordneten Element <environmentVariable> eines <environmentVariables>-Auflistungselements an.

Im folgenden Beispiel werden zwei Umgebungsvariablen festgelegt. ASPNETCORE_ENVIRONMENT konfiguriert die Umgebung der App als Development. Ein Entwickler setzt diesen Wert möglicherweise vorübergehend in der Datei web.config, um das Laden der Seite mit Ausnahmen für Entwickler beim Debugging einer App-Ausnahme zu erzwingen. CONFIG_DIR ist ein Beispiel für eine benutzerdefinierte Umgebungsvariable, wobei der Entwickler Code geschrieben hat, der den Wert beim Start liest, um einen Pfad zum Laden der Konfigurationsdatei der App zu bilden.

<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>

app_offline.htm

Wenn eine Datei mit dem Namen app_offline.htm im Stammverzeichnis einer App erkannt wird, versucht das ASP.NET Core-Modul, die App ordnungsgemäß zu beenden und die Verarbeitung eingehender Anforderungen zu stoppen. Wenn die App nach der Anzahl von Sekunden, die in shutdownTimeLimit definiert wurden, noch ausgeführt wird, beendet das ASP.NET Core-Modul den laufenden Prozess.

Wenn die Datei app_offline.htm vorhanden ist, reagiert das ASP.NET Core-Modul auf Anforderungen, indem es den Inhalt der app_offline.htm-Datei zurücksendet. Wenn die Datei app_offline.htm entfernt wurde, wird die App von der nächsten Anforderung gestartet.

Startfehler-Seite

Wenn das ASP.NET Core-Modul den Back-End-Prozess nicht starten kann oder der Back-End-Prozess gestartet wird, aber nicht am konfigurierten Port lauscht, wird die Statuscodeseite 502.5: Prozessfehler angezeigt. Um diese Seite zu unterdrücken und zur IIS-502-Sandardstatuscodeseite zurückzukehren, verwenden Sie das Attribut disableStartUpErrorPage. Weitere Informationen zum Konfigurieren von benutzerdefinierten Fehlermeldungen finden Sie unter HTTP-Fehler <httpErrors>.

Protokollerstellung und Weiterleitung

Das ASP.NET Core-Modul leitet die Konsolenausgabe „stdout“ und „stderr“ auf den Datenträger weiter, wenn die Attribute stdoutLogEnabled und stdoutLogFile des aspNetCore-Elements festgelegt werden. Ordner, die im stdoutLogFile-Pfad angegeben werden, werden vom Modul erstellt, wenn die Protokolldatei erstellt wird. Der App-Pool muss über Schreibzugriff auf den Speicherort verfügen, an dem die Protokolle geschrieben werden (verwenden Sie IIS AppPool\<app_pool_name>, um die Schreibberechtigung bereitzustellen).

Protokolle werden nur dann rotiert, wenn die Prozesswiederverwendung/der Prozessneustart stattfindet. Der Hoster ist für die Begrenzung des Speicherplatzes zuständig, den die Protokolle nutzen.

Die Verwendung des stdout-Protokolls wird nur für die Problembehandlung bei App-Startproblemen beim Hosten in IIS oder beim Verwenden von Support zum Zeitpunkt der Entwicklung für IIS in Visual Studio empfohlen, nicht aber für das lokale Debuggen und das Ausführen der App mit IIS Express.

Verwenden Sie das Protokoll „stdout“ nicht zu allgemeinen App-Protokollierungszwecken. Verwenden Sie für die routinemäßige Protokollierung in einer ASP.NET Core-App eine Protokollierungsbibliothek, die die Protokolldateigröße beschränkt und die Protokolle rotiert. Weitere Informationen finden Sie im Artikel zur Protokollierung von Drittanbietern.

Ein Zeitstempel und eine Dateierweiterung werden automatisch hinzugefügt, wenn die Protokolldatei erstellt wird. Ein Protokolldateiname wird erstellt, indem der Zeitstempel, die Prozess-ID und die Dateierweiterung ( .log) an das letzte Segment des stdoutLogFile-Pfads (in der Regel stdout), getrennt durch Unterstriche, angehängt werden. Wenn der stdoutLogFile-Pfad mit stdout endet, hat ein Protokoll für eine App mit der PID 1934, erstellt am 2.5.2018 um 19:42:32, den Dateinamen stdout_20180205194132_1934.log.

Das folgende Beispielelement aspNetCore konfiguriert die stdout-Protokollierung im relativen .\log\-Pfad. Vergewissern Sie sich, dass die Identität der AppPool-Benutzerin bzw. des AppPool-Benutzers über die Berechtigung zum Schreiben in den angegebenen Pfad verfügt.

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

Beim Veröffentlichen einer App für die Azure App Service-Bereitstellung legt das Web SDK den Wert stdoutLogFile auf \\?\%home%\LogFiles\stdout fest. Die Umgebungsvariable %home ist für Apps vordefiniert, die von Azure App Service gehostet werden.

Informationen zum Erstellen von Protokollierungsfilterregeln finden Sie in dem Abschnitt Protokollfilterregeln in Code verwenden der Dokumentation zur ASP.NET Core-Protokollierung.

Weitere Informationen zu Pfadformaten finden Sie unter Formate von Dateipfaden unter Windows-Systemen.

Die Proxykonfiguration verwendet das HTTP-Protokoll und ein Paarbildungstoken

Der Proxy, der zwischen dem ASP.NET Core-Modul und Kestrel erstellt wurde, verwendet das HTTP-Protokoll. Es gibt kein Risiko für Lauschangriffe auf den Datenverkehr zwischen dem Modul und Kestrel von einem Speicherort außerhalb des Servers.

Ein Paarbildungstoken wird verwendet, um sicherzustellen, dass die von Kestrel empfangenen Anfragen von IIS über einen Proxy gesendet wurden und nicht von einer anderen Quelle stammen. Das Paarbildungstoken wurde durch das Modul erstellt und in einer Umgebungsvariablen (ASPNETCORE_TOKEN) festgelegt. Das Paarbildungstoken ist auch bei jeder Proxyanforderung in einem Header (MS-ASPNETCORE-TOKEN) festgelegt. IIS-Middleware überprüft jede erhaltene Anforderung, um sicherzustellen, dass der Headerwert des Paarbildungstokens dem Wert der Umgebungsvariablen entspricht. Wenn die Tokenwerte nicht übereinstimmen, wird die Anforderung protokolliert und abgelehnt. Es kann nicht von einem Speicherort außerhalb des Servers auf die Umgebungsvariablen des Paarbildungstokens und den Datenverkehr zwischen dem Modul und Kestrel zugegriffen werden. Wenn Cyberkriminelle den Wert des Paarbildungstokens nicht kennen, können sie keine Anforderungen einreichen, die die IIS-Middleware-Prüfung umgehen.

ASP.NET Core-Modul mit einer IIS-Freigabekonfiguration

Das Installationsprogramm des ASP.NET Core-Moduls wird mit den Berechtigungen des TrustedInstaller-Kontos ausgeführt. Da das lokale Systemkonto keine Berechtigung zum Ändern für den von der IIS-Freigabekonfiguration verwendeten Freigabepfad hat, stößt der Installer beim Versuch, die Moduleinstellungen in der applicationHost.config-Datei auf der Freigabe zu konfigurieren, auf einen „Zugriff verweigert“-Fehler.

Wenn Sie eine IIS-Freigabekonfiguration verwenden, gehen Sie folgendermaßen vor:

1. Deaktivieren Sie die IIS-Freigabekonfiguration.
2. Führen Sie den Installer aus.
3. Exportieren Sie die aktualisierte Datei applicationHost.config auf die Freigabe.
4. Aktivieren Sie die IIS-Freigabekonfiguration erneut.

Version des Moduls und Installerprotokolle des Hostingpakets

So ermitteln Sie die Version des installierten ASP.NET Core-Moduls:

1. Navigieren Sie auf dem Hostsystem zu %windir%\System32\inetsrv.
2. Suchen Sie die Datei aspnetcore.dll.
3. Klicken Sie mit der rechten Maustaste auf die Datei, und wählen Sie im Dropdownmenü die Option Eigenschaften aus.
4. Wählen Sie die Registerkarte Details aus. Die Dateiversion und die Produktversion stellen die installierte Version des Moduls dar.

Die Protokolle des Installationsprogramms des Hostingpakets für das Modul befinden sich unter C:\Users\%UserName%\AppData\Local\Temp. Die Datei heißt dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Dateispeicherorte für Modul, Schema und Konfiguration

Modul

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

Schema

IIS

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

IIS Express

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

Konfiguration

IIS

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

IIS Express

• Visual Studio: {ANWENDUNGSSTAMM}\.vs\config\applicationHost.config

• iisexpress.exe-CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Den Speicherort dieser Dateien finden Sie, indem Sie aspnetcore in der Datei applicationHost.config suchen.