将 ASP.NET Core 应用部署到 Azure 应用服务

项目
11/06/2024

注意

此版本不是本文的最新版本。有关当前版本，请参阅本文的 .NET 9 版本。

警告

此版本的 ASP.NET Core 不再受支持。有关详细信息，请参阅 .NET 和 .NET Core 支持策略。对于当前版本，请参阅此文的 .NET 8 版本。

重要

此信息与预发布产品相关，相应产品在商业发布之前可能会进行重大修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

有关当前版本，请参阅本文的 .NET 9 版本。

Azure 应用服务是一个用于托管 Web 应用（包括 ASP.NET Core）的 Microsoft 云计算平台服务。

可靠的 Web 应用模式

请观看《适用于 .NET 的可靠 Web 应用模式》YouTube 视频和文章，了解如何创建新式、可靠、高性能、可测试、经济高效且可缩放的 ASP.NET Core 应用，无论是从头开始创建还是重构现有应用。

有用的资源

应用服务文档是 Azure 应用文档、教程、示例、操作指南和其他资源的 home。两个有关托管 ASP.NET Core 应用的重要教程为：

在 Azure 中创建 ASP.NET Core Web 应用
使用 Visual Studio 创建 ASP.NET Core Web 应用，并将其部署到 Windows 上的 Azure 应用服务。

在 Linux 上的应用服务中创建 ASP.NET Core 应用
使用命令行创建 ASP.NET Core Web 应用，并将其部署到 Linux 上的 Azure 应用服务。

有关 Azure 应用服务上可用的 ASP.NET Core 版本，请参阅应用服务仪表板上的 ASP.NET Core。

订阅应用服务公告存储库并监视问题。应用服务团队会定期发布应用服务中的公告和方案。

ASP.NET Core 文档中提供以下文章：

使用 Visual Studio 将 ASP.NET Core 应用发布到 Azure
了解如何使用 Visual Studio 将 ASP.NET Core 应用发布到 Azure 应用服务。

Create your first pipeline（创建第一个管道）
为 ASP.NET Core 应用设置 CI 生成，然后创建针对 Azure 应用服务的持续部署发布。

Azure Web 应用沙盒
探索 Azure Apps 平台强制实施的 Azure 应用服务运行时执行限制。

ASP.NET Core 项目故障排除和调试
理解 ASP.NET Core 项目的警告和错误，并对其进行故障排除。

应用程序配置

平台

对于在 A 系列计算（基本）上或更高级托管层上托管的应用，可在 Azure 门户中的应用设置中设置应用服务应用的平台体系结构 (x86/x64)。请确认应用的发布设置（例如 Visual Studio 中的发布配置文件 (.pubxml)）与 Azure 门户中应用的服务配置设置匹配。

ASP.NET 核心应用可以依赖于框架发布，因为 Azure 应用服务上存在 64 位 (x64) 和 32 位 (x86) 应用的运行时。应用服务上提供的 .NET Core SDK 为 32 位，但可使用 Kudu 控制台或通过 Visual Studio 中的发布流程来部署本地构建的 64 位应用。有关详细信息，请参阅发布和部署应用部分。

对于具有本机依赖项的应用，32 位 (x86) 应用的运行时存在于 Azure 应用服务上。应用服务上提供的 .NET Core SDK 为 32 位。

要详细了解 .NET Core 框架组件和分发方法（例如有关 .NET Core 运行时和 .NET Core SDK 的信息），请参阅关于 .NET Core：组合。

包

包含以下 NuGet 包，以便为部署到 Azure 应用服务的应用提供自动日志记录功能：

Microsoft.AspNetCore.AzureAppServices.HostingStartup 使用 IHostingStartup 提供 ASP.NET Core 与 Azure 应用服务的日志记录集成。添加的日志记录功能由 Microsoft.AspNetCore.AzureAppServicesIntegration 包提供。
Microsoft.AspNetCore.AzureAppServicesIntegration 执行 AddAzureWebAppDiagnostics，在 Microsoft.Extensions.Logging.AzureAppServices 包中添加 Azure 应用服务诊断日志记录提供程序。
Microsoft.Extensions.Logging.AzureAppServices 提供记录器实现，支持 Azure 应用服务诊断日志和日志流式处理功能。

前面的包必须在应用的项目文件中显式引用。

使用 Azure 门户重写应用配置

Azure 门户中的应用设置允许为应用设置环境变量。可以通过环境变量配置提供程序来使用环境变量。

