Hướng dẫn cấu hình web server aps.net năm 2024
Hãy nâng cấp lên Microsoft Edge để tận dụng các tính năng mới nhất, bản cập nhật bảo mật và hỗ trợ kỹ thuật. Show
Host ASP.NET Core on Windows with IIS
Trong bài viết nàyInternet Information Services (IIS) is a flexible, secure and manageable Web Server for hosting web apps, including ASP.NET Core. Supported platformsThe following operating systems are supported:
Apps published for 32-bit (x86) or 64-bit (x64) deployment are supported. Deploy a 32-bit app with a 32-bit (x86) .NET Core SDK unless the app:
Install the ASP.NET Core Module/Hosting BundleDownload the latest installer using the following link: Current .NET Core Hosting Bundle installer (direct download) For more details instructions on how to install the ASP.NET Core Module, or installing different versions, see Install the .NET Core Hosting Bundle. To download previous versions of the hosting bundle, see this GitHub issue. Get startedFor getting started with hosting a website on IIS, see our getting started guide. For getting started with hosting a website on Azure App Services, see our deploying to Azure App Service guide. ConfigurationFor configuration guidance, see Advanced configuration. Deployment resources for IIS administrators
Overlapped recycleIn general, we recommend using a pattern like blue-green deployments for zero-downtime deployments. Features like Overlapped Recycle help, but don't guarantee that you can do a zero-downtime deployment. For more information, see this GitHub issue. Optional client certificatesFor information on apps that must protect a subset of the app with a certificate, see . Additional resources
For a tutorial experience on publishing an ASP.NET Core app to an IIS server, see Publish an ASP.NET Core app to IIS. Supported operating systemsThe following operating systems are supported:
HTTP.sys server (formerly called WebListener) doesn't work in a reverse proxy configuration with IIS. Use the Kestrel server. For information on hosting in Azure, see Deploy ASP.NET Core apps to Azure App Service. For troubleshooting guidance, see Troubleshoot and debug ASP.NET Core projects. Supported platformsApps published for 32-bit (x86) or 64-bit (x64) deployment are supported. Deploy a 32-bit app with a 32-bit (x86) .NET Core SDK unless the app:
Apps published for 32-bit (x86) must have 32-bit enabled for their IIS Application Pools. For more information, see the section. Use a 64-bit (x64) .NET Core SDK to publish a 64-bit app. A 64-bit runtime must be present on the host system. Hosting modelsIn-process hosting modelUsing in-process hosting, an ASP.NET Core app runs in the same process as its IIS worker process. In-process hosting provides improved performance over out-of-process hosting because requests aren't proxied over the loopback adapter, a network interface that returns outgoing network traffic back to the same machine. IIS handles process management with the Windows Process Activation Service (WAS). The ASP.NET Core Module:
The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app hosted in-process:
After the IIS HTTP Server processes the request:
In-process hosting is opt-in for existing apps. The ASP.NET Core web templates use the in-process hosting model.
2 adds an IServer instance by calling the UseIIS method to boot the and host the app inside of the IIS worker process (
3 or
4). Performance tests indicate that hosting a .NET Core app in-process delivers significantly higher request throughput compared to hosting the app out-of-process and proxying requests to Kestrel. Apps published as a single file executable can't be loaded by the in-process hosting model. Out-of-process hosting modelBecause ASP.NET Core apps run in a process separate from the IIS worker process, the ASP.NET Core Module handles process management. The module starts the process for the ASP.NET Core app when the first request arrives and restarts the app if it shuts down or crashes. This is essentially the same behavior as seen with apps that run in-process that are managed by the Windows Process Activation Service (WAS). The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app hosted out-of-process:
The ASP.NET Core Module specifies the port via an environment variable at startup. The UseIISIntegration extension configures the server to listen on
5. Additional checks are performed, and requests that don't originate from the module are rejected. The module doesn't support HTTPS forwarding. Requests are forwarded over HTTP even if received by IIS over HTTPS. After Kestrel picks up the request from the module, the request is forwarded into the ASP.NET Core middleware pipeline. The middleware pipeline handles the request and passes it on as an
1 instance to the app's logic. Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for forwarding the request to Kestrel. The app's response is passed back to IIS, which forwards it back to the HTTP client that initiated the request. For ASP.NET Core Module configuration guidance, see ASP.NET Core Module (ANCM) for IIS. For more information on hosting, see . Application configurationEnable the IISIntegration componentsWhen building a host in
7 (
8), call CreateDefaultBuilder to enable IIS integration:
For more information on
2, see . IIS optionsIn-process hosting model To configure IIS Server options, include a service configuration for IISServerOptions in ConfigureServices. The following example disables AutomaticAuthentication:
Option Default Setting
0
1 If
1, IIS Server sets the
3 authenticated by Windows Authentication. If
4, the server only provides an identity for
3 and responds to challenges when explicitly requested by the
6. Windows Authentication must be enabled in IIS for
0 to function. For more information, see Windows Authentication.
8
9 Sets the display name shown to users on login pages.
0
4 Whether synchronous I/O is allowed for the
2 and the
3.
4
5 Gets or sets the max request body size for the
6. Note that IIS itself has the limit
7 which will be processed before the
4 set in the
9. Changing the
4 won't affect the
7. To increase
7, add an entry in the
3 to set
7 to a higher value. For more details, see . Out-of-process hosting model To configure IIS options, include a service configuration for IISOptions in ConfigureServices. The following example prevents the app from populating
5:
Option Default Setting
0
1 If
1, sets the
3 authenticated by Windows Authentication. If
4, the middleware only provides an identity for
3 and responds to challenges when explicitly requested by the
6. Windows Authentication must be enabled in IIS for
0 to function. For more information, see the Windows Authentication topic.
8
9 Sets the display name shown to users on login pages.
6
1 If
1 and the
9 request header is present, the
5 is populated. Proxy server and load balancer scenariosThe and the ASP.NET Core Module are configured to forward the:
The configures Forwarded Headers Middleware. Additional configuration might be required for apps hosted behind additional proxy servers and load balancers. For more information, see Configure ASP.NET Core to work with proxy servers and load balancers.
3 file The
3 file configures the ASP.NET Core Module. Creating, transforming, and publishing the
3 file is handled by an MSBuild target (
5). The SDK is set at the top of the project file:
If a
3 file isn't present in the project, the file is created with the correct
7 and
8 to configure the ASP.NET Core Module and moved to published output. If a
3 file is present in the project, the file is transformed with the correct
7 and
8 to configure the ASP.NET Core Module and moved to published output. The transformation doesn't modify IIS configuration settings in the file. The
3 file may provide additional IIS configuration settings that control active IIS modules. For information on IIS modules that are capable of processing requests with ASP.NET Core apps, see the IIS modules topic. To prevent the Web SDK from transforming the
3 file, use the
4 property in the project file:
When disabling the Web SDK from transforming the file, the
7 and
8 should be manually set by the developer. For more information, see ASP.NET Core Module (ANCM) for IIS.
3 file location In order to set up the ASP.NET Core Module correctly, the
3 file must be present at the path (typically the app base path) of the deployed app. This is the same location as the website physical path provided to IIS. The
3 file is required at the root of the app to enable the publishing of multiple apps using Web Deploy. Sensitive files exist on the app's physical path, such as
0,
1 (XML Documentation comments), and
2, where the placeholder
3 is the assembly name. When the
3 file is present and the site starts normally, IIS doesn't serve these sensitive files if they're requested. If the
3 file is missing, incorrectly named, or unable to configure the site for normal startup, IIS may serve sensitive files publicly. The
3 file must be present in the deployment at all times, correctly named, and able to configure the site for normal start up. Never remove the
3 file from a production deployment. Transform web.configIf you need to transform
3 on publish, see Transform web.config. You might need to transform
3 on publish to set environment variables based on the configuration, profile, or environment. IIS configurationWindows Server operating systems Enable the Web Server (IIS) server role and establish role services.
Windows desktop operating systems Enable the IIS Management Console and World Wide Web Services.
Install the .NET Core Hosting BundleInstall the .NET Core Hosting Bundle on the hosting system. The bundle installs the .NET Core Runtime, .NET Core Library, and the ASP.NET Core Module. The module allows ASP.NET Core apps to run behind IIS. Important If the Hosting Bundle is installed before IIS, the bundle installation must be repaired. Run the Hosting Bundle installer again after installing IIS. If the Hosting Bundle is installed after installing the 64-bit (x64) version of .NET Core, SDKs might appear to be missing (). To resolve the problem, see . Direct download (current version)Download the installer using the following link: Current .NET Core Hosting Bundle installer (direct download) Earlier versions of the installerTo obtain an earlier version of the installer:
Warning Some installers contain release versions that have reached their end of life (EOL) and are no longer supported by Microsoft. For more information, see the support policy. Install the Hosting Bundle
ASP.NET Core doesn't adopt roll-forward behavior for patch releases of shared framework packages. After upgrading the shared framework by installing a new hosting bundle, restart the system or execute the following commands in an elevated command shell:
Install Web Deploy when publishing with Visual StudioWhen deploying apps to servers with Web Deploy, install the latest version of Web Deploy on the server. To install Web Deploy, use the Web Platform Installer (WebPI) or obtain an installer directly from the Microsoft Download Center. The preferred method is to use WebPI. WebPI offers a standalone setup and a configuration for hosting providers. Create the IIS site
Windows Authentication configuration (Optional) For more information, see Configure Windows authentication. Deploy the appDeploy the app to the IIS Physical path folder that was established in the section. Web Deploy is the recommended mechanism for deployment, but several options exist for moving the app from the project's
13 folder to the hosting system's deployment folder. Web Deploy with Visual StudioSee the topic to learn how to create a publish profile for use with Web Deploy. If the hosting provider provides a Publish Profile or support for creating one, download their profile and import it using the Visual Studio Publish dialog: Web Deploy outside of Visual StudioWeb Deploy can also be used outside of Visual Studio from the command line. For more information, see Web Deployment Tool. Alternatives to Web DeployUse any of several methods to move the app to the hosting system, such as manual copy, Xcopy, Robocopy, or PowerShell. For more information on ASP.NET Core deployment to IIS, see the section. Browse the websiteAfter the app is deployed to the hosting system, make a request to one of the app's public endpoints. In the following example, the site is bound to an IIS Host name of
14 on Port
15. A request is made to
16: Locked deployment filesFiles in the deployment folder are locked when the app is running. Locked files can't be overwritten during deployment. To release locked files in a deployment, stop the app pool using one of the following approaches:
Data protectionThe ASP.NET Core Data Protection stack is used by several ASP.NET Core middlewares, including middleware used in authentication. Even if Data Protection APIs aren't called by user code, data protection should be configured with a deployment script or in user code to create a persistent cryptographic key store. If data protection isn't configured, the keys are held in memory and discarded when the app restarts. If the key ring is stored in memory when the app restarts:
To configure data protection under IIS to persist the key ring, use one of the following approaches:
Virtual Directoriesaren't supported with ASP.NET Core apps. An app can be hosted as a . Sub-applicationsAn ASP.NET Core app can be hosted as an . The sub-app's path becomes part of the root app's URL. Static asset links within the sub-app should use tilde-slash (
32, an image linked with
33 is rendered as
34. The root app's Static File Middleware doesn't process the static file request. The request is processed by the sub-app's Static File Middleware. If a static asset's
35 attribute is set to an absolute path (for example,
36), the link is rendered without the sub-app's pathbase. The root app's Static File Middleware attempts to serve the asset from the root app's , which results in a 404 - Not Found response unless the static asset is available from the root app. To host an ASP.NET Core app as a sub-app under another ASP.NET Core app:
The assignment of a separate app pool to the sub-app is a requirement when using the in-process hosting model. For more information on the in-process hosting model and configuring the ASP.NET Core Module, see ASP.NET Core Module (ANCM) for IIS. Configuration of IIS with web.configIIS configuration is influenced by the
37 section of web.config for IIS scenarios that are functional for ASP.NET Core apps with the ASP.NET Core Module. For example, IIS configuration is functional for dynamic compression. If IIS is configured at the server level to use dynamic compression, the
38 element in the app's web.config file can disable it for an ASP.NET Core app. For more information, see the following topics:
To set environment variables for individual apps running in isolated app pools (supported for IIS 10.0 or later), see the AppCmd.exe command section of the topic in the IIS reference documentation. Sections that aren't used by ASP.NET CoreConfiguration sections of ASP.NET apps in web.config aren't used by ASP.NET Core apps for configuration:
ASP.NET Core apps are configured using other configuration providers. For more information, see Configuration and .NET Core run-time configuration settings Application PoolsApp pool isolation is determined by the hosting model:
The IIS Add Website dialog defaults to a single app pool per app. When a Site name is provided, the text is automatically transferred to the Application pool textbox. A new app pool is created using the site name when the site is added. Application Pool IdentityAn app pool identity account allows an app to run under a unique account without having to create and manage domains or local accounts. On IIS 8.0 or later, the IIS Admin Worker Process (WAS) creates a virtual account with the name of the new app pool and runs the app pool's worker processes under this account by default. In the IIS Management Console under Advanced Settings for the app pool, ensure that the Identity is set to use ApplicationPoolIdentity: The IIS management process creates a secure identifier with the name of the app pool in the Windows Security System. Resources can be secured using this identity. However, this identity isn't a real user account and doesn't show up in the Windows User Management Console. If the IIS worker process requires elevated access to the app, modify the Access Control List (ACL) for the directory containing the app:
Access can also be granted at a command prompt using the ICACLS tool. Using the
46 as an example, the following command is used:
For more information, see the icacls topic. HTTP/2 supportHTTP/2 is supported with ASP.NET Core in the following IIS deployment scenarios:
For an in-process deployment when an HTTP/2 connection is established,
50 reports
51. For an out-of-process deployment when an HTTP/2 connection is established,
50 reports
53. For more information on the in-process and out-of-process hosting models, see ASP.NET Core Module (ANCM) for IIS. HTTP/2 is enabled by default. Connections fall back to HTTP/1.1 if an HTTP/2 connection isn't established. For more information on HTTP/2 configuration with IIS deployments, see HTTP/2 on IIS. CORS preflight requestsThis section only applies to ASP.NET Core apps that target the .NET Framework. For an ASP.NET Core app that targets the .NET Framework, OPTIONS requests aren't passed to the app by default in IIS. To learn how to configure the app's IIS handlers in web.config to pass OPTIONS requests, see . |