web.config-Datei

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Die aktuelle Version finden Sie in der .NET 10-Version dieses Artikels.

Warnung

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der .NET- und .NET Core-Supportrichtlinie. Die aktuelle Version finden Sie in der .NET 10-Version dieses Artikels.

Die web.config ist eine Datei, die von IIS gelesen wird, und das modul ASP.NET Core zum Konfigurieren einer mit IIS gehosteten App.

Speicherort der Datei web.config

Um das ASP.NET Core-Modul korrekt einzurichten, muss die web.config-Datei im Inhaltsstammpfad (normalerweise dem App-Basispfad) der bereitgestellten App vorhanden sein. Dies ist derselbe Speicherort wie der physische Pfad der Website, der für IIS bereitgestellt wurde. Die Datei web.config wird im Stammverzeichnis der App benötigt, um die Veröffentlichung mehrerer Apps mit Web Deploy zu ermöglichen.

Vertrauliche Dateien wie {ASSEMBLY}.runtimeconfig.json, {ASSEMBLY}.xml (Kommentare zur XML-Dokumentation) und {ASSEMBLY}.deps.json sind im physischen Pfad der App vorhanden. Der Platzhalter {ASSEMBLY} steht hierbei für den Assemblynamen. Wenn die web.config-Datei vorhanden ist und die Website normal startet, stellt IIS diese vertraulichen Dateien bei Anforderung nicht bereit. Wenn die web.config Datei fehlt, falsch benannt oder die Website nicht für den normalen Start konfiguriert werden kann, werden vertrauliche Dateien von IIS möglicherweise öffentlich bereitgestellt.

Die Datei web.config muss immer in der Bereitstellung vorhanden, richtig benannt und in der Lage sein, die Website für einen normalen Start zu konfigurieren. Entfernen Sie die Datei web.config niemals aus einer Produktionsbereitstellung.

Wenn im Projekt keine Datei namens web.config vorhanden ist, wird sie zur Konfiguration des ASP.NET Core-Moduls mit dem richtigen processPath- und arguments-Attribut erstellt und in die veröffentlichte Ausgabe verschoben.

Ist eine Datei namens web.config im Projekt vorhanden, wird sie zur Konfiguration des ASP.NET Core-Moduls mit dem richtigen processPath- und arguments-Attribut transformiert und in die veröffentlichte Ausgabe verschoben. Die Transformation ändert die IIS-Konfigurationseinstellungen in der Datei nicht.

Die web.config Datei stellt möglicherweise zusätzliche IIS-Konfigurationseinstellungen bereit, die aktive IIS-Module steuern. Informationen zu IIS-Modulen, die in der Lage sind, Anforderungen mit ASP.NET Core Apps zu verarbeiten, finden Sie im Artikel IIS-Module.

Ein MSBuild-Ziel (_TransformWebConfig) behandelt das Erstellen, Transformieren und Veröffentlichen der web.config Datei, wenn das Projekt veröffentlicht wird. Dieses Ziel ist in den Web SDK-Zielen (Microsoft.NET.Sdk.Web) vorhanden. Das SDK wird am Anfang der Projektdatei festgelegt:

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

Verwenden Sie die Eigenschaft web.config in der Projektdatei, um zu verhindern, dass das Web-SDK die Datei <IsTransformWebConfigDisabled> transformiert:

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

Wenn das Web SDK davon abgehalten wird, die Datei zu transformieren, sollte der Entwickler processPath und arguments manuell festlegen. Weitere Informationen finden Sie im Artikel ASP.NET Core-Modul (ANCM) für IIS:

Konfiguration des ASP.NET Core-Moduls mit web.config

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

Die folgende web.config-Datei wird für eine Framework-abhängige Bereitstellung veröffentlicht und konfiguriert das ASP.NET Core-Modul zur Handhabung von Anfragen an die 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>

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 im Ordner LogFiles, einem Verzeichnis, das automatisch vom Dienst erstellt wird.

Weitere Informationen zur Konfiguration von IIS untergeordneten Anwendungen finden Sie unter Erweiterte Konfiguration.

Attribute des aspNetCore-Elements

Attribut BESCHREIBUNG Standard
arguments

