ASP.NET Core-ModulASP.NET Core Module

Von Tom Dykstra, Rick Strahl, Chris Ross, Rick Anderson, Sourabh Shirhatti und Justin KotalikBy Tom Dykstra, Rick Strahl, Chris Ross, Rick Anderson, Sourabh Shirhatti, and Justin Kotalik

Das ASP.NET Core-Modul ist ein natives IIS-Modul, das in die IIS-Pipeline integriert wird, um eine dieser Aktionen auszuführen:The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:

Unterstützte Windows-Versionen:Supported Windows versions:

  • Windows 7 oder höherWindows 7 or later
  • Windows Server 2012 R2 oder höherWindows Server 2012 R2 or later

Beim In-Process-Hosting verwendet das Modul eine In-Process-Server-Implementierung für IIS, die als IIS-HTTP-Server (IISHttpServer) bezeichnet wird.When hosting in-process, the module uses an in-process server implementation for IIS, called IIS HTTP Server (IISHttpServer).

Beim Out-of-Process-Hosting funktioniert das Modul nur mit Kestrel.When hosting out-of-process, the module only works with Kestrel. Dieses Modul funktioniert nicht mit HTTP.sys.The module doesn't function with HTTP.sys.

HostingmodelleHosting models

In-Process-HostingmodellIn-process hosting model

ASP.NET Core-Apps verwenden standardmäßig das In-Process-Hostingmodell.ASP.NET Core apps default to the in-process hosting model.

Die folgenden Merkmale treffen für In-Process-Hosting zu:The following characteristics apply when hosting in-process:

  • Der IIS-HTTP-Server (IISHttpServer) wird anstelle des Kestrel-Servers verwendet.IIS HTTP Server (IISHttpServer) is used instead of Kestrel server. Für In-Process ruft CreateDefaultBuilderUseIIS auf zu:For in-process, CreateDefaultBuilder calls UseIIS to:

    • Registrieren des IISHttpServer.Register the IISHttpServer.
    • Konfigurieren des Ports und des Basispfads, den der Server überwachen soll, wenn er hinter dem ASP.NET Core-Modul ausgeführt wird.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
    • Konfigurieren des Hosts zum Erfassen von Startfehlern.Configure the host to capture startup errors.
  • Das RequestTimeout-Attribut trifft auf In-Process-Hosting nicht zu.The requestTimeout attribute doesn't apply to in-process hosting.

  • Das gemeinsame Verwenden eines Anwendungspools durch mehrere Apps wird nicht unterstützt.Sharing an app pool among apps isn't supported. Verwenden Sie einen Anwendungspool pro App.Use one app pool per 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.When using Web Deploy or manually placing an app_offline.htm file in the deployment, the app might not shut down immediately if there's an open connection. Beispielsweise kann eine Websocketverbindung eine Verzögerung beim Herunterfahren der App bewirken.For example, a websocket connection may delay app shut down.

  • Die Architektur (Bitbreite) der App und der installierten Runtime (x64 oder x86) müssen mit der Architektur des Anwendungspools übereinstimmen.The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool.

  • Verbindungstrennungen von Clients werden erkannt.Client disconnects are detected. Das Abbruchtoken HttpContext.RequestAborted wird abgebrochen, wenn die Verbindung mit dem Client getrennt wird.The HttpContext.RequestAborted cancellation token is cancelled when the client disconnects.

  • 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).In ASP.NET Core 2.2.1 or earlier, GetCurrentDirectory returns the worker directory of the process started by IIS rather than the app's directory (for example, C:\Windows\System32\inetsrv for w3wp.exe).

    Den Beispielcode zum Festlegen des aktuellen App-Verzeichnisses finden Sie in der Klasse CurrentDirectoryHelpers.For sample code that sets the app's current directory, see the CurrentDirectoryHelpers class. Rufen Sie die SetCurrentDirectory-Methode auf.Call the SetCurrentDirectory method. Nachfolgende Aufrufe von GetCurrentDirectory stellen das App-Verzeichnis bereit.Subsequent calls to GetCurrentDirectory provide the app's directory.

  • Beim In-Process-Hosting wird AuthenticateAsync nicht intern aufgerufen, um einen Benutzer zu initialisieren.When hosting in-process, AuthenticateAsync isn't called internally to initialize a user. Deshalb ist eine IClaimsTransformation-Implementierung, die verwendet wird, um Ansprüche nach jeder Authentifizierung zu transformieren, nicht standardmäßig aktiviert.Therefore, an IClaimsTransformation implementation used to transform claims after every authentication isn't activated by default. Rufen Sie AddAuthentication auf, um Authentifizierungsdienste hinzuzufügen, wenn Ansprüche mit einer IClaimsTransformation-Implementierung transformiert werden:When transforming claims with an IClaimsTransformation implementation, call AddAuthentication to add authentication services:

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

Out-of-Process-HostingmodellOut-of-process hosting model

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:To configure an app for out-of-process hosting, set the value of the <AspNetCoreHostingModel> property to OutOfProcess in the project file (.csproj):

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

Das In-Process-Hosting wird mithilfe von InProcess (Standardwert) festgelegt.In-process hosting is set with InProcess, which is the default value.

Beim Wert von <AspNetCoreHostingModel> wird die Groß-/Kleinschreibung nicht beachtet, sodass inprocess und outofprocess gültige Werte sind.The value of <AspNetCoreHostingModel> is case insensitive, so inprocess and outofprocess are valid values.

Der Kestrel-Server wird anstelle des IIS-HTTP-Servers (IISHttpServer) verwendet.Kestrel server is used instead of IIS HTTP Server (IISHttpServer).

Für Out-of-Process ruft CreateDefaultBuilderUseIISIntegration auf zu:For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:

  • Konfigurieren des Ports und des Basispfads, den der Server überwachen soll, wenn er hinter dem ASP.NET Core-Modul ausgeführt wird.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
  • Konfigurieren des Hosts zum Erfassen von Startfehlern.Configure the host to capture startup errors.

Änderungen am HostmodellHosting model changes

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.If the hostingModel setting is changed in the web.config file (explained in the Configuration with web.config section), the module recycles the worker process for IIS.

Bei IIS Express verwendet das Modul den Arbeitsprozess nicht erneut, sondern löst stattdessen ein ordnungsgemäßes Herunterfahren des aktuellen IIS Express-Prozesses aus.For IIS Express, the module doesn't recycle the worker process but instead triggers a graceful shutdown of the current IIS Express process. Mit der nächsten Anforderung an die App wird ein neuer IIS Express-Prozess erzeugt.The next request to the app spawns a new IIS Express process.

ProzessnameProcess name

Process.GetCurrentProcess().ProcessName meldet w3wp/iisexpress (In-Process) oder dotnet (Out-of-Process).Process.GetCurrentProcess().ProcessName reports w3wp/iisexpress (in-process) or dotnet (out-of-process).

Viele native Module, z.B. die Windows-Authentifizierung, bleiben aktiv.Many native modules, such as Windows Authentication, remain active. Weitere Informationen zu IIS-Modulen, die im ASP.NET Core-Modul aktiv sind, finden Sie unter IIS-Module mit ASP.NET Core.To learn more about IIS modules active with the ASP.NET Core Module, see IIS-Module mit ASP.NET Core.

Das ASP.NET Core-Modul kann außerdem:The ASP.NET Core Module can also:

  • Umgebungsvariablen für den Arbeitsprozess festlegenSet environment variables for the worker process.
  • Die stdout-Ausgabe im Dateispeicher protokollieren, um Probleme beim Start zu behebenLog stdout output to file storage for troubleshooting startup issues.
  • Windows-Authentifizierungstoken weiterleitenForward Windows authentication tokens.

So installieren und verwenden Sie das ASP.NET Core-ModulHow to install and use the ASP.NET Core Module

Anweisungen zum Installieren des ASP.NET Core-Moduls finden Sie unter Installieren des .NET Core-Hostingpakets.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Konfiguration mit der Datei „web.config“Configuration with web.config

Das ASP.NET Core-Modul wurde mit dem aspNetCore-Abschnitt des system.webServer-Knotens in der Datei web.config der Site konfiguriert.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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:The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

<?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:The following web.config is published for a self-contained deployment:

<?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.The InheritInChildApplications property is set to false to indicate that the settings specified within the <location> element aren't inherited by apps that reside in a subdirectory of the app.

Wenn eine App für Azure App Service bereitgestellt wird, wird der Pfad stdoutLogFile auf \\?\%home%\LogFiles\stdout gesetzt.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. Der Pfad speichert stdout-Protokolle zum Ordner LogFiles, einem Speicherort, der automatisch vom Dienst erstellt wird.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Weitere Informationen zur Konfiguration von IIS untergeordneten Anwendungen finden Sie unter Hosten von ASP.NET Core unter Windows mit IIS.For information on IIS sub-application configuration, see Hosten von ASP.NET Core unter Windows mit IIS.

