From 643da263f3d2b2bee93fb8f763f62f2d09d40d45 Mon Sep 17 00:00:00 2001 From: Justin Kotalik Date: Mon, 5 Nov 2018 15:23:02 -0800 Subject: [PATCH] Update ANCM host and deploy topic (#9452) --- .../host-and-deploy/aspnet-core-module.md | 105 +++++++++++++----- 1 file changed, 78 insertions(+), 27 deletions(-) diff --git a/aspnetcore/host-and-deploy/aspnet-core-module.md b/aspnetcore/host-and-deploy/aspnet-core-module.md index bdc667b13e..8a61175d90 100644 --- a/aspnetcore/host-and-deploy/aspnet-core-module.md +++ b/aspnetcore/host-and-deploy/aspnet-core-module.md @@ -9,7 +9,7 @@ uid: host-and-deploy/aspnet-core-module --- # ASP.NET Core Module configuration reference -By [Luke Latham](https://github.com/guardrex), [Rick Anderson](https://twitter.com/RickAndMSFT), and [Sourabh Shirhatti](https://twitter.com/sshirhatti) +By [Luke Latham](https://github.com/guardrex), [Rick Anderson](https://twitter.com/RickAndMSFT), [Sourabh Shirhatti](https://twitter.com/sshirhatti), and [Justin Kotalik](https://github.com/jkotalik) This document provides instructions on how to configure the ASP.NET Core Module for hosting ASP.NET Core apps. For an introduction to the ASP.NET Core Module and installation instructions, see the [ASP.NET Core Module overview](xref:fundamentals/servers/aspnet-core-module). @@ -21,11 +21,11 @@ For apps running on .NET Core 2.2 or later, the module supports an in-process ho In-procsess hosting is opt-in for existing apps, but [dotnet new](/dotnet/core/tools/dotnet-new) templates default to the in-process hosting model for all IIS and IIS Express scenarios. -To configure an app for in-process hosting, add the `` property to the app's project file with a value of `inprocess` (out-of-process hosting is set with `outofprocess`): +To configure an app for in-process hosting, add the `` property to the app's project file (for example, *MyApp.csproj*) with a value of `inprocess` (out-of-process hosting is set with `outofprocess`): ```xml - inprocess + inprocess ``` @@ -45,6 +45,8 @@ The following characteristics apply when hosting in-process: * Client disconnects are detected. The [HttpContext.RequestAborted](xref:Microsoft.AspNetCore.Http.HttpContext.RequestAborted*) cancellation token is cancelled when the client disconnects. +* `Directory.GetCurrentDirectory()` returns the worker directory of the process started by IIS rather than the application directory (for example, *C:\Windows\System32\inetsrv* for *w3wp.exe*). + ### Hosting model changes If the `hostingModel` setting is changed in the *web.config* file (explained in the [Configuration with web.config](#configuration-with-webconfig) section), the module recycles the worker process for IIS. @@ -53,7 +55,7 @@ For IIS Express, the module doesn't recycle the worker process but instead trigg ### Process name -`Process.GetCurrentProcess().ProcessName` reports either `w3wp` (in-process) or `dotnet` (out-of-process). +`Process.GetCurrentProcess().ProcessName` reports `w3wp`/`iisexpress` (in-process) or `dotnet` (out-of-process). ::: moniker-end @@ -68,16 +70,18 @@ The following *web.config* file is published for a [framework-dependent deployme ```xml - - - - - - + + + + + + + + ``` @@ -109,15 +113,17 @@ The following *web.config* is published for a [self-contained deployment](/dotne ```xml - - - - - - + + + + + + + + ``` @@ -260,14 +266,26 @@ When using the out-of-process hosting model, the app might not shut down immedia ::: moniker range=">= aspnetcore-2.2" -*Only applies to out-of-process hosting.* +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>](/iis/configuration/system.webServer/httpErrors/). ::: moniker-end -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 502 status code page, use the `disableStartUpErrorPage` attribute. For more information on configuring custom error messages, see [HTTP Errors ``](/iis/configuration/system.webServer/httpErrors/). +::: moniker range="< aspnetcore-2.2" + +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 502 status code page, use the `disableStartUpErrorPage` attribute. For more information on configuring custom error messages, see [HTTP Errors <httpErrors>](/iis/configuration/system.webServer/httpErrors/). ![502.5 Process Failure Status Code Page](aspnet-core-module/_static/ANCM-502_5.png) +::: moniker-end + ## Log creation and redirection 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 must exist in order for the module to create the log file. The app pool must have write access to the location where the logs are written (use `IIS AppPool\` to provide write permission). @@ -278,6 +296,12 @@ Using the stdout log is only recommended for troubleshooting app startup issues. 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*. +::: moniker range=">= aspnetcore-2.2" + +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. + +::: moniker-end + The following sample `aspNetCore` element configures stdout logging for an app hosted in Azure App Service. A local path or network share path is acceptable for local logging. Confirm that the AppPool user identity has permission to write to the path provided. ::: moniker range=">= aspnetcore-2.2" @@ -393,22 +417,49 @@ The Hosting Bundle installer logs for the module are found at *C:\\Users\\%UserN * %windir%\SysWOW64\inetsrv\aspnetcore.dll +::: moniker range=">= aspnetcore-2.2" + + * %ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll + + * %ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll + +::: moniker-end + **IIS Express (x86/amd64):** * %ProgramFiles%\IIS Express\aspnetcore.dll * %ProgramFiles(x86)%\IIS Express\aspnetcore.dll +::: moniker range=">= aspnetcore-2.2" + + * %ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll + + * %ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll + +::: moniker-end + ### Schema **IIS** * %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml +::: moniker range=">= aspnetcore-2.2" + + * %windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml + +::: moniker-end **IIS Express** * %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml +::: moniker range=">= aspnetcore-2.2" + + * %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml + +::: moniker-end + ### Configuration **IIS** @@ -417,6 +468,6 @@ The Hosting Bundle installer logs for the module are found at *C:\\Users\\%UserN **IIS Express** - * .vs\config\applicationHost.config + * %ProgramFiles%\IIS Express\config\templates\PersonalWebServer\applicationHost.config -The files can be found by searching for *aspnetcore.dll* in the *applicationHost.config* file. For IIS Express, the *applicationHost.config* file won't exist by default. The file is created at *\\\.vs\\config* when starting any web app project in the Visual Studio solution. +The files can be found by searching for *aspnetcore* in the *applicationHost.config* file. \ No newline at end of file