在 Azure 门户中创建或修改应用设置并选择“保存”按钮时，Azure 应用将重启。服务重启后，应用即可使用环境变量。

调用 CreateBuilder 生成主机时，会将环境变量加载到应用的配置中。有关详细信息，请参阅环境变量配置提供程序。

Azure 门户中的应用设置允许为应用设置环境变量。可以通过环境变量配置提供程序来使用环境变量。

在 Azure 门户中创建或修改应用设置并选择“保存”按钮时，Azure 应用将重启。服务重启后，应用即可使用环境变量。

当应用使用 Web 主机时，在调用 CreateDefaultBuilder 来构建主机时，环境变量将加载到应用程序的配置中。有关详细信息，请参阅 ASP.NET Core Web 主机和环境变量配置提供程序。

代理服务器和负载均衡器方案

托管在进程外时配置转接头中间件的 IIS 集成中间件和 ASP.NET Core 模块将配置为转发方案 (HTTP/HTTPS) 和发出请求的远程 IP 地址。对于托管在其他代理服务器和负载均衡器后方的应用，可能需要附加配置。有关详细信息，请参阅配置 ASP.NET Core 以使用代理服务器和负载均衡器。

监视和日志记录

部署到应用服务的 ASP.NET Core 应用会自动接收“ASP.NET Core 记录集成”这一应用服务扩展。借助该扩展，可记录 Azure 应用服务上针对 ASP.NET Core 应用的集成。

部署到应用服务的 ASP.NET Core 应用自动接收应用服务扩展“ASP.NET Core 日志记录扩展”。借助该扩展，可记录 Azure 应用服务上针对 ASP.NET Core 应用的集成。

有关监视、日志记录和故障排除的信息，请参阅以下文章：

监视 Azure 应用服务中的应用
了解如何查看应用和应用服务计划的配额和指标。

在 Azure 应用服务中为应用启用诊断日志记录
了解如何启用和访问 HTTP 状态代码、失败请求和 Web 服务器活动的诊断日志记录。

处理 ASP.NET Core 中的错误
了解在 ASP.NET Core 应用中处理错误的常见方法。

对 Azure 应用服务和 IIS 上的 ASP.NET Core 进行故障排除
了解如何使用 ASP.NET Core 应用诊断 Azure 应用服务部署问题。

使用ASP.NET Core 对 Azure 应用服务和 IIS 进行常见错误故障排除
使用故障排除建议查看 Azure 应用服务/IIS 托管的应用的常见部署配置错误。

数据保护密钥环和部署槽位

数据保护密钥将保存到 %HOME%\ASP.NET\DataProtection-Keys 文件夹中。此文件夹由网络存储提供支持，并跨托管应用的所有计算机同步。密钥在 rest 时不受保护。此文件夹向单个部署槽位中应用的所有实例提供密钥环。各部署槽位（例如过渡槽和生成槽）不共享密钥环。

在部署槽位之间交换时，使用数据保护的任意系统都无法使用之前槽位中的密钥环来解密存储的数据。 ASP.NET Cookie 中间件使用数据保护来保护其 Cookie。这导致用户注销使用标准 ASP.NET Cookie 中间件的应用。对于独立于槽位的密钥环解决方案，请使用外部密钥环提供程序，例如：

Azure Blob 存储
Azure Key Vault
SQL 存储
Redis 缓存

有关详细信息，请参阅 ASP.NET Core 中的密钥存储提供程序。

部署使用 .NET Core 预览的 ASP.NET Core 应用

若要部署使用 .NET Core 预览版本的应用，请参阅以下资源。当运行时可用，但 SDK 尚未安装在 Azure 应用服务上时，也可以使用这些方法。

使用 Azure Pipelines 指定 .NET Core SDK 版本
部署独立式预览版应用
对用于容器的 Web 应用使用 Docker
安装预览站点扩展

有关 Azure 应用服务上可用的 ASP.NET Core 版本，请参阅应用服务仪表板上的 ASP.NET Core。

有关为自包含部署选择 .NET SDK 版本的信息，请参阅选择要使用的 .NET Core 版本。

使用 Azure Pipelines 指定 .NET Core SDK 版本

使用 Azure 应用服务 CI/CD 方案设置与 Azure DevOps 的持续集成版本。创建 Azure DevOps 版本后，配置版本以使用特定的 SDK 版本（可选）。

指定 .NET Core SDK 版本