Attribute des aspNetCore-ElementsAttributes of the aspNetCore element

AttributAttribute BeschreibungDescription StandardDefault
arguments

Optionales Zeichenfolgeattribut.Optional string attribute.

Argumente zur ausführbaren Datei, die in processPath angegeben wurde.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Optionales boolesches Attribut.Optional Boolean attribute.

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.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Optionales boolesches Attribut.Optional Boolean attribute.

Wenn TRUE, wird das Token an den untergeordneten Prozess weitergeleitet, der an %ASPNETCORE_PORT% als Header 'MS-ASPNETCORE-WINAUTHTOKEN' pro Anforderung lauscht.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. Es liegt in der Verantwortung des entsprechenden Prozesses, CloseHandle auf dem Token pro Anforderung aufzurufen.It's the responsibility of that process to call CloseHandle on this token per request.

true
hostingModel

Optionales Zeichenfolgeattribut.Optional string attribute.

Gibt das Hostingmodell als In-Process (InProcess/inprocess) oder Out-of-Process (OutOfProcess/outofprocess) an.Specifies the hosting model as in-process (InProcess/inprocess) or out-of-process (OutOfProcess/outofprocess).

InProcess
inprocess
processesPerApplication

Optionales Ganzzahlattribut.Optional integer attribute.

Gibt die Anzahl der Instanzen des Prozesses aus der Einstellung processPath an, die aus der App gestartet werden können.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

†Für In-Process-Hosting ist dieser Wert auf 1 beschränkt.†For in-process hosting, the value is limited to 1.

Einstellen von processesPerApplication wird nicht empfohlen.Setting processesPerApplication is discouraged. Dieses Attribut wird in einer der nächsten Releases entfernt.This attribute will be removed in a future release.

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

Erforderliches Zeichenfolgenattribut.Required string attribute.

Pfad zur ausführbaren Datei, die einen Prozess startet, der auf HTTP-Anforderungen lauscht.Path to the executable that launches a process listening for HTTP requests. Relative Pfade werden unterstützt.Relative paths are supported. Wenn der Pfad mit . beginnt, gilt er als relativ zum Stammverzeichnis.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Optionales Ganzzahlattribut.Optional integer attribute.

Gibt an, wie viele Abstürze des in ProcessPath angegebenen Prozesses pro Minute zulässig sind.Specifies the number of times the process specified in processPath is allowed to crash per minute. Wenn dieses Limit überschritten wird, beendet das Modul das Starten des Prozesses für den Rest der Minute.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

Bei In-Process-Hosting nicht unterstützt.Not supported with in-process hosting.

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

Optionales TimeSpan-Attribut.Optional timespan attribute.

Gibt an, wie lange das ASP.NET Core-Modul auf eine Antwort des Prozesses wartet, der auf „% ASPNETCORE_PORT“ lauscht.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%.

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.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

Trifft auf In-Process-Hosting nicht zu.Doesn't apply to in-process hosting. Bei In-Process-Hosting wartet das Modul darauf, dass die App die Anforderung verarbeitet.For in-process hosting, the module waits for the app to process the request.

Gültige Werte für Minuten- und Sekundensegmente der Zeichenfolge befinden sich im Bereich 0–59.Valid values for minutes and seconds segments of the string are in the range 0-59. Die Verwendung von 60 im Wert für Minuten- oder Sekundenergebnisse führt zu einem 500 – Interner Serverfehler.Use of 60 in the value for minutes or seconds results in a 500 - Internal Server Error.

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

Optionales Ganzzahlattribut.Optional integer attribute.

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.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

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

Optionales Ganzzahlattribut.Optional integer attribute.

Gibt in Sekunden an, wie lange das Modul darauf wartet, dass die ausführbare Datei einen Prozess startet, der an dem Port lauscht.Duration in seconds that the module waits for the executable to start a process listening on the port. Wenn dieses Zeitlimit überschritten wird, beendet das Modul den Prozess.If this time limit is exceeded, the module kills the process. 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.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Der Wert 0 (null) wird nicht als unendliches Timeout angesehen.A value of 0 (zero) is not considered an infinite timeout.

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

Optionales boolesches Attribut.Optional Boolean attribute.

Wenn TRUE, werden stdout und stderr für den Prozess, der in processPath angegeben wurde, zu der Datei weitergeleitet, die in stdoutLogFile angegeben wurde.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Optionales Zeichenfolgeattribut.Optional string attribute.

Gibt den relativen oder absoluten Pfad an, für den stdout und stderr aus dem in ProcessPath angegebenen Prozess protokolliert wurden.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Relative Pfade sind relativ zum Stamm der Site.Relative paths are relative to the root of the site. Jeder mit . beginnende Pfad ist zum Stammverzeichnis relativ, und alle anderen Pfade werden als absolute Pfade behandelt.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Ordner, die im Pfad angegeben werden, werden vom Modul erstellt, wenn die Protokolldatei erstellt wird.Any folders provided in the path are created by the module when the log file is created. Mithilfe von Unterstrichtrennzeichen werden ein Zeitstempel, eine Prozess-ID und eine Dateierweiterung ( .log) dem letzten Segment des Pfads stdoutlogfile hinzugefügt.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. Wenn .\logs\stdout als Wert angegeben wird, wird ein stdout-Beispielprotokoll als stdout_20180205194132_1934.log im Ordner logs gespeichert, sofern es am 2.5.2018 um 19:41:32 mit Prozess-ID 1934 gespeichert wurde.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Festlegen von UmgebungsvariablenSet environment variables

Umgebungsvariablen können für den Prozess im Attribut processPath angegeben werden.Environment variables can be specified for the process in the processPath attribute. Geben Sie eine Umgebungsvariable mit dem untergeordneten Element <environmentVariable> eines <environmentVariables>-Auflistungselements an.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element. In diesem Abschnitt festgelegte Umgebungsvariablen haben Vorrang vor Systemumgebungsvariablen.Environment variables set in this section take precedence over system environment variables.

Im folgenden Beispiel werden zwei Umgebungsvariablen in web.config festgelegt. ASPNETCORE_ENVIRONMENT legt die Umgebung der App auf Development fest.The following example sets two environment variables in web.config. ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

<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 Einbeziehen der <EnvironmentName>-Eigenschaft in das Veröffentlichungsprofil (PUBXML) oder eine Projektdatei.An alternative to setting the environment directly in web.config is to include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Dieser Ansatz legt die Umgebung in web.config fest, wenn das Projekt veröffentlicht wird:This approach sets the environment in web.config when the project is published:

<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.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_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.If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. 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.If the app is still running after the number of seconds defined in shutdownTimeLimit, the ASP.NET Core Module kills the running process.

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.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Wenn die Datei app_offline.htm entfernt wurde, wird die App von der nächsten Anforderung gestartet.When the app_offline.htm file is removed, the next request starts the app.

Beim Verwenden des Out-of-Process-Hostingmodells wird die App möglicherweise nicht sofort heruntergefahren, wenn eine offene Verbindung besteht.When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. Beispielsweise kann eine Websocketverbindung eine Verzögerung beim Herunterfahren der App bewirken.For example, a websocket connection may delay app shut down.

Startfehler-SeiteStart-up error page

Sowohl In-Process- als auch Out-of-Process-Hosting erzeugen benutzerdefinierte Fehlerseiten, wenn die App nicht gestartet werden kann.Both in-process and out-of-process hosting produce custom error pages when they fail to start the app.

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.If the ASP.NET Core Module fails to find either the in-process or out-of-process request handler, a 500.0 - In-Process/Out-Of-Process Handler Load Failure status code page appears.

Wenn das ASP.NET Core-Modul beim In-Process-Hosting die App nicht starten kann, wird die Statuscodeseite 500.30: Fehler beim Starten angezeigt.For in-process hosting if the ASP.NET Core Module fails to start the app, a 500.30 - Start Failure status code page appears.

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.For out-of-process hosting if the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 - Process Failure status code page appears.

Um diese Seite zu unterdrücken und zur standardmäßigen IIS-5xx-Statuscodeseite zurückzukehren, verwenden Sie das Attribut disableStartUpErrorPage.To suppress this page and revert to the default IIS 5xx status code page, use the disableStartUpErrorPage attribute. Weitere Informationen zum Konfigurieren von benutzerdefinierten Fehlermeldungen finden Sie unter HTTP-Fehler <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Protokollerstellung und WeiterleitungLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Ordner, die im stdoutLogFile-Pfad angegeben werden, werden vom Modul erstellt, wenn die Protokolldatei erstellt wird.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Protokolle werden nur dann rotiert, wenn die Prozesswiederverwendung/der Prozessneustart stattfindet.Logs aren't rotated, unless process recycling/restart occurs. Der Hoster ist für die Begrenzung des Speicherplatzes zuständig, den die Protokolle nutzen.It's the responsibility of the hoster to limit the disk space the logs consume.

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.Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