Optionales Zeichenfolgeattribut.

Argumente zur ausführbaren Datei, die in processPath angegeben wurde.
disableStartUpErrorPage

Optionales boolesches Attribut.

Wenn TRUE, wird die Seite 502.5: Prozessfehler unterdrückt, und die in der Datei web.config konfigurierte Seite für den Statuscode 502 hat Vorrang.

 false
forwardWindowsAuthToken

Optionales boolesches Attribut.

Wenn TRUE, wird das Token an den untergeordneten Prozess weitergeleitet, der an %ASPNETCORE_PORT% als Header 'MS-ASPNETCORE-WINAUTHTOKEN' pro Anforderung lauscht. Es liegt in der Verantwortung des entsprechenden Prozesses, CloseHandle auf dem Token pro Anforderung aufzurufen.

 true
hostingModel

Optionales Zeichenfolgeattribut.

Gibt das Hostingmodell als In-Process (InProcess/inprocess) oder Out-of-Process (OutOfProcess/outofprocess) an.

 OutOfProcess / outofprocess, wenn nicht vorhanden
processesPerApplication

Optionales Ganzzahlattribut.

Gibt die Anzahl der Instanzen des in der processPath-Einstellung angegebenen Prozesses an, die pro App gestartet werden können.

†Für In-Process-Hosting ist dieser Wert auf 1 beschränkt.

Einstellen von processesPerApplication wird nicht empfohlen. Dieses Attribut wird in einer der nächsten Releases entfernt.

 Standardwert: 1
Min.: 1
Max: 100†
processPath

Erforderliches Zeichenfolgenattribut.

Pfad zur ausführbaren Datei, die einen Prozess startet, der auf HTTP-Anforderungen lauscht. Relative Pfade werden unterstützt. Wenn der Pfad mit . beginnt, gilt er als relativ zum Stammverzeichnis der Website.
rapidFailsPerMinute

Optionales Ganzzahlattribut.

Gibt an, wie viele Abstürze des in processPath angegebenen Prozesses pro Minute zulässig sind. Wenn dieses Limit überschritten wird, beendet das Modul das Starten des Prozesses für den Rest der Minute.

Bei In-Process-Hosting nicht unterstützt.

 Standardwert: 10
Min.: 0
Max.: 100
requestTimeout

Optionales TimeSpan-Attribut.

Gibt an, wie lange das ASP.NET Core-Modul auf eine Antwort des Prozesses wartet, der auf „% ASPNETCORE_PORT“ lauscht.

In den Versionen des ASP.NET Core-Moduls, die mit Version ASP.NET Core 2.1 oder später ausgeliefert wurden, wird requestTimeout in Stunden, Minuten und Sekunden angegeben.

Trifft auf In-Process-Hosting nicht zu. Bei In-Process-Hosting wartet das Modul darauf, dass die App die Anforderung verarbeitet.

Gültige Werte für Minuten- und Sekundensegmente der Zeichenfolge befinden sich im Bereich 0–59. Die Verwendung von 60 im Wert für Minuten oder Sekunden verursacht einen 500 – Interner Serverfehler.

 Standardwert: 00:02:00
Min.: 00:00:00
Max.: 360:00:00
shutdownTimeLimit

Optionales Ganzzahlattribut.

Gibt in Sekunden an, wie lange das Modul darauf wartet, dass die ausführbare Datei ordnungsgemäß beendet wird, wenn die Datei app_offline.htm erkannt wird.

 Standardwert: 10
Min.: 0
Max.: 600
startupTimeLimit

Optionales Ganzzahlattribut.

Gibt in Sekunden an, wie lange das Modul darauf wartet, dass die ausführbare Datei einen Prozess startet, der an dem Port lauscht. Wenn dieses Zeitlimit überschritten wird, beendet das Modul den Prozess.

Bei In-Process-Hosting: Der Prozess wird nicht neu gestartet und verwendet nicht die Einstellung rapidFailsPerMinute.

Bei Out-of-Process-Hosting: Das Modul versucht, den Prozess neu zu starten, wenn es eine neue Anforderung erhält, und versucht weiterhin, den Prozess bei nachfolgenden eingehenden Anforderungen neu zu starten, es sei denn, die App kann rapidFailsPerMinute-Anzahl in der letzten fortlaufenden Minute nicht starten.

