diff --git a/aspnet/publishing/iis.rst b/aspnet/publishing/iis.rst index e943264a0ac2..6003a6abaf5e 100644 --- a/aspnet/publishing/iis.rst +++ b/aspnet/publishing/iis.rst @@ -59,11 +59,8 @@ Deploy the Application .. warning:: .NET Core applications are hosted via a reverse-proxy between IIS and the Kestrel server. In order to create the reverse-proxy, the *web.config* file must be present at the content root path (typically the app base path) of the deployed application, which is the website physical path provided to IIS. - Sensitive files exist on the app's physical path, such as *my_application.runtimeconfig.json*, *my_application.xml* (XML Documentation comments), and *my_application.deps.json*. The *web.config* file is required to create the reverse proxy to Kestrel, which prevents IIS from serving these files. **Therefore, it is important that the web.config file is never accidently renamed or removed from the deployment.** + Sensitive files exist on the app's physical path, including subfolders, such as *my_application.runtimeconfig.json*, *my_application.xml* (XML Documentation comments), and *my_application.deps.json*. The *web.config* file is required to create the reverse proxy to Kestrel, which prevents IIS from serving these and other sensitive files. **Therefore, it is important that the web.config file is never accidently renamed or removed from the deployment.** - In order to mitigate the risk of serving sensitive application files if *web.config* were ever accidently renamed or removed, one may add sensitive files to the **Hidden Segments** of **Request Filtering** or add blanket file extension rules to the **File Name Extensions** of **Request Filtering**. See `Hidden Segments \ `__ and `File Name Extensions \ `__ for more information. - - Keep in mind that if you use the **File Name Extensions** approach that your application will not receive requests nor be able to serve any file with that extension, even static files in your **webroot** that you wish to serve (for example, JSON or XML files you have placed in `wwwroot` for legitimate file serving). Therefore, specifically naming sensitive files using the **Hidden Segments** approach may be preferable in most scenarios. In **Hidden Segments**, one would list *my_application.runtimeconfig.json*, *my_application.xml* (if this XML Documentation comments file is present), *my_application.deps.json*, and any other files that are not explicitly excluded by IIS for static file serving. Configure the Website in IIS ---------------------------- @@ -115,8 +112,11 @@ A quick way to determine if the IIS reverse proxy to the Kestrel server is worki Common errors and general troubleshooting instructions: -Issue #1 -^^^^^^^^ +- Installation of the .NET Core Windows Server Hosting Bundle fails with *0x80070002 - The system cannot find the file specified*. + +Troubleshooting: + + - If the server does not have Internet access while installing the server hosting bundle, this exception will ensue when the installer is prevented from obtaining the *Microsoft Visual C++ 2015 Redistributable (x64)* packages online. You may obtain an installer for the packages from the `Microsoft Download Center `__. - **Browser:** No response - **Application Log:** Process 'PROC_ID' failed to start. Port = PORT, Error Code = '-2147023829'. @@ -124,10 +124,7 @@ Issue #1 Troubleshooting: -- If your application uses the `.UseUrls(...)` extension on `WebHostBuilder`, make sure you have positioned the `.UseUrls(...)` extension before the `.UseIISIntegration()` extension on `WebHostBuilder`. `.UseIISIntegration()` must overwrite any values you provide in `.UseUrls(...)` in order for the reverse-proxy to succeed. - -Issue #2 -^^^^^^^^ + - If your application uses the `.UseUrls(...)` extension on `WebHostBuilder`, make sure you have positioned the `.UseUrls(...)` extension before the `.UseIISIntegration()` extension on `WebHostBuilder`. `.UseIISIntegration()` must overwrite any values you provide in `.UseUrls(...)` in order for the reverse-proxy to succeed. - **Browser:** No response - **Application Log:** Faulting module: KERNELBASE.dll Exception code: 0xe0434352 Faulting module path: C:\WINDOWS\system32\KERNELBASE.dll @@ -135,10 +132,7 @@ Issue #2 Troubleshooting: -- If you published a self-contained application, confirm that you didn't set a **platform** in **buildOptions** of *project.json* that conflicts with the publishing RID. For example, do not specify a **platform** of **x86** and publish with an RID of **win81-x64** (**dotnet publish -c Release -r win81-x64**). The project will publish without warning or error but fail with the above logged exceptions on the server. - -Issue #3 -^^^^^^^^ + - If you published a self-contained application, confirm that you didn't set a **platform** in **buildOptions** of *project.json* that conflicts with the publishing RID. For example, do not specify a **platform** of **x86** and publish with an RID of **win81-x64** (**dotnet publish -c Release -r win81-x64**). The project will publish without warning or error but fail with the above logged exceptions on the server. - **Browser:** ERR_CONNECTION_REFUSED - **Application Log:** No entry @@ -146,20 +140,14 @@ Issue #3 Troubleshooting: -- Confirm you are using the correct URI endpoint for the application. Check your bindings. -- Confirm that the IIS website is not in the `Stopped` state. - -Issue #4 -^^^^^^^^ + - Confirm you are using the correct URI endpoint for the application. Check your bindings. + - Confirm that the IIS website is not in the `Stopped` state. - **OS Exception:** The IIS 7.0 CoreWebEngine and W3SVC features must be installed to use the Microsoft HTTP Platform Handler 1.x. Troubleshooting: -- Confirm that you have enabled the proper server role. See `IIS Configuration`_. - -Issue #5 -^^^^^^^^ + - Confirm that you have enabled the proper server role. See `IIS Configuration`_. - **Browser:** 403 Forbidden: Access is denied **--OR--** 403.14 Forbidden: The Web server is configured to not list the contents of this directory. - **Application Log:** No entry @@ -167,10 +155,7 @@ Issue #5 Troubleshooting: -- Check the IIS website **Basic Settings** and the physical application assets folder. Confirm that the application is in the folder at the IIS website **Physical path**. - -Issue #6 -^^^^^^^^ + - Check the IIS website **Basic Settings** and the physical application assets folder. Confirm that the application is in the folder at the IIS website **Physical path**. - **Browser:** 500.19 Internal Server Error: The requested page cannot be accessed because the related configuration data for the page is invalid. - **Application Log:** No entry @@ -178,12 +163,9 @@ Issue #6 Troubleshooting: -- Confirm that you have enabled the proper server role. See `IIS Configuration`_. -- Check **Programs & Features** and confirm that the **Microsoft ASP.NET Core Module** has been installed. If the **Microsoft ASP.NET Core Module** is not present in the list of installed programs, install the module. See `IIS Configuration`_. -- Make sure that the **Application Pool Process Model Identity** is either set to **ApplicationPoolIdentity**; or if a custom identity is in use, confirm the identity has the correct permissions to access the application's assets folder. - -Issue #7 -^^^^^^^^ + - Confirm that you have enabled the proper server role. See `IIS Configuration`_. + - Check **Programs & Features** and confirm that the **Microsoft ASP.NET Core Module** has been installed. If the **Microsoft ASP.NET Core Module** is not present in the list of installed programs, install the module. See `IIS Configuration`_. + - Make sure that the **Application Pool Process Model Identity** is either set to **ApplicationPoolIdentity**; or if a custom identity is in use, confirm the identity has the correct permissions to access the application's assets folder. - **Browser:** 502.3 Bad Gateway: There was a connection error while trying to route the request. - **Application Log:** Process '0' failed to start. Port = PORT, Error Code = '-2147024894'. @@ -191,12 +173,9 @@ Issue #7 Troubleshooting: -- Check the `processPath` attribute on the `\` element in *web.config* to confirm that it is `dotnet` for a portable application or `.\\my_application.exe` for a self-contained application. -- You may have deployed a portable application without installing .NET Core on the server. If you are attempting to deploy a portable application and have not installed .NET Core, run the **.NET Core Windows Server Hosting Bundle Installer** on the server. See `Install the .NET Core Windows Server Hosting Bundle`_. -- You may have deployed a portable application and installed .NET Core without restarting the server. Restart the server. - -Issue #8 -^^^^^^^^ + - Check the `processPath` attribute on the `\` element in *web.config* to confirm that it is `dotnet` for a portable application or `.\\my_application.exe` for a self-contained application. + - You may have deployed a portable application without installing .NET Core on the server. If you are attempting to deploy a portable application and have not installed .NET Core, run the **.NET Core Windows Server Hosting Bundle Installer** on the server. See `Install the .NET Core Windows Server Hosting Bundle`_. + - You may have deployed a portable application and installed .NET Core without restarting the server. Restart the server. - **Browser:** 502.3 Bad Gateway: There was a connection error while trying to route the request. - **Application Log:** Process 'PROC_ID' failed to start. Port = PORT, Error Code = '-2147023829'. @@ -204,10 +183,7 @@ Issue #8 Troubleshooting: -- Examine the `arguments` attribute on the `\` element in *web.config* to confirm that it is either (a) `.\\my_applciation.dll` for a portable application; or (b) not present, an empty string (`arguments=""`), or a list of your application's arguments (`arguments="arg1, arg2, ..."`) for a self-contained application. - -Issue #9 -^^^^^^^^ + - Examine the `arguments` attribute on the `\` element in *web.config* to confirm that it is either (a) `.\\my_applciation.dll` for a portable application; or (b) not present, an empty string (`arguments=""`), or a list of your application's arguments (`arguments="arg1, arg2, ..."`) for a self-contained application. - **Browser:** 503 Service Unavailable - **Application Log:** No entry @@ -215,7 +191,7 @@ Issue #9 Troubleshooting -- Confirm that the Application Pool is not in the `Stopped` state. + - Confirm that the Application Pool is not in the `Stopped` state. Additional Resources --------------------