Verwenden Sie das Protokoll „stdout“ nicht zu allgemeinen App-Protokollierungszwecken.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Weitere Informationen finden Sie im Artikel zur Protokollierung von Drittanbietern.For more information, see third-party logging providers.

Ein Zeitstempel und eine Dateierweiterung werden automatisch hinzugefügt, wenn die Protokolldatei erstellt wird.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

Wenn stdoutLogEnabled „false“ ist, werden Fehler beim App-Start erfasst und in das Ereignisprotokoll mit bis zu 30 KB ausgegeben.If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. Nach dem Start werden alle zusätzlichen Protokolle verworfen.After startup, all additional logs are discarded.

Das folgende Beispielelement aspNetCore konfiguriert die stdout-Protokollierung im relativen .\log\-Pfad.The following sample aspNetCore element configures stdout logging at the relative path .\log\. Vergewissern Sie sich, dass die Identität des AppPool-Benutzers über die Berechtigung zum Schreiben in den angegebenen Pfad verfügt.Confirm that the AppPool user identity has permission to write to the path provided.

<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.When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout. Die Umgebungsvariable %home ist für Apps vordefiniert, die von Azure App Service gehostet werden.The %home environment variable is predefined for apps hosted by Azure App Service.

Informationen zum Erstellen von Protokollierungsfilterregeln finden Sie in den Abschnitten Konfiguration und Protokollfilterung der Dokumentation zur ASP.NET Core-Protokollierung.To create logging filter rules, see the Configuration and Log filtering sections of the ASP.NET Core logging documentation.

Weitere Informationen zu Pfadformaten finden Sie unter Formate von Dateipfaden unter Windows-Systemen.For more information on path formats, see File path formats on Windows systems.

Erweiterte DiagnoseprotokolleEnhanced diagnostic logs

Das ASP.NET Core-Modul kann so konfiguriert werden, dass es erweiterte Diagnoseprotokolle bereitstellt.The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Fügen Sie dem <aspNetCore>-Element in der web.config-Datei das <handlerSettings>-Element hinzu. Wenn debugLevel auf TRACE festgelegt wird, werden genauere Diagnoseinformationen zur Verfügung gestellt:Add the <handlerSettings> element to the <aspNetCore> element in web.config. Setting the debugLevel to TRACE exposes a higher fidelity of diagnostic information:

<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.Any folders in the path (logs in the preceding example) are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

debugLevel-Werte können sowohl die Ebene als auch den Speicherort enthalten.Debug level (debugLevel) values can include both the level and the location.

Ebenen (von der geringsten zur höchsten Genauigkeit):Levels (in order from least to most verbose):

  • ERRORERROR
  • WARNINGWARNING
  • INFOINFO
  • TRACETRACE

Speicherorte (mehrere Speicherorte sind zulässig):Locations (multiple locations are permitted):

  • CONSOLECONSOLE
  • EVENTLOGEVENTLOG
  • DATEIFILE

Die Handlereinstellungen können auch über Umgebungsvariablen angegeben werden:The handler settings can also be provided via environment variables:

  • ASPNETCORE_MODULE_DEBUG_FILE: Dies ist der Pfad zur Debugprotokolldatei.ASPNETCORE_MODULE_DEBUG_FILE: Path to the debug log file. (Standard: aspnetcore-debug.log)(Default: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG: Dies ist die Einstellung der Debugebene.ASPNETCORE_MODULE_DEBUG: Debug level setting.

Warnung

Lassen Sie die Debugprotokollierung nicht länger als erforderlich für die Bereitstellung aktiviert, wenn Sie einen Fehler beheben.Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. Die Größe des Protokolls ist nicht beschränkt.The size of the log isn't limited. Wenn die Debugprotokollierung aktiviert bleibt, kann der verfügbare Speicherplatz aufgebraucht werden, und der Server- oder App-Dienst können abstürzen.Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

Konfiguration mit der Datei „web.config“ enthält ein Beispiel für das aspNetCore-Element in der Datei web.config.See Configuration with web.config for an example of the aspNetCore element in the web.config file.

Ändern der StapelgrößeModify the stack size

Gilt nur bei Verwendung des In-Process-Hostingmodells.Only applies when using the in-process hosting model.

Konfigurieren Sie die Größe des verwalteten Stapels in der Datei web.config mithilfe der Einstellung stackSize (in Byte). Die Standardgröße beträgt 1048576 Byte (1 MB).Configure the managed stack size using the stackSize setting in bytes in web.config. The default size is 1048576 bytes (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 PaarbildungstokenProxy configuration uses HTTP protocol and a pairing token

Gilt nur für Out-of-Process-Hosting.Only applies to out-of-process hosting.

Der Proxy, der zwischen dem ASP.NET Core-Modul und Kestrel erstellt wurde, verwendet das HTTP-Protokoll.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. Es gibt kein Risiko für Lauschangriffe auf den Datenverkehr zwischen dem Modul und Kestrel von einem Speicherort außerhalb des Servers.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

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.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. Das Paarbildungstoken wurde durch das Modul erstellt und in einer Umgebungsvariablen (ASPNETCORE_TOKEN) festgelegt.The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. Das Paarbildungstoken ist auch bei jeder Proxyanforderung in einem Header (MS-ASPNETCORE-TOKEN) festgelegt.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. IIS-Middleware überprüft jede erhaltene Anforderung, um sicherzustellen, dass der Headerwert des Paarbildungstokens dem Wert der Umgebungsvariablen entspricht.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Wenn die Tokenwerte nicht übereinstimmen, wird die Anforderung protokolliert und abgelehnt.If the token values are mismatched, the request is logged and rejected. 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.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Wenn ein Angreifer den Wert des Paarbildungstokens nicht kennt, kann er keine Anforderungen einreichen, die die IIS-Middleware-Prüfung umgehen.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

ASP.NET Core-Modul mit einer IIS-FreigabekonfigurationASP.NET Core Module with an IIS Shared Configuration

Das Installationsprogramm des ASP.NET Core-Moduls wird mit den Berechtigungen des TrustedInstaller-Kontos ausgeführt.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

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:When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 1:

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:When the path to the shared configuration isn't on the same machine as the IIS installation, follow these steps:

  1. Deaktivieren Sie die IIS-Freigabekonfiguration.Disable the IIS Shared Configuration.
  2. Führen Sie den Installer aus.Run the installer.
  3. Exportieren Sie die aktualisierte Datei applicationHost.config auf die Freigabe.Export the updated applicationHost.config file to the share.
  4. Aktivieren Sie die IIS-Freigabekonfiguration erneut.Re-enable the IIS Shared Configuration.

Version des Moduls und Installerprotokolle des HostingpaketsModule version and Hosting Bundle installer logs

So ermitteln Sie die Version des installierten ASP.NET Core-Moduls:To determine the version of the installed ASP.NET Core Module:

  1. Navigieren Sie auf dem Hostsystem zu %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Suchen Sie die Datei aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Klicken Sie mit der rechten Maustaste auf die Datei, und wählen Sie im Dropdownmenü die Option Eigenschaften aus.Right-click the file and select Properties from the contextual menu.
  4. Wählen Sie die Registerkarte Details aus. Die Dateiversion und die Produktversion stellen die installierte Version des Moduls dar.Select the Details tab. The File version and Product version represent the installed version of the module.

Die Installer-Protokolle des Hostingpakets für das Modul finden Sie unter C:\Benutzer\%UserName%\AppData\Local\Temp. Die Datei heißt dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Dateispeicherorte für Modul, Schema und KonfigurationModule, schema, and configuration file locations

ModulModule

IIS (x86/amd64):IIS (x86/amd64):

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

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

  • %ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

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

IIS Express (x86/amd64):IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\aspnetcore.dll

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

  • %ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

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

SchemaSchema

IISIIS

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

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

IIS ExpressIIS Express

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

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

KonfigurationConfiguration

IISIIS

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

IIS ExpressIIS Express

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

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

Den Speicherort dieser Dateien finden Sie, indem Sie aspnetcore in der Datei applicationHost.config suchen.The files can be found by searching for aspnetcore in the applicationHost.config file.

Das ASP.NET Core-Modul ist ein natives IIS-Modul, das in die IIS-Pipeline integriert wird, um eine dieser Aktionen auszuführen:The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:

Unterstützte Windows-Versionen:Supported Windows versions:

  • Windows 7 oder höherWindows 7 or later
  • Windows Server 2008 R2 oder höherWindows Server 2008 R2 or later

Beim In-Process-Hosting verwendet das Modul eine In-Process-Server-Implementierung für IIS, die als IIS-HTTP-Server (IISHttpServer) bezeichnet wird.When hosting in-process, the module uses an in-process server implementation for IIS, called IIS HTTP Server (IISHttpServer).

Beim Out-of-Process-Hosting funktioniert das Modul nur mit Kestrel.When hosting out-of-process, the module only works with Kestrel. Dieses Modul funktioniert nicht mit HTTP.sys.The module doesn't function with HTTP.sys.

HostingmodelleHosting models

In-Process-HostingmodellIn-process hosting model

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):To configure an app for in-process hosting, add the <AspNetCoreHostingModel> property to the app's project file with a value of InProcess (out-of-process hosting is set with OutOfProcess):

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

Das In-Process-Hostingmodell wird nicht für ASP.NET Core-Apps unterstützt, die auf .NET Framework abzielen.The in-process hosting model isn't supported for ASP.NET Core apps that target the .NET Framework.

Beim Wert von <AspNetCoreHostingModel> wird die Groß-/Kleinschreibung nicht beachtet, sodass inprocess und outofprocess gültige Werte sind.The value of <AspNetCoreHostingModel> is case insensitive, so inprocess and outofprocess are valid values.

Ist die <AspNetCoreHostingModel>-Eigenschaft nicht in der Datei vorhanden, ist OutOfProcess der Standardwert.If the <AspNetCoreHostingModel> property isn't present in the file, the default value is OutOfProcess.

Die folgenden Merkmale treffen für In-Process-Hosting zu:The following characteristics apply when hosting in-process:

  • Der IIS-HTTP-Server (IISHttpServer) wird anstelle des Kestrel-Servers verwendet.IIS HTTP Server (IISHttpServer) is used instead of Kestrel server. Für In-Process ruft CreateDefaultBuilderUseIIS auf zu:For in-process, CreateDefaultBuilder calls UseIIS to:

    • Registrieren des IISHttpServer.Register the IISHttpServer.
    • Konfigurieren des Ports und des Basispfads, den der Server überwachen soll, wenn er hinter dem ASP.NET Core-Modul ausgeführt wird.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
    • Konfigurieren des Hosts zum Erfassen von Startfehlern.Configure the host to capture startup errors.
  • Das RequestTimeout-Attribut trifft auf In-Process-Hosting nicht zu.The requestTimeout attribute doesn't apply to in-process hosting.

  • Das gemeinsame Verwenden eines Anwendungspools durch mehrere Apps wird nicht unterstützt.Sharing an app pool among apps isn't supported. Verwenden Sie einen Anwendungspool pro App.Use one app pool per 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.When using Web Deploy or manually placing an app_offline.htm file in the deployment, the app might not shut down immediately if there's an open connection. Beispielsweise kann eine Websocketverbindung eine Verzögerung beim Herunterfahren der App bewirken.For example, a websocket connection may delay app shut down.

  • Die Architektur (Bitbreite) der App und der installierten Runtime (x64 oder x86) müssen mit der Architektur des Anwendungspools übereinstimmen.The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool.

  • Verbindungstrennungen von Clients werden erkannt.Client disconnects are detected. Das Abbruchtoken HttpContext.RequestAborted wird abgebrochen, wenn die Verbindung mit dem Client getrennt wird.The HttpContext.RequestAborted cancellation token is cancelled when the client disconnects.

  • 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).In ASP.NET Core 2.2.1 or earlier, GetCurrentDirectory returns the worker directory of the process started by IIS rather than the app's directory (for example, C:\Windows\System32\inetsrv for w3wp.exe).

    Den Beispielcode zum Festlegen des aktuellen App-Verzeichnisses finden Sie in der Klasse CurrentDirectoryHelpers.For sample code that sets the app's current directory, see the CurrentDirectoryHelpers class. Rufen Sie die SetCurrentDirectory-Methode auf.Call the SetCurrentDirectory method. Nachfolgende Aufrufe von GetCurrentDirectory stellen das App-Verzeichnis bereit.Subsequent calls to GetCurrentDirectory provide the app's directory.

  • Beim In-Process-Hosting wird AuthenticateAsync nicht intern aufgerufen, um einen Benutzer zu initialisieren.When hosting in-process, AuthenticateAsync isn't called internally to initialize a user. Deshalb ist eine IClaimsTransformation-Implementierung, die verwendet wird, um Ansprüche nach jeder Authentifizierung zu transformieren, nicht standardmäßig aktiviert.Therefore, an IClaimsTransformation implementation used to transform claims after every authentication isn't activated by default. Rufen Sie AddAuthentication auf, um Authentifizierungsdienste hinzuzufügen, wenn Ansprüche mit einer IClaimsTransformation-Implementierung transformiert werden:When transforming claims with an IClaimsTransformation implementation, call AddAuthentication to add authentication services:

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