Der Wert 0 (null) wird nicht als unendliches Timeout angesehen.

 Standardwert: 120
Min.: 0
Max.: 3600
stdoutLogEnabled

Optionales boolesches Attribut.

Wenn TRUE, werden stdout und stderr für den Prozess, der in processPath angegeben wurde, zu der Datei weitergeleitet, die in stdoutLogFile angegeben wurde.

 false
stdoutLogFile

Optionales Zeichenfolgeattribut.

Gibt den relativen oder absoluten Dateipfad an, für den stdout und stderr aus dem Prozess protokolliert werden, der in processPath angegeben ist. Relative Pfade sind relativ zum Stamm der Site. Jeder Pfad, der mit . beginnt, ist relativ zum Stammverzeichnis, während alle anderen Pfade als absolute Pfade gelten. Das Modul erstellt alle Ordner, die im Pfad bereitgestellt werden, wenn die Protokolldatei erstellt wird. Mithilfe von Unterstrichtrennzeichen werden ein Zeitstempel, eine Prozess-ID und eine Dateierweiterung ( .log) dem letzten Segment des Pfads stdoutLogFile hinzugefügt. Wenn .\logs\stdout als Wert angegeben wird, wird ein stdout-Beispielprotokoll als stdout_20180205194132_1934.log im Ordner logs gespeichert, sofern es am 5.2.2018 um 19:41:32 mit Prozess-ID 1934 gespeichert wurde.

 aspnetcore-stdout

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 legt diesen Wert möglicherweise vorübergehend in der web.config Datei fest, um das Laden der Entwickler ausnahmeseite beim Debuggen 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>

Hinweis

Eine Alternative zum direkten Festlegen der Umgebung in web.config ist das Einschließen der <EnvironmentName>-Eigenschaft in das Veröffentlichungsprofil (.pubxml) oder eine Projektdatei. Dieser Ansatz legt die Umgebung in web.config fest, wenn das Projekt veröffentlicht wird:

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

Warnung

Legen Sie die Umgebungsvariable ASPNETCORE_ENVIRONMENT nur auf Staging- und Testservern auf Development fest, auf die nicht vertrauenswürdige Netzwerke, z.B. das Internet, nicht zugreifen können.

IIS-Konfiguration mit web.config

Die IIS-Konfiguration wird von dem Abschnitt <system.webServer> der Datei web.config für IIS-Szenarien beeinflusst, die für ASP.NET Core-Apps mit dem ASP.NET Core-Modul funktional sind. Beispielsweise eignet sich die IIS-Konfiguration für dynamische Komprimierung. Wenn IIS auf Serverebene für die Verwendung der dynamischen Komprimierung konfiguriert ist, kann diese Einstellung mit dem <urlCompression>-Element in der Datei web.config der App für eine ASP.NET Core-App deaktiviert werden.

Weitere Informationen finden Sie in den folgenden Artikeln:

Informationen zum Festlegen von Umgebungsvariablen für einzelne Apps, die in isolierten App-Pools ausgeführt werden (unterstützt für IIS 10.0 oder höher), finden Sie AppCmd.exe im Befehlsabschnitt des Artikels"Umgebungsvariablen <environmentVariables> " in der IIS-Referenzdokumentation.

Konfigurationsabschnitte für web.config

Konfigurationsabschnitte von ASP.NET 4.x-Apps in der Datei web.config werden von ASP.NET Core-Apps nicht zur Konfiguration verwendet:

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

ASP.NET Core-Apps werden mit anderen Konfigurationsanbietern konfiguriert. Weitere Informationen finden Sie unter Konfiguration.

Transformieren von web.config

Wenn Sie web.config beim Veröffentlichen transformieren müssen, finden Sie unter Transformieren von web.config weitere Informationen. Möglicherweise müssen Sie web.config beim Veröffentlichen transformieren, um Umgebungsvariablen basierend auf der Konfiguration, dem Profil oder der Umgebung festzulegen.

Zusätzliche Ressourcen

  • Last updated on