Visual Studio 中针对 ASP.NET Core 的开发时 IIS 支持Development-time IIS support in Visual Studio for ASP.NET Core

作者:Sourabh ShirhattiBy Sourabh Shirhatti

本文介绍了对调试在 Windows Server 上与 IIS 一起运行的 ASP.NET Core 应用的 Visual Studio 支持。This article describes Visual Studio support for debugging ASP.NET Core apps running with IIS on Windows Server. 本主题逐步介绍了如何启用此方案并设置项目。This topic walks through enabling this scenario and setting up a project.

先决条件Prerequisites

  • Visual Studio(适用于 Windows)Visual Studio for Windows
  • ASP.NET 和 Web 开发工作负荷ASP.NET and web development workload
  • .NET Core 跨平台开发工作负荷.NET Core cross-platform development workload
  • X.509 安全证书(用于 HTTPS 支持)X.509 security certificate (for HTTPS support)

启用 IISEnable IIS

  1. 在 Windows 中,导航到“控制面板”>“程序”>“程序和功能”>“打开或关闭 Windows 功能”(位于屏幕左侧) 。In Windows, navigate to Control Panel > Programs > Programs and Features > Turn Windows features on or off (left side of the screen).
  2. 选中“Internet Information Services”复选框。Select the Internet Information Services check box. 选择“确定”。Select OK.

IIS 安装可能需要重启系统。The IIS installation may require a system restart.

配置 IISConfigure IIS

IIS 必须具有具备以下配置的网站:IIS must have a website configured with the following:

  • 主机名:通常情况下,使用“主机名”为“localhost”的“默认网站”。Host name: Typically, the Default Web Site is used with a Host name of localhost. 不过,任何具有唯一主机名的有效 IIS 网站也都可行。However, any valid IIS website with a unique host name works.
  • 网站绑定Site Binding
    • 对于要求使用 HTTPS 的应用,请使用证书创建对端口 443 的绑定。For apps that require HTTPS, create a binding to port 443 with a certificate. 通常使用的是“IIS Express 开发证书”,但任何有效证书也都可行。Typically, the IIS Express Development Certificate is used, but any valid certificate works.
    • 对于使用 HTTP 的应用,请确认是否存在对端口 80 的绑定,或为新网站创建对端口 80 的绑定。For apps that use HTTP, confirm the existence of a binding to post 80 or create a binding to port 80 for a new site.
    • 对 HTTP 或 HTTPS 使用单一绑定。Use a single binding for either HTTP or HTTPS. 不支持同时绑定到 HTTP 和 HTTPS 端口。Binding to both HTTP and HTTPS ports simultaneously isn't supported.

在 Visual Studio 中启用开发时 IIS 支持Enable development-time IIS support in Visual Studio

  1. 启动 Visual Studio 安装程序。Launch the Visual Studio installer.

  2. 对于计划用于 IIS 开发时支持的 Visual Studio 安装,选择“修改”。Select Modify for the Visual Studio installation that you plan to use for IIS development-time support.

  3. 对于 ASP.NET 和 Web 开发工作负荷,找到并安装“开发时 IIS 支持”组件。For the ASP.NET and web development workload, locate and install the Development time IIS support component.

    在工作负荷右侧的“安装详细信息”面板中,“开发时 IIS 支持”下的“可选”部分列出了此组件。The component is listed in the Optional section under Development time IIS support in the Installation details panel to the right of the workloads. 该组件将安装 ASP.NET Core 模块,该模块是运行具有 IIS 的 ASP.NET Core 应用所需的本机 IIS 模块。The component installs the ASP.NET Core Module, which is a native IIS module required to run ASP.NET Core apps with IIS.

配置项目Configure the project

HTTPS 重定向HTTPS redirection

