十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Aspire 集成 Azure App Configuration:配置、预置与本地模拟器实战指南

Aspire 集成 Azure App Configuration:配置、预置与本地模拟器实战指南 Aspire 集成 Azure App Configuration配置、预置与本地模拟器实战指南【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本指南以 Aspire 开源仓库中的 Aspire.Hosting.Azure.AppConfiguration 集成文档 为核心完整讲解如何在 Aspire AppHost 中建模、配置并编排 Azure App Configuration 资源包括添加集成、配置本地开发期 Azure 预置、C#/TypeScript 双语言引用方式并深入源码剖析资源模型、默认角色分配、私有终结点与本地模拟器Emulator等底层机制。读完本文你将能在自己的 Aspire 解决方案中端到端接入 Azure App Configuration并掌握本地开发与云端部署两套完整工作流。集成概览在 Aspire 中建模 Azure App ConfigurationAspire.Hosting.Azure.AppConfiguration是 Aspire 的托管集成之一作用是在 Aspire 的应用模型中建模、配置并编排Azure App Configuration 资源。它位于仓库 src/Aspire.Hosting.Azure.AppConfiguration 目录从项目文件 Aspire.Hosting.Azure.AppConfiguration.csproj 可以看到它依赖Aspire.Hosting.AzureAzure 托管基础以及Azure.Provisioning、Azure.Provisioning.AppConfiguration两个预置Provisioning库说明该集成不仅负责资源建模还承担了从代码生成 Bicep 基础设施的职责。集成对外暴露的核心 API 均收敛在 AzureAppConfigurationExtensions.cs 中包括AddAzureAppConfiguration(name)向应用模型添加 Azure App Configuration 资源RunAsEmulator(configureEmulator)在本地以容器模拟器运行该资源WithRoleAssignments(...)为资源分配 App Configuration 内置角色WithDataBindMount/WithDataVolume/WithHostPort模拟器数据持久化与端口配置。对应的资源类型定义在 AzureAppConfigurationResource.cs它实现了IResourceWithConnectionString、IResourceWithEndpoints与IAzurePrivateEndpointTarget等接口意味着它天然支持连接字符串注入、终结点暴露以及 Azure 私有终结点Private Endpoint能力。快速开始添加集成前置条件使用该集成的前提是拥有一个Azure 订阅。本地开发期若要让 Aspire 自动完成 Azure 资源预置开发者还需要对目标订阅具备Owner 权限——原因是预置过程会为资源配置角色分配Role Assignments这需要较高权限级别原文档中对此有明确提醒。使用 Aspire CLI 添加集成在 AppHost 项目目录下执行以下命令即可将Aspire.Hosting.Azure.AppConfiguration集成添加到当前解决方案aspire add Aspire.Hosting.Azure.AppConfiguration该命令会为 AppHost 项目添加对应的包引用之后便可在Program.csC#或apphost.mtsTypeScript中调用集成提供的 API。配置 Azure 预置为本地开发做准备将 Azure 资源加入 AppHost 模型后Aspire 会自动启用**开发期 Azure 预置development-time provisioning**能力——即无需手动在 Azure 门户创建资源Aspire 会在本地开发运行时按需为你预置。这一机制对应源码中AddAzureAppConfiguration第一行调用的builder.AddAzureProvisioning()见 AzureAppConfigurationExtensions.cs。预置过程需要从 AppHost 配置中读取若干设置使用aspire secret set在 AppHost 目录下写入即可aspire secret set Azure:SubscriptionId your subscription id aspire secret set Azure:ResourceGroupPrefix prefix for the resource group aspire secret set Azure:Location azure location三个配置项的作用分别是配置键含义建议Azure:SubscriptionId目标 Azure 订阅 ID填入订阅 GUIDAzure:ResourceGroupPrefix预置资源组的名称前缀预置时会基于前缀生成资源组Azure:LocationAzure 区域如eastus、westeurope等注意开发者必须对目标订阅拥有Owner访问权限这样预置出来的资源才能成功配置角色分配Role Assignments。这是原文档明确强调的硬性前提。使用示例C# 与 TypeScript 双语言接入C# AppHost在 C# AppHost 中通过AddAzureAppConfiguration创建连接再通过WithReference注入到其他资源var appConfig builder.AddAzureAppConfiguration(config); var myService builder.AddProjectProjects.MyService() .WithReference(appConfig);WithReference会把连接信息连接字符串以环境变量的形式注入MyService服务即可通过标准配置读取方式消费 App Configuration。TypeScript AppHost在 TypeScript AppHostAspire 的多语言应用宿主中写法是对应的异步 APIconst appConfig await builder.addAzureAppConfiguration(config); const myService await builder.addNodeApp(myService, ../my-service, server.js) .withReference(appConfig);TypeScript 侧的能力清单可以查看集成生成的 Aspire Type System 描述文件 Aspire.Hosting.Azure.AppConfiguration.ats.txt其中列出了addAzureAppConfiguration、runAsEmulator、withAppConfigurationRoleAssignments、withDataBindMount、withDataVolume、withHostPort等全部可调用能力以及AzureAppConfigurationRole枚举AppConfigurationDataOwner、AppConfigurationDataReader。仓库 tests/PolyglotAppHosts/Aspire.Hosting.Azure.AppConfiguration/TypeScript/apphost.mts 给出了一个完整的 TypeScript 用法创建资源后调用withAppConfigurationRoleAssignments分配角色再通过runAsEmulator的configureEmulator回调配置数据绑定挂载、数据卷与宿主机端口。资源命名注意事项建议将资源名称设置为 config、appconfig 之外的名称。尽管部署时 Aspire 会自动追加随机后缀但仍有发生名称冲突的可能。这一提示背后有真实的工程考量从 AzureAppConfigurationExtensionsTests.cs 生成的 Bicep 可以看到实际部署名称形如take(appConfig-${uniqueString(resourceGroup().id)}, 50)——即资源名 uniqueString 后缀并被截断到 50 个字符因此短小通用的名称更易撞车。云端预置的底层原理资源模型与 Bicep 生成预置资源的结构AddAzureAppConfiguration在 AzureAppConfigurationExtensions.cs 中通过configureInfrastructure回调完成云资源的建模核心配置包括SKU固定为standard本地认证默认DisableLocalAuth true禁用本地访问密钥认证强制走托管标识/Entra ID标签写入aspire-resource-name标签以标识资源归属私有终结点若资源带有PrivateEndpointTargetAnnotation注解则自动设置PublicNetworkAccess Disabled仅允许私有网络访问。预置完成后集成会输出三个 Provisioning 输出供下游引用输出名内容用途appConfigEndpoint配置存储终结点 URL作为连接字符串主体注入name实际部署的资源名称用于外部化角色分配id资源 Azure 资源 ID用于私有终结点支持测试验证的 Bicep 形态单元测试 AzureAppConfigurationExtensionsTests.cs 锁定了生成 Bicep 的形态可直接对照理解云端部署产物description(The location for the resource(s) to be deployed.) param location string resourceGroup().location resource appConfig Microsoft.AppConfiguration/configurationStores2024-06-01 { name: take(appConfig-${uniqueString(resourceGroup().id)}, 50) location: location properties: { disableLocalAuth: true } sku: { name: standard } tags: { aspire-resource-name: appConfig } } output appConfigEndpoint string appConfig.properties.endpoint output name string appConfig.name output id string appConfig.id同时生成的清单manifest为azure.bicep.v0类型连接字符串取自{appConfig.outputs.appConfigEndpoint}——这解释了WithReference注入的最终连接字符串是如何在运行时被解析的。默认角色分配默认情况下引用该 App Configuration 资源的资源会被分配AppConfigurationDataOwner内置角色。测试中的角色 Bicep 展示了实际的角色定义 ID5ae67dd6-50cb-40e7-96ff-dc2bfa4b606b对应 App Configuration Data Owner。若想改为只读访问可通过WithRoleAssignments替换默认分配var builder DistributedApplication.CreateBuilder(args); var appStore builder.AddAzureAppConfiguration(appStore); var api builder.AddProjectProjects.Api(api) .WithRoleAssignments(appStore, AppConfigurationBuiltInRole.AppConfigurationDataReader) .WithReference(appStore);说明AppConfigurationBuiltInRole属于Azure.Provisioning类型不能直接用于多语言polyglotAppHostTypeScript 等场景请使用基于 AzureAppConfigurationRole 枚举的withAppConfigurationRoleAssignments重载见 Aspire.Hosting.Azure.AppConfiguration.ats.txt。本地开发使用模拟器Emulator启用模拟器与真实云端资源不同本地开发时可通过RunAsEmulator()将资源切换为容器化的本地模拟器避免依赖 Azure 云端。调用后会做以下几件事见 AzureAppConfigurationExtensions.cs暴露名为emulator的 HTTP 终结点容器目标端口为8483注册针对/health路径的 HTTP 健康检查测试RunAsEmulatorRegistersHealthCheck验证了appconfig_emulator_/health_200_check注解绑定官方模拟器镜像mcr.microsoft.com/azure-app-configuration/app-configuration-emulator:1.2.0版本常量见 AppConfigurationEmulatorContainerImageTags.cs默认开启匿名访问Anonymous Auth匿名用户角色为Owner对应环境变量Tenant:AnonymousAuthEnabledtrue与Authentication:Anonymous:AnonymousUserRoleOwner见WithAnonymousAccess内部实现。从 AzureAppConfigurationResource.cs 可以确认模拟器模式下的连接字符串会被自动改写为本地模拟器形态Endpoint{emulator endpoint url};Idanonymous;Secretabcdefghijklmnopqrstuvwxyz1234567890;AnonymousTrue即本地开发时注入给下游服务的连接字符串自动指向模拟器而IsEmulator this.IsContainer()则用于运行时区分当前是模拟器还是云端资源部署Publish模式下RunAsEmulator会被直接跳过见ExecutionContext.IsPublishMode判断。数据持久化与端口配置模拟器资源还提供三类常用配置1. 数据绑定挂载——将模拟器数据持久化到宿主机目录builder.AddAzureAppConfiguration(config) .RunAsEmulator(emulator emulator.WithDataBindMount());默认挂载路径为 AppHost 目录下的.aace/{资源名}映射到容器内/app/.aace也可显式指定路径WithDataBindMount(./my-data)。2. 命名数据卷——改用 Docker 命名卷持久化.RunAsEmulator(emulator emulator.WithDataVolume());未指定名称时卷名由VolumeNameGenerator.Generate基于应用名与资源名自动生成挂载点为容器内/app。3. 固定宿主机端口——默认端口是随机分配的需要固定时可调用.RunAsEmulator(emulator emulator.WithHostPort(8483));传null则继续使用随机端口。TypeScript 下三者对应withDataBindMount({ path })、withDataVolume({ name })、withHostPort({ port })完整可运行示例见 PolyglotAppHosts 的 apphost.mts。私有终结点与既有资源接入私有终结点支持AzureAppConfigurationResource.cs 中实现了IAzurePrivateEndpointTarget接口声明了Private Link 组 IDconfigurationStores私有 DNS 区域privatelink.azconfig.io。配合AddAzureAppConfiguration中的PrivateEndpointTargetAnnotation检查一旦在应用中配置了私有终结点预置的存储会自动关闭公网访问PublicNetworkAccess Disabled从而构建出完全私有化的配置访问链路。接入既有 App ConfigurationAzureAppConfigurationResource.AddAsExistingResource见 AzureAppConfigurationResource.cs支持将应用模型中已存在的配置存储以既有资源方式引用先检查 Bicep 标识符是否已注册以避免重复再以AppConfigurationStore.FromExisting建立引用若附加了ExistingAzureResourceAnnotation对应.AsExisting(name, resourceGroup)API则直接沿用注解中的名称与资源组。对应测试AddAsExistingResource_ShouldBeIdempotent_ForAzureAppConfigurationResource与AddAsExistingResource_RespectsExistingAzureResourceAnnotation_ForAzureAppConfigurationResource分别验证了幂等性与注解行为。更多参考集成完整的 ATS API 能力清单Aspire.Hosting.Azure.AppConfiguration.ats.txt托管扩展实现AzureAppConfigurationExtensions.cs资源类型定义AzureAppConfigurationResource.cs单元测试AzureAppConfigurationExtensionsTests.csTypeScript 端到端示例PolyglotAppHosts 的 apphost.mts本集成遵循 Apache/MIT 开源协议贡献与反馈可参考仓库根目录的 CONTRIBUTING 相关文档 与 AGENTS.md。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表