Out-of-Process-HostingmodellOut-of-process hosting model

Um eine App für Out-of-Process-Hosting zu konfigurieren, konfigurieren Sie die Projektdatei auf eine der folgenden Weisen:To configure an app for out-of-process hosting, use either of the following approaches in the project file:

  • Geben Sie die <AspNetCoreHostingModel>-Eigenschaft nicht an.Don't specify the <AspNetCoreHostingModel> property. Ist die <AspNetCoreHostingModel>-Eigenschaft nicht in der Datei vorhanden, ist OutOfProcess der Standardwert.If the <AspNetCoreHostingModel> property isn't present in the file, the default value is OutOfProcess.
  • Legen Sie den Wert der <AspNetCoreHostingModel>-Eigenschaft auf OutOfProcess fest (In-Process-Hosting wird mit InProcess festgelegt):Set the value of the <AspNetCoreHostingModel> property to OutOfProcess (in-process hosting is set with InProcess):
<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

Beim Wert wird die Groß-/Kleinschreibung nicht beachtet, sodass inprocess und outofprocess gültige Werte sind.The value is case insensitive, so inprocess and outofprocess are valid values.

Der Kestrel-Server wird anstelle des IIS-HTTP-Servers (IISHttpServer) verwendet.Kestrel server is used instead of IIS HTTP Server (IISHttpServer).

Für Out-of-Process ruft CreateDefaultBuilderUseIISIntegration auf zu:For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:

  • Konfigurieren des Ports und des Basispfads, den der Server überwachen soll, wenn er hinter dem ASP.NET Core-Modul ausgeführt wird.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
  • Konfigurieren des Hosts zum Erfassen von Startfehlern.Configure the host to capture startup errors.

Änderungen am HostmodellHosting model changes

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.If the hostingModel setting is changed in the web.config file (explained in the Configuration with web.config section), the module recycles the worker process for IIS.

Bei IIS Express verwendet das Modul den Arbeitsprozess nicht erneut, sondern löst stattdessen ein ordnungsgemäßes Herunterfahren des aktuellen IIS Express-Prozesses aus.For IIS Express, the module doesn't recycle the worker process but instead triggers a graceful shutdown of the current IIS Express process. Mit der nächsten Anforderung an die App wird ein neuer IIS Express-Prozess erzeugt.The next request to the app spawns a new IIS Express process.

ProzessnameProcess name

Process.GetCurrentProcess().ProcessName meldet w3wp/iisexpress (In-Process) oder dotnet (Out-of-Process).Process.GetCurrentProcess().ProcessName reports w3wp/iisexpress (in-process) or dotnet (out-of-process).

Viele native Module, z.B. die Windows-Authentifizierung, bleiben aktiv.Many native modules, such as Windows Authentication, remain active. Weitere Informationen zu IIS-Modulen, die im ASP.NET Core-Modul aktiv sind, finden Sie unter IIS-Module mit ASP.NET Core.To learn more about IIS modules active with the ASP.NET Core Module, see IIS-Module mit ASP.NET Core.

Das ASP.NET Core-Modul kann außerdem:The ASP.NET Core Module can also:

  • Umgebungsvariablen für den Arbeitsprozess festlegenSet environment variables for the worker process.
  • Die stdout-Ausgabe im Dateispeicher protokollieren, um Probleme beim Start zu behebenLog stdout output to file storage for troubleshooting startup issues.
  • Windows-Authentifizierungstoken weiterleitenForward Windows authentication tokens.

So installieren und verwenden Sie das ASP.NET Core-ModulHow to install and use the ASP.NET Core Module

