The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:
w3wp.exe), called the in-process hosting model.Supported Windows versions:
When hosting in-process, the module uses an in-process server implementation for IIS, called IIS HTTP Server (IISHttpServer).
When hosting out-of-process, the module only works with Kestrel. The module doesn't function with HTTP.sys.
ASP.NET Core apps default to the in-process hosting model.
The following characteristics apply when hosting in-process:
IIS HTTP Server (IISHttpServer) is used instead of Kestrel server. For in-process, CreateDefaultBuilder calls UseIIS to:
IISHttpServer.The requestTimeout attribute doesn't apply to in-process hosting.
Sharing an app pool among apps isn't supported. Use one app pool per app.
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. For example, a websocket connection may delay app shut down.
The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool.
Client disconnects are detected. The HttpContext.RequestAborted cancellation token is cancelled when the client disconnects.
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).
For sample code that sets the app's current directory, see the CurrentDirectoryHelpers class. Call the SetCurrentDirectory method. Subsequent calls to GetCurrentDirectory provide the app's directory.
When hosting in-process, AuthenticateAsync isn't called internally to initialize a user. Therefore, an IClaimsTransformation implementation used to transform claims after every authentication isn't activated by default. 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();
}
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>
In-process hosting is set with InProcess, which is the default value.
The value of <AspNetCoreHostingModel> is case insensitive, so inprocess and outofprocess are valid values.
Kestrel server is used instead of IIS HTTP Server (IISHttpServer).
For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:
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.
For IIS Express, the module doesn't recycle the worker process but instead triggers a graceful shutdown of the current IIS Express process. The next request to the app spawns a new IIS Express process.
Process.GetCurrentProcess().ProcessName reports w3wp/iisexpress (in-process) or dotnet (out-of-process).
Many native modules, such as Windows Authentication, remain active. To learn more about IIS modules active with the ASP.NET Core Module, see IIS modules with ASP.NET Core.
The ASP.NET Core Module can also:
For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.
The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.
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>
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>
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.
When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.
For information on IIS sub-application configuration, see Host ASP.NET Core on Windows with IIS.
Environment variables can be specified for the process in the processPath attribute. Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element. Environment variables set in this section take precedence over system environment variables.
The following example sets two environment variables in web.config. ASPNETCORE_ENVIRONMENT configures the app's environment to Development. 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 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>
Note
An alternative to setting the environment directly in web.config is to include the <EnvironmentName> property in the publish profile (.pubxml) or project file. This approach sets the environment in web.config when the project is published:
<PropertyGroup>
<EnvironmentName>Development</EnvironmentName>
</PropertyGroup>
Warning
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.
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. If the app is still running after the number of seconds defined in shutdownTimeLimit, the ASP.NET Core Module kills the running process.
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. When the app_offline.htm file is removed, the next request starts the app.
When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. For example, a websocket connection may delay app shut down.
Both in-process and out-of-process hosting produce custom error pages when they fail to start the app.
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.
For in-process hosting if the ASP.NET Core Module fails to start the app, a 500.30 - Start Failure status code page appears.
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.
To suppress this page and revert to the default IIS 5xx status code page, use the disableStartUpErrorPage attribute. For more information on configuring custom error messages, see HTTP Errors <httpErrors>.
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. Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).
Logs aren't rotated, unless process recycling/restart occurs. It's the responsibility of the hoster to limit the disk space the logs consume.
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.
Don't use the stdout log for general app logging purposes. For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. For more information, see third-party logging providers.
A timestamp and file extension are added automatically when the log file is created. 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. 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.
If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. After startup, all additional logs are discarded.
The following sample aspNetCore element configures stdout logging at the relative path .\log\. 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>
When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout. The %home environment variable is predefined for apps hosted by Azure App Service.
To create logging filter rules, see the Configuration and Log filtering sections of the ASP.NET Core logging documentation.
For more information on path formats, see File path formats on Windows systems.
The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. 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>
Any folders in the path (logs in the preceding example) are created by the module when the log file is created. 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).
Debug level (debugLevel) values can include both the level and the location.
Levels (in order from least to most verbose):
Locations (multiple locations are permitted):
The handler settings can also be provided via environment variables:
ASPNETCORE_MODULE_DEBUG_FILE: Path to the debug log file. (Default: aspnetcore-debug.log)ASPNETCORE_MODULE_DEBUG: Debug level setting.Warning
Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. The size of the log isn't limited. Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.
See Configuration with web.config for an example of the aspNetCore element in the web.config file.
Only applies when using the in-process hosting model.
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>
Only applies to out-of-process hosting.
The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.
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. The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.
The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.
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
When the path to the shared configuration isn't on the same machine as the IIS installation, follow these steps:
To determine the version of the installed ASP.NET Core Module:
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.
IIS (x86/amd64):
%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll
%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
IIS Express (x86/amd64):
%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
IIS
%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml
IIS Express
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml
IIS
IIS Express
Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config
The files can be found by searching for aspnetcore in the applicationHost.config file.
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。