对于要求使用 HTTPS 的新项目,选中“新建 ASP.NET Core Web 应用”窗口中的“针对 HTTPS 进行配置”复选框。For a new project that requires HTTPS, select the check box to Configure for HTTPS in the Create a new ASP.NET Core Web Application window. 选中此复选框会向创建后的应用添加 HTTPS 重定向和 HSTS 中间件Selecting the check box adds HTTPS Redirection and HSTS Middleware to the app when it's created.

对于要求使用 HTTPS 的现有项目,使用 Startup.Configure 中的 HTTPS 重定向和 HSTS 中间件。For an existing project that requires HTTPS, use HTTPS Redirection and HSTS Middleware in Startup.Configure. 有关详细信息,请参阅 在 ASP.NET Core 强制实施 HTTPSFor more information, see 在 ASP.NET Core 强制实施 HTTPS.

对于使用 HTTP 的项目,HTTPS 重定向和 HSTS 中间件不会添加到应用中。For a project that uses HTTP, HTTPS Redirection and HSTS Middleware aren't added to the app. 无需配置应用。No app configuration is required.

IIS 启动配置文件IIS launch profile

创建新的启动配置文件以添加开发时 IIS 支持:Create a new launch profile to add development-time IIS support:

  1. 在“解决方案资源管理器”中,右键单击项目。Right-click the project in Solution Explorer. 选择“属性”。Select Properties. 打开“调试”选项卡。Open the Debug tab.

  2. 对于配置文件,请选择“新建”按钮。For Profile, select the New button. 在弹出窗口中将该配置文件命名为“IIS”。Name the profile "IIS" in the popup window. 选择“确定”创建配置文件。Select OK to create the profile.

  3. 对于“启动”设置,请从列表中选择“IIS”。For the Launch setting, select IIS from the list.

  4. 选中“启动浏览器”复选框并提供终结点 URL。Select the check box for Launch browser and provide the endpoint URL.

    如果应用要求使用 HTTPS,使用 HTTPS 终结点 (https://)。When the app requires HTTPS, use an HTTPS endpoint (https://). 如果应用要求使用 HTTP,使用 HTTP (http://) 终结点。For HTTP, use an HTTP (http://) endpoint.

    提供前面指定的 IIS 配置使用的相同主机名和端口,通常为 localhostProvide the same host name and port as the IIS configuration specified earlier uses, typically localhost.

    在 URL 结尾处提供应用名称。Provide the name of the app at the end of the URL.

    例如,https://localhost/WebApplication1 (HTTPS) 或 http://localhost/WebApplication1 (HTTP) 是有效的终结点 URL。For example, https://localhost/WebApplication1 (HTTPS) or http://localhost/WebApplication1 (HTTP) are valid endpoint URLs.

  5. 在“环境变量”部分中,选择“添加”按钮。In the Environment variables section, select the Add button. 提供“名称”为“ASPNETCORE_ENVIRONMENT”且“值”为“Development”的环境变量。Provide an environment variable with a Name of ASPNETCORE_ENVIRONMENT and a Value of Development.

  6. 在“Web 服务器设置”区域中,将“应用 URL”设置为用于“启动浏览器”终结点 URL 的相同值。In the Web Server Settings area, set the App URL to the same value used for the Launch browser endpoint URL.

  7. 对于 Visual Studio 2019 或更高版本中的“托管模型”设置,选择“默认”,以使用项目使用的托管模型。For the Hosting Model setting in Visual Studio 2019 or later, select Default to use the hosting model used by the project. 如果项目在自己的项目文件中设置 <AspNetCoreHostingModel> 属性,使用的是此属性的值(InProcessOutOfProcess)。If the project sets the <AspNetCoreHostingModel> property in its project file, the value of the property (InProcess or OutOfProcess) is used. 如果没有设置此属性,使用的是应用的默认(进程内)托管模型。If the property isn't present, the default hosting model of the app is used, which is in-process. 如果应用需要不同于常规托管模型的显式托管模型,请根据需要将“托管模型”设置为“In Process”或“Out Of Process”。If the app requires an explicit hosting model setting different from the app's normal hosting model, set the Hosting Model to either In Process or Out Of Process as needed.

  8. 保存配置文件。Save the profile.

如果未使用 Visual Studio,请将启动配置文件手动添加到“属性”文件夹中的 launchSettings.json 文件内。When not using Visual Studio, manually add a launch profile to the launchSettings.json file in the Properties folder. 下面的示例展示了如何将配置文件配置为使用 HTTPS 协议:The following example configures the profile to use the HTTPS protocol:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iis": {
      "applicationUrl": "https://localhost/WebApplication1",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS": {
      "commandName": "IIS",
      "launchBrowser": true,
      "launchUrl": "https://localhost/WebApplication1",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

确认 applicationUrllaunchUrl 终结点是否一致,且是否使用与 IIS 绑定配置相同的协议(HTTP 或 HTTPS)。Confirm that the applicationUrl and launchUrl endpoints match and use the same protocol as the IIS binding configuration, either HTTP or HTTPS.

运行该项目Run the project

以管理员身份运行 Visual Studio:Run Visual Studio as an administrator:

  • 确认已将生成配置下拉列表设置为“调试”。Confirm that the build configuration drop-down list is set to Debug.
  • “开始调试”按钮设置为 IIS 配置文件,然后选择此按钮以启动该应用。Set the Start Debugging button to the IIS profile and select the button to start the app.

如果不以管理员身份运行,Visual Studio 可能会提示重启。Visual Studio may prompt a restart if not running as an administrator. 如果出现提示,请重启 Visual Studio。If prompted, restart Visual Studio.

如果使用不受信任的开发证书,则浏览器可能会要求你为不受信任的证书创建异常。If an untrusted development certificate is used, the browser may require you to create an exception for the untrusted certificate.

备注

通过仅我的代码调试“发布”生成配置,从而导致降低编译器优化体验。Debugging a Release build configuration with Just My Code and compiler optimizations results in a degraded experience. 例如,不会遇到断点。For example, break points aren't hit.

其他资源Additional resources

本文介绍了对调试在 Windows Server 上与 IIS 一起运行的 ASP.NET Core 应用的 Visual Studio 支持。This article describes Visual Studio support for debugging ASP.NET Core apps running with IIS on Windows Server. 本主题逐步介绍了如何启用此方案并设置项目。This topic walks through enabling this scenario and setting up a project.

先决条件Prerequisites

  • Visual Studio(适用于 Windows)Visual Studio for Windows
  • ASP.NET 和 Web 开发工作负荷ASP.NET and web development workload
  • .NET Core 跨平台开发工作负荷.NET Core cross-platform development workload
  • X.509 安全证书(用于 HTTPS 支持)X.509 security certificate (for HTTPS support)

启用 IISEnable IIS

  1. 在 Windows 中,导航到“控制面板”>“程序”>“程序和功能”>“打开或关闭 Windows 功能”(位于屏幕左侧) 。In Windows, navigate to Control Panel > Programs > Programs and Features > Turn Windows features on or off (left side of the screen).
  2. 选中“Internet Information Services”复选框。Select the Internet Information Services check box. 选择“确定”。Select OK.

IIS 安装可能需要重启系统。The IIS installation may require a system restart.

配置 IISConfigure IIS

IIS 必须具有具备以下配置的网站:IIS must have a website configured with the following:

  • 主机名:通常情况下,使用“主机名”为“localhost”的“默认网站”。Host name: Typically, the Default Web Site is used with a Host name of localhost. 不过,任何具有唯一主机名的有效 IIS 网站也都可行。However, any valid IIS website with a unique host name works.
  • 网站绑定Site Binding
    • 对于要求使用 HTTPS 的应用,请使用证书创建对端口 443 的绑定。For apps that require HTTPS, create a binding to port 443 with a certificate. 通常使用的是“IIS Express 开发证书”,但任何有效证书也都可行。Typically, the IIS Express Development Certificate is used, but any valid certificate works.
    • 对于使用 HTTP 的应用,请确认是否存在对端口 80 的绑定,或为新网站创建对端口 80 的绑定。For apps that use HTTP, confirm the existence of a binding to post 80 or create a binding to port 80 for a new site.
    • 对 HTTP 或 HTTPS 使用单一绑定。Use a single binding for either HTTP or HTTPS. 不支持同时绑定到 HTTP 和 HTTPS 端口。Binding to both HTTP and HTTPS ports simultaneously isn't supported.

在 Visual Studio 中启用开发时 IIS 支持Enable development-time IIS support in Visual Studio

  1. 启动 Visual Studio 安装程序。Launch the Visual Studio installer.

  2. 对于计划用于 IIS 开发时支持的 Visual Studio 安装,选择“修改”。Select Modify for the Visual Studio installation that you plan to use for IIS development-time support.

  3. 对于 ASP.NET 和 Web 开发工作负荷,找到并安装“开发时 IIS 支持”组件。For the ASP.NET and web development workload, locate and install the Development time IIS support component.

    在工作负荷右侧的“安装详细信息”面板中,“开发时 IIS 支持”下的“可选”部分列出了此组件。The component is listed in the Optional section under Development time IIS support in the Installation details panel to the right of the workloads. 该组件将安装 ASP.NET Core 模块,该模块是运行具有 IIS 的 ASP.NET Core 应用所需的本机 IIS 模块。The component installs the ASP.NET Core Module, which is a native IIS module required to run ASP.NET Core apps with IIS.

配置项目Configure the project

HTTPS 重定向HTTPS redirection

对于要求使用 HTTPS 的新项目,选中“新建 ASP.NET Core Web 应用”窗口中的“针对 HTTPS 进行配置”复选框。For a new project that requires HTTPS, select the check box to Configure for HTTPS in the Create a new ASP.NET Core Web Application window. 选中此复选框会向创建后的应用添加 HTTPS 重定向和 HSTS 中间件Selecting the check box adds HTTPS Redirection and HSTS Middleware to the app when it's created.

对于要求使用 HTTPS 的现有项目,使用 Startup.Configure 中的 HTTPS 重定向和 HSTS 中间件。For an existing project that requires HTTPS, use HTTPS Redirection and HSTS Middleware in Startup.Configure. 有关详细信息,请参阅 在 ASP.NET Core 强制实施 HTTPSFor more information, see 在 ASP.NET Core 强制实施 HTTPS.

对于使用 HTTP 的项目,HTTPS 重定向和 HSTS 中间件不会添加到应用中。For a project that uses HTTP, HTTPS Redirection and HSTS Middleware aren't added to the app. 无需配置应用。No app configuration is required.

IIS 启动配置文件IIS launch profile

创建新的启动配置文件以添加开发时 IIS 支持:Create a new launch profile to add development-time IIS support:

  1. 在“解决方案资源管理器”中,右键单击项目。Right-click the project in Solution Explorer. 选择“属性”。Select Properties. 打开“调试”选项卡。Open the Debug tab.

  2. 对于配置文件,请选择“新建”按钮。For Profile, select the New button. 在弹出窗口中将该配置文件命名为“IIS”。Name the profile "IIS" in the popup window. 选择“确定”创建配置文件。Select OK to create the profile.

  3. 对于“启动”设置,请从列表中选择“IIS”。For the Launch setting, select IIS from the list.

  4. 选中“启动浏览器”复选框并提供终结点 URL。Select the check box for Launch browser and provide the endpoint URL.

    如果应用要求使用 HTTPS,使用 HTTPS 终结点 (https://)。When the app requires HTTPS, use an HTTPS endpoint (https://). 如果应用要求使用 HTTP,使用 HTTP (http://) 终结点。For HTTP, use an HTTP (http://) endpoint.

    提供前面指定的 IIS 配置使用的相同主机名和端口,通常为 localhostProvide the same host name and port as the IIS configuration specified earlier uses, typically localhost.

    在 URL 结尾处提供应用名称。Provide the name of the app at the end of the URL.

    例如,https://localhost/WebApplication1 (HTTPS) 或 http://localhost/WebApplication1 (HTTP) 是有效的终结点 URL。For example, https://localhost/WebApplication1 (HTTPS) or http://localhost/WebApplication1 (HTTP) are valid endpoint URLs.

  5. 在“环境变量”部分中,选择“添加”按钮。In the Environment variables section, select the Add button. 提供“名称”为“ASPNETCORE_ENVIRONMENT”且“值”为“Development”的环境变量。Provide an environment variable with a Name of ASPNETCORE_ENVIRONMENT and a Value of Development.

  6. 在“Web 服务器设置”区域中,将“应用 URL”设置为用于“启动浏览器”终结点 URL 的相同值。In the Web Server Settings area, set the App URL to the same value used for the Launch browser endpoint URL.

  7. 对于 Visual Studio 2019 或更高版本中的“托管模型”设置,选择“默认”,以使用项目使用的托管模型。For the Hosting Model setting in Visual Studio 2019 or later, select Default to use the hosting model used by the project. 如果项目在自己的项目文件中设置 <AspNetCoreHostingModel> 属性,使用的是此属性的值(InProcessOutOfProcess)。If the project sets the <AspNetCoreHostingModel> property in its project file, the value of the property (InProcess or OutOfProcess) is used. 如果没有设置此属性,使用的是应用的默认(进程外)托管模型。If the property isn't present, the default hosting model of the app is used, which is out-of-process. 如果应用需要不同于常规托管模型的显式托管模型,请根据需要将“托管模型”设置为“In Process”或“Out Of Process”。If the app requires an explicit hosting model setting different from the app's normal hosting model, set the Hosting Model to either In Process or Out Of Process as needed.

  8. 保存配置文件。Save the profile.

如果未使用 Visual Studio,请将启动配置文件手动添加到“属性”文件夹中的 launchSettings.json 文件内。When not using Visual Studio, manually add a launch profile to the launchSettings.json file in the Properties folder. 下面的示例展示了如何将配置文件配置为使用 HTTPS 协议:The following example configures the profile to use the HTTPS protocol:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iis": {
      "applicationUrl": "https://localhost/WebApplication1",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS": {
      "commandName": "IIS",
      "launchBrowser": true,
      "launchUrl": "https://localhost/WebApplication1",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

确认 applicationUrllaunchUrl 终结点是否一致,且是否使用与 IIS 绑定配置相同的协议(HTTP 或 HTTPS)。Confirm that the applicationUrl and launchUrl endpoints match and use the same protocol as the IIS binding configuration, either HTTP or HTTPS.

运行该项目Run the project

以管理员身份运行 Visual Studio:Run Visual Studio as an administrator:

  • 确认已将生成配置下拉列表设置为“调试”。Confirm that the build configuration drop-down list is set to Debug.
  • “开始调试”按钮设置为 IIS 配置文件,然后选择此按钮以启动该应用。Set the Start Debugging button to the IIS profile and select the button to start the app.

如果不以管理员身份运行,Visual Studio 可能会提示重启。Visual Studio may prompt a restart if not running as an administrator. 如果出现提示,请重启 Visual Studio。If prompted, restart Visual Studio.

如果使用不受信任的开发证书,则浏览器可能会要求你为不受信任的证书创建异常。If an untrusted development certificate is used, the browser may require you to create an exception for the untrusted certificate.

备注

通过仅我的代码调试“发布”生成配置,从而导致降低编译器优化体验。Debugging a Release build configuration with Just My Code and compiler optimizations results in a degraded experience. 例如,不会遇到断点。For example, break points aren't hit.

其他资源Additional resources