Anweisungen zum Installieren des ASP.NET Core-Moduls finden Sie unter Installieren des .NET Core-Hostingpakets.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Konfiguration mit der Datei „web.config“Configuration with web.config

Das ASP.NET Core-Modul wurde mit dem aspNetCore-Abschnitt des system.webServer-Knotens in der Datei web.config der Site konfiguriert.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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:The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

<?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:The following web.config is published for a self-contained deployment:

<?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.The InheritInChildApplications property is set to false to indicate that the settings specified within the <location> element aren't inherited by apps that reside in a subdirectory of the app.

Wenn eine App für Azure App Service bereitgestellt wird, wird der Pfad stdoutLogFile auf \\?\%home%\LogFiles\stdout gesetzt.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. Der Pfad speichert stdout-Protokolle zum Ordner LogFiles, einem Speicherort, der automatisch vom Dienst erstellt wird.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Weitere Informationen zur Konfiguration von IIS untergeordneten Anwendungen finden Sie unter Hosten von ASP.NET Core unter Windows mit IIS.For information on IIS sub-application configuration, see Hosten von ASP.NET Core unter Windows mit IIS.

Attribute des aspNetCore-ElementsAttributes of the aspNetCore element

AttributAttribute BeschreibungDescription StandardDefault
arguments

Optionales Zeichenfolgeattribut.Optional string attribute.

Argumente zur ausführbaren Datei, die in processPath angegeben wurde.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Optionales boolesches Attribut.Optional Boolean attribute.

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.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Optionales boolesches Attribut.Optional Boolean attribute.

Wenn TRUE, wird das Token an den untergeordneten Prozess weitergeleitet, der an %ASPNETCORE_PORT% als Header 'MS-ASPNETCORE-WINAUTHTOKEN' pro Anforderung lauscht.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. Es liegt in der Verantwortung des entsprechenden Prozesses, CloseHandle auf dem Token pro Anforderung aufzurufen.It's the responsibility of that process to call CloseHandle on this token per request.

true
hostingModel

Optionales Zeichenfolgeattribut.Optional string attribute.

Gibt das Hostingmodell als In-Process (InProcess/inprocess) oder Out-of-Process (OutOfProcess/outofprocess) an.Specifies the hosting model as in-process (InProcess/inprocess) or out-of-process (OutOfProcess/outofprocess).

OutOfProcess
outofprocess
processesPerApplication

Optionales Ganzzahlattribut.Optional integer attribute.

Gibt die Anzahl der Instanzen des Prozesses aus der Einstellung processPath an, die aus der App gestartet werden können.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

†Für In-Process-Hosting ist dieser Wert auf 1 beschränkt.†For in-process hosting, the value is limited to 1.

Einstellen von processesPerApplication wird nicht empfohlen.Setting processesPerApplication is discouraged. Dieses Attribut wird in einer der nächsten Releases entfernt.This attribute will be removed in a future release.

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

Erforderliches Zeichenfolgenattribut.Required string attribute.

Pfad zur ausführbaren Datei, die einen Prozess startet, der auf HTTP-Anforderungen lauscht.Path to the executable that launches a process listening for HTTP requests. Relative Pfade werden unterstützt.Relative paths are supported. Wenn der Pfad mit . beginnt, gilt er als relativ zum Stammverzeichnis.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Optionales Ganzzahlattribut.Optional integer attribute.

Gibt an, wie viele Abstürze des in ProcessPath angegebenen Prozesses pro Minute zulässig sind.Specifies the number of times the process specified in processPath is allowed to crash per minute. Wenn dieses Limit überschritten wird, beendet das Modul das Starten des Prozesses für den Rest der Minute.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

Bei In-Process-Hosting nicht unterstützt.Not supported with in-process hosting.

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

Optionales TimeSpan-Attribut.Optional timespan attribute.

Gibt an, wie lange das ASP.NET Core-Modul auf eine Antwort des Prozesses wartet, der auf „% ASPNETCORE_PORT“ lauscht.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%.

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.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

Trifft auf In-Process-Hosting nicht zu.Doesn't apply to in-process hosting. Bei In-Process-Hosting wartet das Modul darauf, dass die App die Anforderung verarbeitet.For in-process hosting, the module waits for the app to process the request.

Gültige Werte für Minuten- und Sekundensegmente der Zeichenfolge befinden sich im Bereich 0–59.Valid values for minutes and seconds segments of the string are in the range 0-59. Die Verwendung von 60 im Wert für Minuten- oder Sekundenergebnisse führt zu einem 500 – Interner Serverfehler.Use of 60 in the value for minutes or seconds results in a 500 - Internal Server Error.

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

Optionales Ganzzahlattribut.Optional integer attribute.

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.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

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

Optionales Ganzzahlattribut.Optional integer attribute.

Gibt in Sekunden an, wie lange das Modul darauf wartet, dass die ausführbare Datei einen Prozess startet, der an dem Port lauscht.Duration in seconds that the module waits for the executable to start a process listening on the port. Wenn dieses Zeitlimit überschritten wird, beendet das Modul den Prozess.If this time limit is exceeded, the module kills the process. 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.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Der Wert 0 (null) wird nicht als unendliches Timeout angesehen.A value of 0 (zero) is not considered an infinite timeout.

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

Optionales boolesches Attribut.Optional Boolean attribute.

Wenn TRUE, werden stdout und stderr für den Prozess, der in processPath angegeben wurde, zu der Datei weitergeleitet, die in stdoutLogFile angegeben wurde.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Optionales Zeichenfolgeattribut.Optional string attribute.

Gibt den relativen oder absoluten Pfad an, für den stdout und stderr aus dem in ProcessPath angegebenen Prozess protokolliert wurden.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Relative Pfade sind relativ zum Stamm der Site.Relative paths are relative to the root of the site. Jeder mit . beginnende Pfad ist zum Stammverzeichnis relativ, und alle anderen Pfade werden als absolute Pfade behandelt.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Ordner, die im Pfad angegeben werden, werden vom Modul erstellt, wenn die Protokolldatei erstellt wird.Any folders provided in the path are created by the module when the log file is created. Mithilfe von Unterstrichtrennzeichen werden ein Zeitstempel, eine Prozess-ID und eine Dateierweiterung ( .log) dem letzten Segment des Pfads stdoutlogfile hinzugefügt.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. Wenn .\logs\stdout als Wert angegeben wird, wird ein stdout-Beispielprotokoll als stdout_20180205194132_1934.log im Ordner logs gespeichert, sofern es am 2.5.2018 um 19:41:32 mit Prozess-ID 1934 gespeichert wurde.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Festlegen von UmgebungsvariablenSetting environment variables

Umgebungsvariablen können für den Prozess im Attribut processPath angegeben werden.Environment variables can be specified for the process in the processPath attribute. Geben Sie eine Umgebungsvariable mit dem untergeordneten Element <environmentVariable> eines <environmentVariables>-Auflistungselements an.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element. In diesem Abschnitt festgelegte Umgebungsvariablen haben Vorrang vor Systemumgebungsvariablen.Environment variables set in this section take precedence over system environment variables.

Im folgenden Beispiel werden zwei Umgebungsvariablen festgelegt.The following example sets two environment variables. ASPNETCORE_ENVIRONMENT konfiguriert die Umgebung der App als Development.ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

<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 Einbeziehen der <EnvironmentName>-Eigenschaft in das Veröffentlichungsprofil (PUBXML) oder eine Projektdatei.An alternative to setting the environment directly in web.config is to include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Dieser Ansatz legt die Umgebung in web.config fest, wenn das Projekt veröffentlicht wird:This approach sets the environment in web.config when the project is published:

<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.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_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.If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. 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.If the app is still running after the number of seconds defined in shutdownTimeLimit, the ASP.NET Core Module kills the running process.

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.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Wenn die Datei app_offline.htm entfernt wurde, wird die App von der nächsten Anforderung gestartet.When the app_offline.htm file is removed, the next request starts the app.

Beim Verwenden des Out-of-Process-Hostingmodells wird die App möglicherweise nicht sofort heruntergefahren, wenn eine offene Verbindung besteht.When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. Beispielsweise kann eine Websocketverbindung eine Verzögerung beim Herunterfahren der App bewirken.For example, a websocket connection may delay app shut down.

Startfehler-SeiteStart-up error page

Sowohl In-Process- als auch Out-of-Process-Hosting erzeugen benutzerdefinierte Fehlerseiten, wenn die App nicht gestartet werden kann.Both in-process and out-of-process hosting produce custom error pages when they fail to start the app.

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.If the ASP.NET Core Module fails to find either the in-process or out-of-process request handler, a 500.0 - In-Process/Out-Of-Process Handler Load Failure status code page appears.