使用应用服务部署中心创建 Azure DevOps 版本时，默认版本管道包含 Restore、Build、Test 和 Publish 的步骤。若要指定 SDK 版本，请在“代理作业”列表中选择“添加 (+)”按钮以添加新步骤。在搜索栏中搜索“.NET Core SDK”。

添加 .NET Core SDK 步骤

将该步骤移至版本中的第一个位置，使其后面的步骤使用 .NET Core SDK 的指定版本。指定 .NET Core SDK 版本。在本示例中，SDK 被设置为 3.0.100。

完成的 SDK 步骤

若要发布独立部署 (SCD)，请在 Publish 步骤中配置 SCD 并提供运行时标识符 (RID)。

独立发布

部署独立式预览版应用

针对预览运行时的自包含部署 (SCD)在部署中承载预览运行时。

部署自包含应用时：

Azure 应用服务中的站点不需要预览站点扩展名。
必须使用不同于发布依赖框架部署 (FDD) 的方法发布应用。

按照部署独立式应用部分中的指南操作。

对用于容器的 Web 应用使用 Docker

https://hub.docker.com/_/microsoft-dotnet 的 Docker Hub 包含最新的预览 Docker 映像。这些映像可以用作基础映像。按常规方法使用映像并部署到用于容器的 Web 应用。

安装预览站点扩展

如果无法使用预览版站点扩展，请提出 dotnet/AspNetCore 问题。

从 Azure 门户导航到“应用服务”。
选择 Web 应用。
在搜索框中键入“ex”以筛选“扩展”，或向下滚动管理工具列表。
选择“扩展”。
选择添加。
从列表选择“ASP.NET Core {X.Y} ({x64|x86}) 运行时”扩展，其中 {X.Y} 是 ASP.NET Core 预览版本，并且 {x64|x86} 指定平台。
选择“确定”以接受法律条款。
选择“确定”安装扩展。

操作完成时，即表示已安装最新的 .NET Core 预览版。验证安装：

选择“高级工具”。
选择“高级工具”中的“Go”。
选择“调试控制台”>“PowerShell”菜单项。
从 PowerShell 命令提示符处执行以下命令。在以下命令中，将 ASP.NET Core 运行时版本替换为 {X.Y}，并将平台替换为 {PLATFORM}：
```
Test-Path D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.{PLATFORM}\
```
如果安装 x64 预览版运行时，该命令将返回True。

注意

如果应用在进程内模式下运行并且平台体系结构配置为 64 位 (x64)，则 ASP.NET Core 模块会使用 64 位预览版运行时（如存在）。使用 Azure 门户安装“ASP.NET Core {X.Y} (x64) 运行时”扩展。

安装 x64 预览版运行时后，在 Azure Kudu PowerShell 命令窗口中运行以下命令以验证该安装。在以下命令中，将 ASP.NET Core 运行时版本替换为 {X.Y}：

Test-Path D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x64\

如果安装 x64 预览版运行时，该命令将返回True。

通过 ARM 模板使用预览站点扩展

如果使用 ARM 模板创建和部署应用，则可使用 Microsoft.Web/sites/siteextensions 资源类型将站点扩展添加到 Web 应用。在以下示例中，将 ASP.NET Core 5.0 (x64) 运行时站点扩展 (AspNetCoreRuntime.5.0.x64) 添加到应用：

{
    ...
    "parameters": {
        "site_name": {
            "defaultValue": "{SITE NAME}",
            "type": "String"
        },
        ...
    },       
    ...
    "resources": [
        ...
        {
            "type": "Microsoft.Web/sites/siteextensions",
            "apiVersion": "2018-11-01",
            "name": "[concat(parameters('site_name'), '/AspNetCoreRuntime.5.0.x64')]",
            "location": "[resourceGroup().location]",
            "dependsOn": [
                "[resourceId('Microsoft.Web/sites', parameters('site_name'))]"
            ]
        }
    ]
}

对于占位符 {SITE NAME}，请使用 Azure 应用服务中的应用名称（例如 contoso）。

发布和部署应用

对于 64 位部署：

使用 64 位 .NET Core SDK 部署 64 位的应用。
在应用服务的“配置”>“常规”l“设置”中将“平台”设置为“64 位”。应用必须使用基本服务计划或更高级别的服务计划才能选择平台位数。

部署依赖框架的应用

发布为依赖于框架的应用是跨平台的，并且不包括部署中的 .NET 运行时。 Azure 应用服务包括 .NET 运行时。

Visual Studio
.NET CLI

