Aspire Azure Container Apps 托管集成环境建模、计算资源编排与发布部署实战指南【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire导读Aspire.Hosting.Azure.AppContainers是 Aspire 用于建模、配置和编排 Azure Container Apps 环境的托管集成。本文基于该集成在仓库中的 README.md 展开并结合 AzureContainerAppExtensions.cs、AzureContainerAppContainerExtensions.cs 等源码实现与 AzureContainerAppEnvironmentExtensionsTests.cs 测试用例系统讲解如何用一行 API 在 Aspire 解决方案中声明 Container Apps 环境、把 Dockerfile/项目/可执行程序发布为容器应用、定制入站流量与命名约定并通过aspire publish/aspire deploy完成从 Bicep 生成到真实资源预配的完整链路。读完本文你将掌握该集成的全部核心 API、默认基础设施模型、常见定制手段及部署/清理的实战方法。一、集成概览一条语句构建云原生应用环境该集成允许在 Aspire AppHost 的编程模型中声明式地定义一个 Azure Container Apps 环境并把解决方案中的计算资源Dockerfile 容器、.NET 项目、可执行程序自动映射为该环境内的 Container App。它位于 src/Aspire.Hosting.Azure.AppContainers/ 目录核心类型包括文件职责AzureContainerAppExtensions.cs环境资源的入口AddAzureContainerAppEnvironment以及命名、Dashboard、日志、拉取身份等定制 APIAzureContainerAppEnvironmentResource.cs环境资源模型实现IAzureComputeEnvironmentResource、IContainerRegistry等接口AzureContainerAppContainerExtensions.cs将容器资源发布为 Container AppAzureContainerAppProjectExtensions.cs将项目资源发布为 Container AppAzureContainerAppExecutableExtensions.cs将可执行程序资源发布为 Container AppContainerAppContext.cs单个 Container App 的构建逻辑端点、环境变量、密钥、卷、探针ContainerAppEnvironmentContext.cs环境级上下文为每个计算资源创建 Container AppAzureContainerAppScaleConfig.cs缩放配置模型AzureContainerAppJobCustomizationAnnotation.csContainer App Job 定制标注从源码结构看该集成基于 Azure.ProvisioningCDK构建环境资源继承自AzureProvisioningResource通过回调把 Azure 资源托管环境、容器注册表、Log Analytics 工作区、托管标识等编译为 Bicep 模块再交由 Aspire 的部署管线执行。二、快速开始前置条件与安装集成2.1 前置条件一个 Aspire AppHost 项目以及可用的容器运行时如 Docker用于构建和运行容器镜像若要部署到 Azure需要一个有权创建资源并分配角色的 Azure 订阅并且已通过az login完成 Azure CLI 登录。2.2 添加集成在 AppHost 目录下使用 Aspire CLI 添加集成包aspire add Aspire.Hosting.Azure.AppContainers添加完成后AppHost 项目中即可引用Aspire.Hosting.Azure.AppContainers命名空间下对外暴露于Aspire.Hosting命名空间的扩展方法。三、最小可用示例一个环境 一个 Web 应用README 给出的最小示例用核心AddDockerfileAPI 声明一个 HTTP 应用监听8080端口并放入一个名为env的 Container Apps 环境。前提是 AppHost 目录下存在web子目录其中包含构建该 HTTP 应用的 Dockerfile。C#AppHost/Program.csusing Aspire.Hosting; var builder DistributedApplication.CreateBuilder(args); builder.AddAzureContainerAppEnvironment(env); builder.AddDockerfile(web, web) .WithHttpEndpoint(targetPort: 8080) .WithExternalHttpEndpoints(); builder.Build().Run();TypeScriptapphost.mtsimport { createBuilder } from ./.aspire/modules/aspire.mjs; const builder await createBuilder(); await builder.addAzureContainerAppEnvironment(env); await builder.addDockerfile(web, web) .withHttpEndpoint({ targetPort: 8080 }) .withExternalHttpEndpoints(); await builder.build().run();3.1 行为要点自动归属当解决方案中存在一个环境时受支持的计算资源会被自动分配到该环境无需显式指定PublishAsAzureContainerApp是可选的它只用于定制生成的 Container App见下文第五节。如果无需定制声明 Dockerfile/项目后就会自动以默认方式发布默认内网HTTP 端点默认是内部internal的WithExternalHttpEndpoints显式把该 Web 应用纳入公共入站ingress流量本地运行不预配本地dotnet run时不会创建真实的 Container Apps 环境源码中AddAzureContainerAppEnvironment在 Run 模式下仅返回资源构建器不把资源加入模型见 AzureContainerAppExtensions.cs。从实现看AddAzureContainerAppEnvironment(env)会同步创建默认的 Azure Container Registry命名为env-acr并绑定到环境AzureContainerAppExtensions.cs后续发布的计算资源镜像都推送到该注册表。四、AddAzureContainerAppEnvironment的默认基础设施模型调用AddAzureContainerAppEnvironment(name)时Aspire 会在生成 Bicep 时自动预配以下整套 Azure 基础设施见 AzureContainerAppExtensions.cs资源默认命名说明Azure Container Registry{env}-acr存放所有容器镜像同时输出AZURE_CONTAINER_REGISTRY_NAME/AZURE_CONTAINER_REGISTRY_ENDPOINTUser-Assigned 托管标识{env}_mi用于从 ACR 拉取镜像AcrPull输出AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_IDACR AcrPull 角色分配—将ContainerRegistryBuiltInRole.AcrPull授予上述标识Log Analytics 工作区{env}_lawSku 为PerGB2018供环境日志收集输出AZURE_LOG_ANALYTICS_WORKSPACE_NAME/AZURE_LOG_ANALYTICS_WORKSPACE_IDContainer App 托管环境{env}Workload Profiles 默认仅含Consumption档日志目标为 log-analyticsAspire Dashboard 组件aspire-dashboard类型AspireDashboard版本2025-10-02-preview默认启用4.1 关键输出参数环境模块统一输出以下标准参数供下游 Container App 与 azd 消费见AddSharedContainerAppEnvironmentOutputsAzureContainerAppExtensions.csAZURE_CONTAINER_REGISTRY_NAMEAZURE_CONTAINER_REGISTRY_ENDPOINTAZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_IDAZURE_CONTAINER_APPS_ENVIRONMENT_NAMEAZURE_CONTAINER_APPS_ENVIRONMENT_IDAZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAINazd 输出 Dashboard 地址时使用4.2 每个 Container App 的构建流程AzureContainerAppEnvironmentResource注册了两个管线步骤prepare-azure-container-apps-{name}在 BeforeStart 阶段为所有计算资源物化部署目标和可选的print-dashboard-url-{name}部署成功后打印 Dashboard 地址见 AzureContainerAppEnvironmentResource.cs。对每个计算资源ContainerAppEnvironmentContext.CreateContainerAppAsync会创建对应的ContainerAppContextContainerAppEnvironmentContext.cs随后在ContainerAppContext.BuildContainerApp中完成解析所有端点并生成 ingress 配置注入环境变量与命令行参数含密钥映射若资源带有AppIdentityAnnotation为 Container App 附加用户分配的托管标识挂载卷Azure Files 存储映射探针Startup/Readiness/Liveness最后执行用户通过PublishAsAzureContainerApp提供的定制回调。五、发布计算资源Project / Container / Executable 三种载体当解决方案中有多个环境或需要对默认生成的 Container App 做定制时使用PublishAsAzureContainerApp。该系列 API 有三个重载分别面向不同类型的资源项目资源ProjectResourcebuilder.AddProjectProjects.Api() .PublishAsAzureContainerApp((infrastructure, app) { // 在这里定制生成的 ContainerApp });容器资源ContainerResourcebuilder.AddContainer(name, image) .PublishAsAzureContainerApp((infrastructure, app) { // 例如配置自定义环境变量、缩放规则等 });可执行程序资源ExecutableResource通常与 Dockerfile 配合builder.AddDockerfile(web, web) .PublishAsAzureContainerApp((infrastructure, app) { // 定制 ContainerApp });5.1 实现要点从源码看这三个扩展方法的行为完全一致AzureContainerAppProjectExtensions.cs仅在发布模式生效if (!project.ApplicationBuilder.ExecutionContext.IsPublishMode) return project;——本地运行run 模式时调用该方法不会产生任何副作用调用AddAzureContainerAppsInfrastructureCore()注册基础设施幂等多次调用只注册一次全局校验步骤见 AzureContainerAppExtensions.cs把定制回调封装为AzureContainerAppCustomizationAnnotation标注附加到资源上最终在ContainerAppContext.BuildContainerApp末尾执行ContainerAppContext.cs。5.2 项目资源的默认行为对 .NET 项目Aspire 默认启用AutoConfigureDataProtection需要2025-10-02-preview资源版本见 ContainerAppContext.cs对带AzureFunctionsAnnotation的资源默认将Kind设为Functionapp适配 Azure Functions 部署。六、端点与入站流量控制6.1 HTTP 端点默认升级为 HTTPS默认情况下环境会把所有 HTTP 端点升级为 HTTPS443 端口。原因在源码注释中说明HTTP 到 HTTPS 的重定向会破坏 WebSocket 升级ContainerAppContext.cs。部署时日志会汇总被升级的端点如web:http提示可通过.WithHttpsUpgrade(false)关闭ContainerAppEnvironmentContext.cs。关闭 HTTPS 升级保留 HTTP 80builder.AddAzureContainerAppEnvironment(env) .WithHttpsUpgrade(upgrade: false);注意即便关闭升级显式指定的开发端口如 8080仍会按 Azure Container Apps 的要求规范化为标准端口 80/443见 AzureContainerAppExtensions.cs 的 XML 注释。6.2 端点类型约束ContainerAppContext.ProcessEndpoints会校验端点定义ContainerAppContext.cs仅支持http、http2、tcp三种传输层协议其他传输会抛出NotSupportedException最多一个外部端点且外部端点必须为 HTTP(S)外部 TCP 端点不支持同一目标端口上不允许混用 HTTP 与 TCP有多个 HTTP 端点时优先选择外部端点作为 ingress其余作为附加 TCP 端口映射AdditionalPortMappings内网附加端口超过 5 个时会输出警告参考 Azure 关于 TCP ingress 的文档。6.3 内部/外部地址表达式环境实现了GetHostAddressExpression为内部端点生成name.internal.domain形式的地址、外部端点生成name.domain形式AzureContainerAppEnvironmentResource.cs应用之间可通过标准 Aspire 端点引用互访。七、命名约定azd 对齐、唯一命名与紧凑命名当应用最初由 azd 部署、或需要把多个环境部署到同一资源组时命名策略至关重要。源码中针对 managed environment 名称做了专门的碰撞防护详见 AzureContainerAppExtensions.cs 及 ManagedEnvironmentNameResolver。7.1 WithAzdResourceNaming让环境资源与 azd 使用完全相同的命名约定从而复用 azd 已部署的资源builder.AddAzureContainerAppEnvironment(env) .WithAzdResourceNaming();启用后托管环境命名为cae-${uniqueString(resourceGroup().id)}标识为mi-${resourceToken}、注册表为acr-…、Log Analytics 为law-${resourceToken}AzureContainerAppExtensions.cs。7.2 WithUniqueResourceNaming解决同一资源组内多个环境命名塌缩的问题。默认情况下 Azure.Provisioning 对ContainerAppManagedEnvironment只保留小写字母cae1与cae2会被清洗成同一个cae进而碰撞到同一个物理环境对应 issue #18722。启用该方法后名称算法改为清洗后的资源名 连字符 uniqueString截断到 60 字符例如cae1生成take(cae1-${uniqueString(resourceGroup().id)}, 60)保留数字从而区分彼此var env1 builder.AddAzureContainerAppEnvironment(cae1).WithUniqueResourceNaming(); var env2 builder.AddAzureContainerAppEnvironment(cae2).WithUniqueResourceNaming();该方法为可选opt-in因为它会改变已部署单环境的名称并导致 Azure 重建环境通常只对多个环境共享一个资源组的部署使用或用于全新部署。若两个环境最终解析到相同名称publish/deploy 阶段会以明确的错误提示要求调用此方法。7.3 WithCompactResourceNaming针对卷相关存储资源Storage Account / File Share的命名优化。默认生成的名称使用较长的静态后缀如storageVolume、managedStorage会吃掉存储账号 24 字符名称上限的大部分空间截断提供跨部署唯一性的uniqueString。启用后缩短静态部分完整保留 13 字符的uniqueString避免向不同资源组部署多个环境时发生命名冲突builder.AddAzureContainerAppEnvironment(env) .WithCompactResourceNaming();该方法仅影响卷相关存储资源的命名不改变托管环境、注册表、Log Analytics 或托管标识的名称该 API 带有Experimental(ASPIREACANAMING001)实验性标记接口可能在未来版本调整。八、高级定制选项8.1 控制 Aspire Dashboard环境中默认附带 Aspire Dashboardaspire-dashboard组件2025-10-02-preview。可通过以下方式开关builder.AddAzureContainerAppEnvironment(env) .WithDashboard(enable: false); // 默认 true部署后 Dashboard 地址为https://aspire-dashboard.ext.default-domain仅在 Dashboard 启用时才会注册打印 URL 的摘要步骤AzureContainerAppEnvironmentResource.cs。8.2 使用现有的 Log Analytics 工作区默认环境会新建{env}_law工作区。若希望复用已有工作区builder.AddAzureLogAnalyticsWorkspace(logs); builder.AddAzureContainerAppEnvironment(env) .WithAzureLogAnalyticsWorkspace(logsBuilder);实现上通过AzureLogAnalyticsWorkspaceReferenceAnnotation标注引用现有工作区AzureContainerAppExtensions.cs。8.3 自定义 ACR 拉取身份WithAcrPullIdentity默认环境会创建新的用户分配标识并授予 AcrPull。若希望使用自己提供的用户分配标识例如配合AsExisting复用既有资源且不产生任何新的标识/角色资源builder.AddAzureUserAssignedIdentity(acrPullIdentity) .WithRoleAssignments(acr, ContainerRegistryBuiltInRole.AcrPull); builder.AddAzureContainerAppEnvironment(env) .WithAcrPullIdentity(acrPullIdentityBuilder);注意该方法中的标识仅用于 ACR 拉取AcrPull 角色并不会被附加到环境中的单个 Container App 上调用方需自行保证该标识已具备 AcrPull 权限AzureContainerAppExtensions.cs。8.4 引用已存在的环境AsExisting / PublishAsExisting当环境被标记为AsExisting时Aspire 不会生成新的托管环境、Log Analytics 工作区或 Dashboard 组件而是生成一个引用现有环境的薄模块并只补充新部署 Container App 所需的 ACR 拉取标识AzureContainerAppExtensions.cs。此时以下组合不被允许会直接抛错声明了卷挂载卷需要在托管环境上预配存储通过WithDelegatedSubnet配置了 VNet 集成VNet 是环境自身的属性无法对已存在环境重新配置通过WithAzureLogAnalyticsWorkspace指定工作区已存在环境已拥有自己的日志工作区。8.5 卷挂载与探针卷资源通过标准挂载 APIBindMount / Volume声明后环境会自动创建 Storage AccountStandardLRS、StorageV2、启用大文件共享、最低 TLS 1.2与 Azure Files 文件共享并以ContainerAppManagedEnvironmentStorageAzureFile读写模式挂载到环境AzureContainerAppExtensions.cs探针ContainerAppContext.AddProbes会把ProbeAnnotationStartup/Readiness/Liveness映射为 ACA 探针关联到 ingress 端点的探针强制使用http协议、目标端口BaseContainerAppContext.cs。8.6 环境变量与密钥BaseContainerAppContext.ProcessValue负责把值转换为 Bicep 表达式BaseContainerAppContext.cs普通字符串直接作为环境变量值端点引用解析为容器应用域名地址ParameterResource若标记为 Secret则注册为 Container App 密钥SecretRef密钥名由_转-并小写Key Vault 引用注册为 Key Vault 密钥引用并可选附加标识用于访问不支持的引用类型如自动 Key Vault 生成会明确抛错提示手动创建 Key Vault 资源。九、发布与部署publish / deploy / destroy 完整闭环9.1 aspire publish生成部署产物不触碰 Azureaspire publish生成 Bicep 模板与参数化的部署产物但不会预配任何 Azure 资源产物默认写入 AppHost 的aspire-output目录交互式部署过程中可提示选择订阅、位置与资源组。9.2 aspire deploy实际预配与部署aspire deploy解析 Azure 设置与参数预配 Container Apps 环境及其默认容器注册表构建并推送镜像部署应用。9.3 aspire destroy清理aspire destroy注意该命令会删除整个部署资源组包括并非由 Aspire 创建的资源请仅在确认无误后执行。9.4 安全提示本地运行不会预配 Container Apps 环境部署后的应用通过托管标识managed identity拉取镜像不依赖明文凭证敏感配置应放在 secret 参数或 Azure Key Vault 引用中而不是明文环境变量。十、测试验证与延伸阅读该集成的行为在仓库中有较完整的测试覆盖可作为自定义配置时的参考依据AzureContainerAppEnvironmentExtensionsTests.cs覆盖环境资源默认生成、WithAzdResourceNaming/WithCompactResourceNaming/WithUniqueResourceNaming命名策略、AsExisting引用现有环境等场景AzureContainerAppsTests.cs覆盖 Container App 发布与 Bicep 生成。更多相关背景可继续阅读仓库内文档docs/specs/aks-support.md多计算环境编排的设计背景、docs/azure.mdAzure 相关概览。若需在生产中落地请以当前仓库版本的 API 签名与实验性标记为准部分命名 API 标有Experimental特性后续版本可能调整。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考