Wenn das ASP.NET Core-Modul beim In-Process-Hosting die App nicht starten kann, wird die Statuscodeseite 500.30: Fehler beim Starten angezeigt.For in-process hosting if the ASP.NET Core Module fails to start the app, a 500.30 - Start Failure status code page appears.

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.For out-of-process hosting if the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 - Process Failure status code page appears.

Um diese Seite zu unterdrücken und zur standardmäßigen IIS-5xx-Statuscodeseite zurückzukehren, verwenden Sie das Attribut disableStartUpErrorPage.To suppress this page and revert to the default IIS 5xx status code page, use the disableStartUpErrorPage attribute. Weitere Informationen zum Konfigurieren von benutzerdefinierten Fehlermeldungen finden Sie unter HTTP-Fehler <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Protokollerstellung und WeiterleitungLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Ordner, die im stdoutLogFile-Pfad angegeben werden, werden vom Modul erstellt, wenn die Protokolldatei erstellt wird.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Protokolle werden nur dann rotiert, wenn die Prozesswiederverwendung/der Prozessneustart stattfindet.Logs aren't rotated, unless process recycling/restart occurs. Der Hoster ist für die Begrenzung des Speicherplatzes zuständig, den die Protokolle nutzen.It's the responsibility of the hoster to limit the disk space the logs consume.

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.Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

Verwenden Sie das Protokoll „stdout“ nicht zu allgemeinen App-Protokollierungszwecken.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Weitere Informationen finden Sie im Artikel zur Protokollierung von Drittanbietern.For more information, see third-party logging providers.

Ein Zeitstempel und eine Dateierweiterung werden automatisch hinzugefügt, wenn die Protokolldatei erstellt wird.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

Wenn stdoutLogEnabled „false“ ist, werden Fehler beim App-Start erfasst und in das Ereignisprotokoll mit bis zu 30 KB ausgegeben.If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. Nach dem Start werden alle zusätzlichen Protokolle verworfen.After startup, all additional logs are discarded.

Das folgende Beispielelement aspNetCore konfiguriert die stdout-Protokollierung im relativen .\log\-Pfad.The following sample aspNetCore element configures stdout logging at the relative path .\log\. Vergewissern Sie sich, dass die Identität des AppPool-Benutzers über die Berechtigung zum Schreiben in den angegebenen Pfad verfügt.Confirm that the AppPool user identity has permission to write to the path provided.

<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.When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout. Die Umgebungsvariable %home ist für Apps vordefiniert, die von Azure App Service gehostet werden.The %home environment variable is predefined for apps hosted by Azure App Service.

Weitere Informationen zu Pfadformaten finden Sie unter Formate von Dateipfaden unter Windows-Systemen.For more information on path formats, see File path formats on Windows systems.

Erweiterte DiagnoseprotokolleEnhanced diagnostic logs

Das ASP.NET Core-Modul kann so konfiguriert werden, dass es erweiterte Diagnoseprotokolle bereitstellt.The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Fügen Sie dem <aspNetCore>-Element in der web.config-Datei das <handlerSettings>-Element hinzu. Wenn debugLevel auf TRACE festgelegt wird, werden genauere Diagnoseinformationen zur Verfügung gestellt:Add the <handlerSettings> element to the <aspNetCore> element in web.config. Setting the debugLevel to TRACE exposes a higher fidelity of diagnostic information:

<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.Folders in the path provided to the <handlerSetting> value (logs in the preceding example) aren't created by the module automatically and should pre-exist in the deployment. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

debugLevel-Werte können sowohl die Ebene als auch den Speicherort enthalten.Debug level (debugLevel) values can include both the level and the location.

Ebenen (von der geringsten zur höchsten Genauigkeit):Levels (in order from least to most verbose):

  • ERRORERROR
  • WARNINGWARNING
  • INFOINFO
  • TRACETRACE

Speicherorte (mehrere Speicherorte sind zulässig):Locations (multiple locations are permitted):

  • CONSOLECONSOLE
  • EVENTLOGEVENTLOG
  • DATEIFILE

