
Aspire hosting 集成分类矩阵用四个维度确定 Aspire.Hosting 集成的资源形态与生命周期【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire这篇技术文章讲解 Aspire 仓库中用于创作与评审Aspire.Hosting.*集成的分类矩阵selector matrix。该矩阵来自仓库的 hosting-integration-authoring 技能文档是 Agent 与开发者在新增或评审任何 hosting 集成时的第一份检查清单先沿资源形态resource shape、生命周期模式lifecycle mode、角色role、结构structure四个维度组合打分再决定该套用哪种原型archetype与哪些横切规范。读完后你能掌握对任意 Aspire 集成数据库、Azure 资源、隧道工具、部署目标等进行系统化分类的方法并理解每个分类取值在src/Aspire.Hosting源码中对应的具体类型。矩阵在 Aspire 集成开发流程中的位置Aspire 的 hosting 集成不是写一个Add*扩展方法就完事的工作。仓库中的 SKILL.md 定义了完整工作流先读 selector-matrix.md——即本文的主角用于对集成进行分类再读应用模型基础规则按四个维度资源形态、生命周期模式、角色、结构完成分类然后按分类结果读取对应的原型文档与横切规范文档命名、连接属性、多语言导出、端点语义、安全等创作或评审时先声明分类结论再套用对应原型的 DO/DONT 清单。关键原则是不要强行把集成塞进单一类别。如 SKILL.md 所述PostgreSQL 同时是容器支撑的服务 父子数据库子资源 连接属性 就绪时建库 管理 UI 伴随工具是多个模式的组合体。轴一资源形态Resource shape资源形态回答这个集成的主资源是什么类型的 C# 对象。矩阵列出了 12 种形态每种都映射到src/Aspire.Hosting中的基础类型并指向对应的原型文档均位于 resources 目录。以下完整继承矩阵原文并补充源码佐证形态典型基类/类型例子对应原型文档容器支撑的服务Container-backed serviceContainerResourceMongoDB、PostgreSQL、Redis、Kafka、RabbitMQarchetype-container-backed-service.md管理/工具容器Admin/tool containerContainerResourceAdminer、DbGate、MCP Inspector、k6archetype-admin-and-tool-container.md设置/迁移助手Setup or migration helperExecutableResource、ContainerResource或带元数据的ResourceFlyway、SQL DACPAC 部署、包安装器、模型拉取archetype-setup-and-migration-helper.md控制器/协调器Controller/reconciler单例控制器服务 环境/控制资源Azure run 模式供给控制器、部署协调器、本地基础设施 operatorarchetype-controller-reconciler.md边车/中间件基础设施Sidecar/middleware边车/组件资源 注解Dapr sidecars/components、OpenTelemetry Collectorarchetype-sidecar-and-middleware.md隧道/Webhook 桥Tunnel/webhook bridgeContainerResource或ExecutableResourceNgrok、Stripe CLI webhook 转发archetype-tunnel-and-webhook-bridge.md密钥提供者/中介Secret provider/brokerResource 值提供者或流水线步骤Bitwarden Secrets Manager、外部密钥中介archetype-secret-provider.mdAzure 供给服务Azure provisioning serviceAzureProvisioningResourceAzure Storage、Cosmos DB、Key Vault、Service Bus、Azure SQLarchetype-azure-provisioning.md外部/云端引用External/cloud referenceResource 连接属性OpenAI、GitHub Models、外部 APIarchetype-external-cloud-reference.md可执行/语言应用Executable/language appExecutableResourcePython、Go、JavaScript、Node、Vite、Next.jsarchetype-language-executable-app.md部署目标/发布器Deployment target/publisher环境资源 部署目标注解Docker Compose、Kubernetes、Azure Container Appsarchetype-deployment-target-publisher.md叠加/配置对象Overlay/configuration object自定义非资源模型对象Orleans 风格的 app model 叠加archetype-overlay-configuration.md从源码结构看这些基类真实存在于核心库中ContainerResource 是容器类服务的统一基类构造器除name外还接受entrypoint参数ExecutableResource 同时实现了IResourceWithEnvironment、IResourceWithArgs、IResourceWithEndpoints、IResourceWithWaitSupport、IResourceWithProbes等接口——这解释了为什么语言应用和设置助手两个形态都能用ExecutableResource承载可执行进程天然带参数、端点、健康探针与等待能力AzureProvisioningResource 继承自AzureBicepResource构造器接收ActionAzureResourceInfrastructure基础设施配置回调对应表中Azure 供给服务形态IResourceWithParent接口定义在 IResourceWithParentOfT.cs是父子结构的源码依据。值得注意的一点矩阵把Adminer与PostgreSQL都归为ContainerResource但分别落到不同原型管理工具 vs 服务。这说明基类相同不代表架构相同——资源形态只是四个维度之一必须结合角色与结构共同判定。轴二生命周期模式Lifecycle mode生命周期模式回答这个集成在 run / publish / deploy 三个阶段中的哪个阶段存在。矩阵给出 5 种模式模式含义常见 API 形态Run-capable publish/deploy participant可运行且参与发布/部署本地可运行同时参与 manifest 或部署输出Add{Service}、子级Add{Resource}方法Run-only仅运行仅存在于本地开发/运行编排在 publish/deploy 输出中被排除或 no-opWith{DevTool}、setup 同级资源Publish/deploy-only仅发布/部署仅存在于生成或应用部署输出期间Add{Target}Environment、PublishAs{Target}Dual-mode双模式本地是一种形态发布/部署时是另一种形态Azure 资源的RunAsEmulator、RunAsContainer、InnerResource、IsContainerMode-agnostic reference模式无关引用run 与 publish 中使用相同的应用模型表示外部端点/API key 资源这个轴直接决定评审时的验证范围如 SKILL.md 的创作工作流第 4 条要求当集成改变了 run/publish/deploy 任一面时两种行为都要验证。例如 Adminer 是 Run-only 的它不该出现在生产部署里而 PostgreSQL 是 Run-capable participant本地跑容器、部署时生成对应声明Azure Storage 则是典型的 Dual-mode——本地用 Azurite 模拟器、云上供给真实资源RunAsEmulator/RunAsContainer这一组 API 就是为此设计的。轴三角色Role角色回答这个集成在应用图中扮演什么身份。矩阵列出 11 种角色角色职责服务依赖Service dependency被 workload 通过WithReference引用的资源Workload/应用Workload/app运行应用代码部署目标Deployment target在 publish/deploy 时接收计算资源管理/开发伴随工具Admin/dev companion父服务的可选本地 UI/工具容器独立开发工具Standalone dev tool不隶属于单一父级、共享或独立的本地工具子/子资源Child/subresource数据库、队列、主题、hub、模型、部署、容器等子级对象Setup 同级资源Setup sibling在 workload 启动前为其做准备的 run 模式助手边车/中间件Sidecar/middleware通过注解附着到一个或多个 workload 的进程或配置桥/代理Bridge/proxy向外部系统暴露或转发端点的本地资源密钥提供者Secret provider为其他资源管理或解析密钥/凭据控制器/协调器Controller/reconciler串行化命令、生命周期事件、后台探测与实时状态对账角色维度是连接资源形态与具体资源类的语义桥梁。WithReference、IResourceWithConnectionString等 Aspire.Hosting 核心 API 在矩阵中都以角色取值的身份出现——SKILL.md 进一步要求凡涉及IResourceWithConnectionString、WithReference、环境变量、URI/JDBC 属性的改动还要额外阅读连接属性横切文档。轴四结构Structure结构回答Add*API 的形状和资源的归属关系是怎样的。矩阵给出 8 种结构模式结构模式独立Standalone顶层Add{Technology}返回IResourceBuilderT父子Parent-child子级Add*方法暴露于父级 builder 上子资源实现IResourceWithParentTParent伴随Companion父级With{Tool}方法添加隐藏/排除的伴随资源并返回原父级 builder单例工具Singleton utility顶层Add{Tool}重复调用时返回已存在的单例 builder合成门面Synthetic facade资源本身没有独立的 DCP 进程/容器其状态、端点与生命周期由另一个资源或外部服务驱动控制器驱动Controller-driven资源命令与生命周期钩子把类型化 intent 排入串行控制器/协调器注解驱动Annotation-drivenfluent API 添加注解生命周期钩子发现注解并物化派生资源叠加OverlayAdd*返回非资源的配置对象资源接线通过WithReference、AsClient等完成这 8 种结构在IResourceBuilderT返回类型、IResourceWithParentTParent接口、builder 链式返回值等可验证的 API 特征上逐一对应评审一个 PR 时只需观察新增扩展方法的接收者、返回类型和参数形态即可判定它属于哪种结构。例如 Companion 的判定特征是方法名以With开头、返回原父级 builder如WithAdmin之于数据库资源Parent-child 的判定特征是子级资源类实现IResourceWithParentTParent其接口定义可参见 IResourceWithParentOfT.cs。分类实例把 11 个真实集成放回矩阵矩阵末尾给出了一份现成的分类示范它是学习本方法最快的材料——每个集成都是四轴取值的组合而非单桶标签集成分类形态 生命周期 角色 结构PostgreSQL容器支撑服务 可运行发布/部署参与者 服务依赖 父子 管理伴随Azure Storage配 AzuriteAzure 供给服务 双模式 服务依赖 子资源 模拟器Docker Compose部署目标/发布器 仅发布/部署 环境资源 逐资源PublishAs*定制Python Uvicorn 应用可执行/语言应用 run 与 publish workload 生成的 DockerfileOpenAI外部/云端引用 模式无关 服务依赖 可选子模型/部署资源Orleans叠加/配置对象 对计算资源的资源引用Adminer管理/工具容器 仅运行 独立单例工具Dapr边车/中间件基础设施 run/deploy 桥接 注解驱动的 sidecar/componentNgrok隧道/webhook 桥 仅运行 桥/代理Dev Tunnel 端口隧道/webhook 桥 仅运行 桥/代理 合成门面端点Azure run 模式供给控制器/协调器 run 模式可见的环境控制资源 隐藏/排除的发布标记 命令驱动的资源操作 漂移检测SQL DACPAC设置/迁移助手 仅运行或部署阶段 setup 服务态部署从中可以读出几条实用的判断规律同一形态不同结局Adminer 与 PostgreSQL 同为容器资源但前者仅运行 单例后者可发布 父子 伴随——生命周期轴和结构轴才是区分两者架构的关键桥接类集成常带合成门面Dev Tunnel 端口本身不是独立进程端点由外部隧道服务驱动这正是Synthetic facade结构的典型实例控制型集成最复杂Azure run 模式供给一行里堆叠了控制器、隐藏发布标记、命令驱动操作与漂移检测四类特征对应仓库中 Aspire.Hosting.Azure 里体量最大的供给控制器实现。如何使用这个矩阵操作要点结合 SKILL.md 的工作流矩阵的使用方法是先声明分类在改动或评审Aspire.Hosting.*集成代码之前先用四轴取值把集成点名如这是一个 Executable/language app run and publish workload声明要简短按形态取原型轴一的结果决定读哪个 archetype 文档——仓库当前实际存在全部 12 个原型文档位于 .agents/skills/hosting-integration-authoring/resources/ 下可一一对上按轴二定验证范围Run-only 集成无需验证部署输出Dual-mode 集成必须同时验证本地形态与云上形态按轴四定 API 形状Add*/With*的接收者与返回类型必须符合所选结构这是评审时最容易被违反、也最容易一眼发现的点评审聚焦实质问题SKILL.md 明确要求评审只关注会导致运行时行为错误、生成 manifest 错误、部署输出损坏、公共 API 缺陷、连接属性缺失或 polyglot 投影错误的具体问题不花在纯风格评论上。小结selector-matrix.md 的价值在于把Aspire hosting 集成怎么写这件模糊的事压缩成了 4 个维度 × 共 36 个可枚举取值12 形态 5 生命周期 11 角色 8 结构加上 11 个标注好的真实示例。矩阵中的每个基类名ContainerResource、ExecutableResource、AzureProvisioningResource、IResourceWithParent都能在 src/Aspire.Hosting 与 src/Aspire.Hosting.Azure 中找到对应实现每个原型取值都指向一份已入库的 archetype 文档。对开发者而言它既是新集成动手前的分类器也是 PR 评审时的核对表先给集成分类再决定套用什么原型与横切规范避免一个Add*方法式的片面实现。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考