web.config-Datei

  • Artikel

Bei web.config handelt es sich um eine Datei, die von den IIS und vom ASP.NET Core-Modul gelesen wird, um eine mit den IIS gehostete App zu konfigurieren.

Speicherort der Datei web.config

Zum Erstellen des ASP.NET Core-Moduls muss die Datei web.config im Inhaltsstammpfad (normalerweise dem App-Basispfad) der bereitgestellten App vorhanden sein. Dies ist der physische Pfad der Website, der in 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, werden diese vertraulichen Dateien bei Anforderung nicht offengelegt. Wenn die Datei web.config fehlt, falsch benannt wurde oder die Website nicht für den normalen Start konfigurieren kann, macht IIS vertrauliche Dateien möglicherweise öffentlich verfügbar.

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 Datei web.config kann zusätzliche IIS-Konfigurationseinstellungen zum Steuern der aktiven IIS-Module bereitstellen. Informationen zu IIS-Modulen, die Anforderungen mit ASP.NET Core-Apps verarbeiten können, finden Sie im Thema IIS-Module.

Die Erstellung, Transformation und Veröffentlichung der Datei web.config wird bei der Projektveröffentlichung von einem MSBuild-Ziel (_TransformWebConfig) abgewickelt. 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 <IsTransformWebConfigDisabled> in der Projektdatei, um zu verhindern, dass das Web-SDK die Datei web.config transformiert:

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

Wenn die Transformation der Datei durch das Web-SDK deaktiviert wird, müssen die Attribute processPath und arguments manuell durch den Entwickler festgelegt werden. 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 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.

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

Attribute des aspNetCore-Elements

attribute 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 Prozesses aus der Einstellung processPath an, die aus der 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.
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 Sekundenergebnisse führt zu einem 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 Pfad an, für den stdout und stderr aus dem in processPath angegebenen Prozess protokolliert wurden. Relative Pfade sind relativ zum Stamm der Site. Jeder mit . beginnende Pfad ist zum Stammverzeichnis relativ, und alle anderen Pfade werden als absolute Pfade behandelt. Ordner, die im Pfad angegeben werden, werden vom Modul erstellt, 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 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>

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 unter den folgenden Themen:

Lesen Sie den Abschnitt zum Befehl AppCmd.exe im Thema Umgebungsvariablen<environmentVariables> in der IIS-Referenzdokumentation, um Umgebungsvariablen für einzelne Apps festzulegen, die in isolierten App-Pools ausgeführt werden (unterstützt für IIS 10.0 oder höher).

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