Die Handlereinstellungen können auch über Umgebungsvariablen angegeben werden:The handler settings can also be provided via environment variables:

  • ASPNETCORE_MODULE_DEBUG_FILE: Dies ist der Pfad zur Debugprotokolldatei.ASPNETCORE_MODULE_DEBUG_FILE: Path to the debug log file. (Standard: aspnetcore-debug.log)(Default: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG: Dies ist die Einstellung der Debugebene.ASPNETCORE_MODULE_DEBUG: Debug level setting.

Warnung

Lassen Sie die Debugprotokollierung nicht länger als erforderlich für die Bereitstellung aktiviert, wenn Sie einen Fehler beheben.Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. Die Größe des Protokolls ist nicht beschränkt.The size of the log isn't limited. Wenn die Debugprotokollierung aktiviert bleibt, kann der verfügbare Speicherplatz aufgebraucht werden, und der Server- oder App-Dienst können abstürzen.Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

Konfiguration mit der Datei „web.config“ enthält ein Beispiel für das aspNetCore-Element in der Datei web.config.See Configuration with web.config for an example of the aspNetCore element in the web.config file.

Die Proxykonfiguration verwendet das HTTP-Protokoll und ein PaarbildungstokenProxy configuration uses HTTP protocol and a pairing token

Gilt nur für Out-of-Process-Hosting.Only applies to out-of-process hosting.

Der Proxy, der zwischen dem ASP.NET Core-Modul und Kestrel erstellt wurde, verwendet das HTTP-Protokoll.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. Es gibt kein Risiko für Lauschangriffe auf den Datenverkehr zwischen dem Modul und Kestrel von einem Speicherort außerhalb des Servers.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

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.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. Das Paarbildungstoken wurde durch das Modul erstellt und in einer Umgebungsvariablen (ASPNETCORE_TOKEN) festgelegt.The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. Das Paarbildungstoken ist auch bei jeder Proxyanforderung in einem Header (MS-ASPNETCORE-TOKEN) festgelegt.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. IIS-Middleware überprüft jede erhaltene Anforderung, um sicherzustellen, dass der Headerwert des Paarbildungstokens dem Wert der Umgebungsvariablen entspricht.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Wenn die Tokenwerte nicht übereinstimmen, wird die Anforderung protokolliert und abgelehnt.If the token values are mismatched, the request is logged and rejected. 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.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Wenn ein Angreifer den Wert des Paarbildungstokens nicht kennt, kann er keine Anforderungen einreichen, die die IIS-Middleware-Prüfung umgehen.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

ASP.NET Core-Modul mit einer IIS-FreigabekonfigurationASP.NET Core Module with an IIS Shared Configuration

Das Installationsprogramm des ASP.NET Core-Moduls wird mit den Berechtigungen des TrustedInstaller-Kontos ausgeführt.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

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:When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 1:

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:When the path to the shared configuration isn't on the same machine as the IIS installation, follow these steps:

  1. Deaktivieren Sie die IIS-Freigabekonfiguration.Disable the IIS Shared Configuration.
  2. Führen Sie den Installer aus.Run the installer.
  3. Exportieren Sie die aktualisierte Datei applicationHost.config auf die Freigabe.Export the updated applicationHost.config file to the share.
  4. Aktivieren Sie die IIS-Freigabekonfiguration erneut.Re-enable the IIS Shared Configuration.

Version des Moduls und Installerprotokolle des HostingpaketsModule version and Hosting Bundle installer logs

So ermitteln Sie die Version des installierten ASP.NET Core-Moduls:To determine the version of the installed ASP.NET Core Module:

  1. Navigieren Sie auf dem Hostsystem zu %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Suchen Sie die Datei aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Klicken Sie mit der rechten Maustaste auf die Datei, und wählen Sie im Dropdownmenü die Option Eigenschaften aus.Right-click the file and select Properties from the contextual menu.
  4. Wählen Sie die Registerkarte Details aus. Die Dateiversion und die Produktversion stellen die installierte Version des Moduls dar.Select the Details tab. The File version and Product version represent the installed version of the module.

Die Installer-Protokolle des Hostingpakets für das Modul finden Sie unter C:\Benutzer\%UserName%\AppData\Local\Temp. Die Datei heißt dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Dateispeicherorte für Modul, Schema und KonfigurationModule, schema, and configuration file locations

ModulModule

IIS (x86/amd64):IIS (x86/amd64):

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

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

  • %ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

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

IIS Express (x86/amd64):IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\aspnetcore.dll

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

  • %ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

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

SchemaSchema

IISIIS

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

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

IIS ExpressIIS Express

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

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

KonfigurationConfiguration

IISIIS

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

IIS ExpressIIS Express

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

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

Den Speicherort dieser Dateien finden Sie, indem Sie aspnetcore in der Datei applicationHost.config suchen.The files can be found by searching for aspnetcore in the applicationHost.config file.

Das ASP.NET Core-Modul ist ein natives IIS-Modul, das in die IIS-Pipeline integriert wird, um Webanforderungen an Back-End-ASP.NET Core-Apps weiterzuleiten.The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to forward web requests to backend ASP.NET Core apps.

Unterstützte Windows-Versionen:Supported Windows versions:

  • Windows 7 oder höherWindows 7 or later
  • Windows Server 2008 R2 oder höherWindows Server 2008 R2 or later

Das Modul funktioniert nur mit Kestrel.The module only works with Kestrel. Das Modul ist nicht mit HTTP.sys kompatibel.The module is incompatible with HTTP.sys.

Da ASP.NET Core-Apps in einem Prozess getrennt vom IIS-Arbeitsprozess ausgeführt werden, führt das Modul auch Prozessverwaltung durch.Because ASP.NET Core apps run in a process separate from the IIS worker process, the module also handles process management. 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.The module starts the process for the ASP.NET Core app when the first request arrives and restarts the app if it crashes. 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.This is essentially the same behavior as seen with ASP.NET 4.x apps that run in-process in IIS that are managed by the Windows Process Activation Service (WAS).

Das folgende Diagramm zeigt die Beziehung zwischen IIS, dem ASP.NET Core-Modul und einer App:The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app:

ASP.NET Core-Modul

Anforderungen gehen aus dem Internet an den Treiber „HTTP.sys“ ein, der im Kernelmodus betrieben wird.Requests arrive from the web to the kernel-mode HTTP.sys driver. Der Treiber leitet die Anforderungen an IIS auf dem konfigurierten Port der Webseite weiter, normalerweise 80 (HTTP) oder 443 (HTTPS).The driver routes the requests to IIS on the website's configured port, usually 80 (HTTP) or 443 (HTTPS). Das Modul leitet die Anforderung an Kestrel auf einem zufälligen Port der App weiter, der nicht Port 80 oder 443 entspricht.The module forwards the requests to Kestrel on a random port for the app, which isn't port 80 or 443.

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.The module specifies the port via an environment variable at startup, and the IIS Integration Middleware configures the server to listen on http://localhost:{port}. Zusätzliche Überprüfungen werden durchgeführt. Anforderungen, die nicht vom Modul stammen, werden abgelehnt.Additional checks are performed, and requests that don't originate from the module are rejected. Das Modul unterstützt die HTTPS-Weiterleitung nicht. Deshalb werden Anforderungen über HTTP weitergeleitet, selbst wenn sie von IIS über HTTPS empfangen wurden.The module doesn't support HTTPS forwarding, so requests are forwarded over HTTP even if received by IIS over HTTPS.

Nachdem Kestrel die Anforderung vom Modul erhalten hat, wird die Anforderung in die Middleware-Pipeline von ASP.NET Core eingestellt.After Kestrel picks up the request from the module, the request is pushed into the ASP.NET Core middleware pipeline. Die Middleware-Pipeline behandelt die Anforderung und gibt sie als HttpContext-Instanz an die App-Logik weiter.The middleware pipeline handles the request and passes it on as an HttpContext instance to the app's logic. Die durch IIS-Integration hinzugefügte Middleware aktualisiert das Schema, die Remote-IP und die Pfadbasis, um der Weiterleitung der Anforderung an Kestrel Rechnung zu tragen.Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for forwarding the request to Kestrel. 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.The app's response is passed back to IIS, which pushes it back out to the HTTP client that initiated the request.

Viele native Module, z.B. die Windows-Authentifizierung, bleiben aktiv.Many native modules, such as Windows Authentication, remain active. Weitere Informationen zu IIS-Modulen, die im ASP.NET Core-Modul aktiv sind, finden Sie unter IIS-Module mit ASP.NET Core.To learn more about IIS modules active with the ASP.NET Core Module, see IIS-Module mit ASP.NET Core.

Das ASP.NET Core-Modul kann außerdem:The ASP.NET Core Module can also:

  • Umgebungsvariablen für den Arbeitsprozess festlegenSet environment variables for the worker process.
  • Die stdout-Ausgabe im Dateispeicher protokollieren, um Probleme beim Start zu behebenLog stdout output to file storage for troubleshooting startup issues.
  • Windows-Authentifizierungstoken weiterleitenForward Windows authentication tokens.

So installieren und verwenden Sie das ASP.NET Core-ModulHow to install and use the ASP.NET Core Module

Anweisungen zum Installieren des ASP.NET Core-Moduls finden Sie unter Installieren des .NET Core-Hostingpakets.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Konfiguration mit der Datei „web.config“Configuration with web.config

Das ASP.NET Core-Modul wurde mit dem aspNetCore-Abschnitt des system.webServer-Knotens in der Datei web.config der Site konfiguriert.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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:The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

<?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:The following web.config is published for a self-contained deployment:

<?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.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. Der Pfad speichert stdout-Protokolle zum Ordner LogFiles, einem Speicherort, der automatisch vom Dienst erstellt wird.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Weitere Informationen zur Konfiguration von IIS untergeordneten Anwendungen finden Sie unter Hosten von ASP.NET Core unter Windows mit IIS.For information on IIS sub-application configuration, see Hosten von ASP.NET Core unter Windows mit IIS.

Attribute des aspNetCore-ElementsAttributes of the aspNetCore element

AttributAttribute BeschreibungDescription StandardDefault
arguments

Optionales Zeichenfolgeattribut.Optional string attribute.

Argumente zur ausführbaren Datei, die in processPath angegeben wurde.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Optionales boolesches Attribut.Optional Boolean attribute.

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.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Optionales boolesches Attribut.Optional Boolean attribute.

Wenn TRUE, wird das Token an den untergeordneten Prozess weitergeleitet, der an %ASPNETCORE_PORT% als Header 'MS-ASPNETCORE-WINAUTHTOKEN' pro Anforderung lauscht.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. Es liegt in der Verantwortung des entsprechenden Prozesses, CloseHandle auf dem Token pro Anforderung aufzurufen.It's the responsibility of that process to call CloseHandle on this token per request.

true
processesPerApplication

Optionales Ganzzahlattribut.Optional integer attribute.

Gibt die Anzahl der Instanzen des Prozesses aus der Einstellung processPath an, die aus der App gestartet werden können.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

Einstellen von processesPerApplication wird nicht empfohlen.Setting processesPerApplication is discouraged. Dieses Attribut wird in einer der nächsten Releases entfernt.This attribute will be removed in a future release.

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

Erforderliches Zeichenfolgenattribut.Required string attribute.

Pfad zur ausführbaren Datei, die einen Prozess startet, der auf HTTP-Anforderungen lauscht.Path to the executable that launches a process listening for HTTP requests. Relative Pfade werden unterstützt.Relative paths are supported. Wenn der Pfad mit . beginnt, gilt er als relativ zum Stammverzeichnis.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Optionales Ganzzahlattribut.Optional integer attribute.

Gibt an, wie viele Abstürze des in ProcessPath angegebenen Prozesses pro Minute zulässig sind.Specifies the number of times the process specified in processPath is allowed to crash per minute. Wenn dieses Limit überschritten wird, beendet das Modul das Starten des Prozesses für den Rest der Minute.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

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

Optionales TimeSpan-Attribut.Optional timespan attribute.

Gibt an, wie lange das ASP.NET Core-Modul auf eine Antwort des Prozesses wartet, der auf „% ASPNETCORE_PORT“ lauscht.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%.

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.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

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

Optionales Ganzzahlattribut.Optional integer attribute.

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.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

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

Optionales Ganzzahlattribut.Optional integer attribute.

Gibt in Sekunden an, wie lange das Modul darauf wartet, dass die ausführbare Datei einen Prozess startet, der an dem Port lauscht.Duration in seconds that the module waits for the executable to start a process listening on the port. Wenn dieses Zeitlimit überschritten wird, beendet das Modul den Prozess.If this time limit is exceeded, the module kills the process. 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.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Der Wert 0 (null) wird nicht als unendliches Timeout angesehen.A value of 0 (zero) is not considered an infinite timeout.

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

Optionales boolesches Attribut.Optional Boolean attribute.

Wenn TRUE, werden stdout und stderr für den Prozess, der in processPath angegeben wurde, zu der Datei weitergeleitet, die in stdoutLogFile angegeben wurde.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Optionales Zeichenfolgeattribut.Optional string attribute.

Gibt den relativen oder absoluten Pfad an, für den stdout und stderr aus dem in ProcessPath angegebenen Prozess protokolliert wurden.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Relative Pfade sind relativ zum Stamm der Site.Relative paths are relative to the root of the site. Jeder mit . beginnende Pfad ist zum Stammverzeichnis relativ, und alle anderen Pfade werden als absolute Pfade behandelt.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Alle im Pfad angegebenen Ordner müssen vorhanden sein, damit das Modul die Protokolldatei erstellt.Any folders provided in the path must exist in order for the module to create the log file. Mithilfe von Unterstrichtrennzeichen werden ein Zeitstempel, eine Prozess-ID und eine Dateierweiterung ( .log) dem letzten Segment des Pfads stdoutlogfile hinzugefügt.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. Wenn .\logs\stdout als Wert angegeben wird, wird ein stdout-Beispielprotokoll als stdout_20180205194132_1934.log im Ordner logs gespeichert, sofern es am 2.5.2018 um 19:41:32 mit Prozess-ID 1934 gespeichert wurde.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Festlegen von UmgebungsvariablenSetting environment variables

Umgebungsvariablen können für den Prozess im Attribut processPath angegeben werden.Environment variables can be specified for the process in the processPath attribute. Geben Sie eine Umgebungsvariable mit dem untergeordneten Element <environmentVariable> eines <environmentVariables>-Auflistungselements an.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element.

Warnung

In diesem Abschnitt festgelegte Umgebungsvariablen stehen im Konflikt mit Systemumgebungsvariablen gleichen Namens.Environment variables set in this section conflict with system environment variables set with the same name. Wenn eine Umgebungsvariable sowohl in der Datei web.config als auch auf Systemebene in Windows festgelegt ist, wird der Wert aus der Datei web.config dem Wert der Systemumgebungsvariablen angefügt (z.B. ASPNETCORE_ENVIRONMENT: Development;Development), um zu verhindern, dass die App startet.If an environment variable is set in both the web.config file and at the system level in Windows, the value from the web.config file becomes appended to the system environment variable value (for example, ASPNETCORE_ENVIRONMENT: Development;Development), which prevents the app from starting.

Im folgenden Beispiel werden zwei Umgebungsvariablen festgelegt.The following example sets two environment variables. ASPNETCORE_ENVIRONMENT konfiguriert die Umgebung der App als Development.ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

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

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.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_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.If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. 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.If the app is still running after the number of seconds defined in shutdownTimeLimit, the ASP.NET Core Module kills the running process.

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.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Wenn die Datei app_offline.htm entfernt wurde, wird die App von der nächsten Anforderung gestartet.When the app_offline.htm file is removed, the next request starts the app.

Startfehler-SeiteStart-up error page

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.If the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 - Process Failure status code page appears. Um diese Seite zu unterdrücken und zur IIS-502-Sandardstatuscodeseite zurückzukehren, verwenden Sie das Attribut disableStartUpErrorPage.To suppress this page and revert to the default IIS 502 status code page, use the disableStartUpErrorPage attribute. Weitere Informationen zum Konfigurieren von benutzerdefinierten Fehlermeldungen finden Sie unter HTTP-Fehler <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Statuscodeseite „502.5: Prozessfehler“

Protokollerstellung und WeiterleitungLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Ordner, die im stdoutLogFile-Pfad angegeben werden, werden vom Modul erstellt, wenn die Protokolldatei erstellt wird.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Protokolle werden nur dann rotiert, wenn die Prozesswiederverwendung/der Prozessneustart stattfindet.Logs aren't rotated, unless process recycling/restart occurs. Der Hoster ist für die Begrenzung des Speicherplatzes zuständig, den die Protokolle nutzen.It's the responsibility of the hoster to limit the disk space the logs consume.

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.Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

Verwenden Sie das Protokoll „stdout“ nicht zu allgemeinen App-Protokollierungszwecken.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Weitere Informationen finden Sie im Artikel zur Protokollierung von Drittanbietern.For more information, see third-party logging providers.

Ein Zeitstempel und eine Dateierweiterung werden automatisch hinzugefügt, wenn die Protokolldatei erstellt wird.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

Das folgende Beispielelement aspNetCore konfiguriert die stdout-Protokollierung im relativen .\log\-Pfad.The following sample aspNetCore element configures stdout logging at the relative path .\log\. Vergewissern Sie sich, dass die Identität des AppPool-Benutzers über die Berechtigung zum Schreiben in den angegebenen Pfad verfügt.Confirm that the AppPool user identity has permission to write to the path provided.

<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.When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout. Die Umgebungsvariable %home ist für Apps vordefiniert, die von Azure App Service gehostet werden.The %home environment variable is predefined for apps hosted by Azure App Service.

Informationen zum Erstellen von Protokollierungsfilterregeln finden Sie in den Abschnitten Konfiguration und Protokollfilterung der Dokumentation zur ASP.NET Core-Protokollierung.To create logging filter rules, see the Configuration and Log filtering sections of the ASP.NET Core logging documentation.

Weitere Informationen zu Pfadformaten finden Sie unter Formate von Dateipfaden unter Windows-Systemen.For more information on path formats, see File path formats on Windows systems.

Die Proxykonfiguration verwendet das HTTP-Protokoll und ein PaarbildungstokenProxy configuration uses HTTP protocol and a pairing token

Der Proxy, der zwischen dem ASP.NET Core-Modul und Kestrel erstellt wurde, verwendet das HTTP-Protokoll.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. Es gibt kein Risiko für Lauschangriffe auf den Datenverkehr zwischen dem Modul und Kestrel von einem Speicherort außerhalb des Servers.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

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.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. Das Paarbildungstoken wurde durch das Modul erstellt und in einer Umgebungsvariablen (ASPNETCORE_TOKEN) festgelegt.The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. Das Paarbildungstoken ist auch bei jeder Proxyanforderung in einem Header (MS-ASPNETCORE-TOKEN) festgelegt.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. IIS-Middleware überprüft jede erhaltene Anforderung, um sicherzustellen, dass der Headerwert des Paarbildungstokens dem Wert der Umgebungsvariablen entspricht.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Wenn die Tokenwerte nicht übereinstimmen, wird die Anforderung protokolliert und abgelehnt.If the token values are mismatched, the request is logged and rejected. 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.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Wenn ein Angreifer den Wert des Paarbildungstokens nicht kennt, kann er keine Anforderungen einreichen, die die IIS-Middleware-Prüfung umgehen.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

ASP.NET Core-Modul mit einer IIS-FreigabekonfigurationASP.NET Core Module with an IIS Shared Configuration

Das Installationsprogramm des ASP.NET Core-Moduls wird mit den Berechtigungen des TrustedInstaller-Kontos ausgeführt.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

Wenn Sie eine IIS-Freigabekonfiguration verwenden, gehen Sie folgendermaßen vor:When using an IIS Shared Configuration, follow these steps:

  1. Deaktivieren Sie die IIS-Freigabekonfiguration.Disable the IIS Shared Configuration.
  2. Führen Sie den Installer aus.Run the installer.
  3. Exportieren Sie die aktualisierte Datei applicationHost.config auf die Freigabe.Export the updated applicationHost.config file to the share.
  4. Aktivieren Sie die IIS-Freigabekonfiguration erneut.Re-enable the IIS Shared Configuration.

Version des Moduls und Installerprotokolle des HostingpaketsModule version and Hosting Bundle installer logs

So ermitteln Sie die Version des installierten ASP.NET Core-Moduls:To determine the version of the installed ASP.NET Core Module:

  1. Navigieren Sie auf dem Hostsystem zu %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Suchen Sie die Datei aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Klicken Sie mit der rechten Maustaste auf die Datei, und wählen Sie im Dropdownmenü die Option Eigenschaften aus.Right-click the file and select Properties from the contextual menu.
  4. Wählen Sie die Registerkarte Details aus. Die Dateiversion und die Produktversion stellen die installierte Version des Moduls dar.Select the Details tab. The File version and Product version represent the installed version of the module.

Die Installer-Protokolle des Hostingpakets für das Modul finden Sie unter C:\Benutzer\%UserName%\AppData\Local\Temp. Die Datei heißt dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Dateispeicherorte für Modul, Schema und KonfigurationModule, schema, and configuration file locations

ModulModule

IIS (x86/amd64):IIS (x86/amd64):

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

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

IIS Express (x86/amd64):IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\aspnetcore.dll

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

SchemaSchema

IISIIS

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

IIS ExpressIIS Express

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

KonfigurationConfiguration

IISIIS

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

IIS ExpressIIS Express

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

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

Den Speicherort dieser Dateien finden Sie, indem Sie aspnetcore in der Datei applicationHost.config suchen.The files can be found by searching for aspnetcore in the applicationHost.config file.

Zusätzliche RessourcenAdditional resources