在“解决方案资源管理器”中，右键单击该项目并选择“发布”。或者，从 Visual Studio 工具栏中选择“生成”>“发布 {应用程序名称}”。
在“发布”对话框中，选择“Azure”>“下一步”。
选择“Azure 服务”。
选择“高级”。随即会打开“发布”对话框。
选择资源组和托管计划，或创建新的资源组和托管计划。
选择“完成”。
在“发布”页面中：
- 对于“配置”，选择笔形图标“编辑配置”：
  - 确认已选中“发布”配置。
  - 在“部署模式”下拉列表中，选择“框架依赖”。
  - 在“目标运行时”下拉列表中，选择所需运行时。默认为 win-x86。
- 若要在部署时删除其他文件，请打开“文件发布选项”，然后选中复选框以删除目标位置的其他文件。
- 选择“保存”。
- 选择发布。

在项目文件中，不要指定运行时标识符 (RID)。
在命令 shell 中，使用 dotnet publish 命令在发布配置中发布应用。在下例中，应用发布为依赖框架的应用：
```
dotnet publish --configuration Release
```
将 bin/Release/{TARGET FRAMEWORK}/publish 目录的内容移动到应用服务中的站点。如果将 publish 文件夹内容从本地硬盘或网络共享直接拖动到 Kudu 控制台中的应用服务，则请将文件拖动到 Kudu 控制台的 D:\home\site\wwwroot 文件夹。

部署自包含应用

如果将应用发布为独立应用，将会生成特定于平台的可执行文件。输出发布文件夹包含应用的所有组件，包括 .NET 库和目标运行时。有关详细信息，请参阅 [自包含发布]/dotnet/core/deploying/#publish-self-contained)。对独立式部署 (SCD) 使用 Visual Studio 或 .NET CLI。

Visual Studio
.NET CLI

在“解决方案资源管理器”中，右键单击该项目并选择“发布”。或者，从 Visual Studio 工具栏中选择“生成”>“发布 {应用程序名称}”。
在“发布”对话框中，选择“Azure”>“下一步”。
选择“Azure 服务”。
选择“高级”。随即会打开“发布”对话框。
选择资源组和托管计划，或创建新的资源组和托管计划。
选择“完成”。
在“发布”页面中：
- 对于“配置”，选择笔形图标“编辑配置”：
  - 确认已选中“发布”配置。
  - 在“部署模式”下拉列表中，选择“自包含”。
  - 在“目标运行时”下拉列表中，选择所需运行时。默认为 win-x86。
- 若要在部署时删除其他文件，请打开“文件发布选项”，然后选中复选框以删除目标位置的其他文件。
- 选择“保存”。
- 选择发布。

在项目文件中，指定一个或多个运行时标识符 (RID)。对单个 RID 使用 <RuntimeIdentifier>，或使用 <RuntimeIdentifiers> 提供以分号分隔的多个 RID 的列表。在以下示例中，指定 win-x86 RID：
```
<PropertyGroup>
  <TargetFramework>{TARGET FRAMEWORK}</TargetFramework>
  <RuntimeIdentifier>win-x86</RuntimeIdentifier>
</PropertyGroup>
```
在命令 shell 中，使用 dotnet publish 命令在主机运行时的发布配置中发布应用。在以下示例中，为 win-x86 RID 发布应用。提供给 --runtime 选项的 RID 必须在项目文件的 <RuntimeIdentifier>（或 <RuntimeIdentifiers>）属性中提供。
```
dotnet publish --configuration Release --runtime win-x86 --self-contained
```
将 bin/Release/{TARGET FRAMEWORK}/{RUNTIME IDENTIFIER}/publish 目录的内容移动到应用服务中的站点。如果将 publish 文件夹内容从本地硬盘或网络共享直接拖动到 Kudu 控制台中的应用服务，则请将文件拖动到 Kudu 控制台的 D:\home\site\wwwroot 文件夹。

协议设置 (HTTPS)

借助安全的协议绑定，可在通过 HTTPS 响应请求时指定要使用的证书。若要绑定，需要一个为特定主机名颁发的有效专用证书 (.pfx)。有关详细信息，请参阅教程：将现有自定义 SSL 证书绑定到 Azure 应用服务。

转换 web.config

如果需要在发布时转换 web.config（例如，基于配置、配置文件或环境设置环境变量），请参阅转换 web.config。

其他资源

Windows Server 上的 Azure 应用服务使用 Internet Information Services (IIS)。前端上的 Kestrel 和 YARP 提供负载均衡器。以下是基础 IIS 技术的相关主题：