企业官网建设流程全解析

Aspire CLI 完整命令参考：创建、运行、监控与部署分布式应用实战指南

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire

Aspire CLI 是 .NET Aspire 的命令行入口，用于创建、运行和管理基于 Aspire 的分布式应用。本文以 src/Aspire.Cli/README.md 的命令参考为骨架，结合仓库内 Commands 目录 的源码实现，系统讲解全局选项、五大命令族（应用管理、资源管理、监控、部署、工具配置）及完整实战示例，帮助你快速掌握从aspire new到aspire deploy的完整工作流，并学会在 CI/Agent 环境下以非交互方式驱动 CLI。

Aspire CLI 是什么

Aspire CLI 是 Aspire 项目（code-first、可扩展、可观测的开发与部署工具）的命令行前端，覆盖分布式应用生命周期的所有阶段：模板创建、项目初始化、集成添加、本地运行、资源状态监控、日志与可观测性数据查看，以及发布与部署。CLI 的核心命令注册位于 src/Aspire.Cli/Commands/RootCommand.cs，所有子命令通过 System.CommandLine 构建并挂载到根命令之下。

基本用法

所有命令遵循统一的调用形态：

aspire <command> [options]

不带任何子命令直接执行aspire时，CLI 会输出分组帮助信息（Grouped Help）并返回非零退出码，提示正确用法。帮助输出由 GroupedHelpWriter.cs 渲染，按命令族分组展示，比 System.CommandLine 默认的扁平帮助更易浏览。

全局选项

以下选项对所有子命令通用（源码定义见 RootCommand.cs）：

从源码看，根命令还内置了一批隐藏选项用于内部诊断：--debug（旧版调试开关，已隐藏，建议改用--log-level）、--log-file（将日志写入文件）、--capture-profile/--capture-profile-output/--capture-profile-delay（性能剖析采集，默认延迟 5 秒）。其中--log-level、--wait-for-debugger等选项在 CLI 以分离模式（detached）派生子进程时会被自动透传给子进程（见 RootCommand.cs 中的s_childProcessOptions）。

另外，当传入-h/--help/-v/--version这类纯信息性调用时，CLI 会跳过遥测上报与首次运行引导（见 CommonOptionNames.cs 的IsInformationalInvocation判断）。

命令总览

命令按职责分为五个族（帮助输出中的 HelpGroup 定义见 HelpGroups.cs）：

App 命令（应用管理）

资源管理（Resource Management）

监控（Monitoring）

部署（Deployment）

工具与配置（Tools & Configuration）

除上述命令外，根命令还按需挂载了terminal（终端）与setup（Bundle 安装）等命令。其中terminal默认隐藏在功能开关之后，可通过aspire config set features.terminalCommandsEnabled true开启（见 RootCommand.cs）。

App 命令详解

aspire new：创建新应用

aspire new从 Aspire 入门模板生成新应用，是开始一个新 Aspire 分布式应用最快的方式。它会引导选择模板类型与目标语言，并基于选定的 channel 解析对应版本的模板包（stable / staging / daily / pr-N 等身份渠道），确保本地 CLI 与生成的模板版本一致。

aspire init：初始化现有代码库

aspire init在已有代码库中放入一个最小化的 AppHost 骨架（必要时附带aspire.config.json），随后链式调用aspire agent init安装对应的 Agent skill 来完成后续接线工作。从源码看，init本质是一个"瘦启动器"——项目发现、依赖配置、校验等重活被委托给aspireifyskill（见 InitCommand.cs）。

其核心执行流程为（InitCommand.cs）：

1. 语言选择：解析--language或交互式提示选择项目语言；
2. 方案探测（仅 C# 且非 file-based）：通过ISolutionLocator查找现有.sln/.slnx；
3. 生成骨架：C# 走apphost.cs单文件或aspire-apphost模板工程两条路径，其他语言（Go、Java、Python、TypeScript 等）走 polyglot 脚手架路径；
4. 信任开发证书（C# 路径）：自动执行证书信任，避免首次aspire start出现证书错误（失败不阻塞，可用aspire doctor/aspire certs trust兜底）；
5. 链式 Agent 初始化：预选全部 bundle skill（含 aspireify），但不注册 MCP——MCP 配置只能通过独立的aspire agent init显式开启；
6. 输出后续命令：若用户选择了一次性 init skill，会打印如claude "run the aspireify skill"或opencode --prompt "run the aspireify skill"的跟进命令。

C# 单文件骨架会生成如下apphost.cs内容（InitCommand.cs）：

#:sdk Aspire.AppHost.Sdk@<version> #:property AspireUseCliBundle=true var builder = DistributedApplication.CreateBuilder(args); // The aspireify skill will wire up your projects here. builder.Build().Run();

同时还会生成aspire.config.json（含appHost.path、appHost.language、channel以及 https/http 双 profile，覆盖 dashboard / OTLP / 资源服务的端口与环境变量）和apphost.run.json（供dotnet run apphost.cs使用）。两个文件共享同一组随机生成的端口，保证无论用aspire run还是dotnet run apphost.cs启动，dashboard 与 OTLP 端点都一致。

aspire add：添加集成

aspire add [<integration>]向 apphost 添加托管集成（integration）。integration 参数可选——省略时会交互式搜索并选择。核心选项包括：

• --version：指定集成包版本；
• --source, -s：指定 NuGet 源；
• --all：添加所有可用集成；
• --apphost/--project：显式指定 AppHost 工程文件（多个候选时也可交互选择）。

该命令内部通过 IntegrationPackageSearchService.cs 按aspire.config.json中配置的 channel 解析包，并对 .NET 项目先确保 SDK 已安装（见 AddCommand.cs）。

aspire run：开发模式运行

aspire run是本地开发的主命令，负责构建并启动 AppHost，随后连接 AppHost 回通道（backchannel），展示 dashboard 地址与实时资源状态。源码层面的关键行为（RunCommand.cs）：

• --detach：分离模式，启动 AppHost 后 CLI 立即退出，适合后台启动；
• --no-build：跳过构建（隐含--no-restore；在 watch 模式开启时不允许使用）；
• --format json：仅可与--detach组合使用，输出DetachOutputInfo（AppHostPath、AppHostPid、CliPid、DashboardUrl、LogFile）；
• 启动超时可通过ASPIRE_CLI_START_TIMEOUT环境变量配置；
• 按下 Ctrl+C 视为正常退出路径，返回成功退出码；
• 运行期间会先等待构建完成，再等待 AppHost 回通道就绪，最后渲染 dashboard 摘要、资源端点与日志流；
• 在 VS Code Aspire 终端中运行时，会拦截并委托扩展启动调试/运行会话（非交互模式除外）。

aspire stop/aspire ps：停止与列举

• aspire stop停止正在运行的 apphost（可加stop <resource>只停止指定资源）；
• aspire ps列出所有正在运行的 apphost，支持--format json（输出 AppHostPath、AppHostPid、Status、SdkVersion、CliPid、DashboardUrl、LogFilePath，见 PsCommand.cs）与--follow持续刷新。

aspire update：更新集成

aspire update更新 Aspire 项目中的托管集成包版本，适合在 CLI 或 Aspire 版本升级后同步项目依赖。

资源管理命令详解

aspire start：后台启动

aspire start以分离模式在后台启动 AppHost 并立即返回，非常适合 CI 与 Agent 环境（文档推荐aspire start --isolated）。支持--no-build、--format json等选项，并可通过--isolated以隔离方式运行（隔离模式下如果发现已有实例被停止，会给出警告）。分离启动时 CLI 会派生子进程承载 AppHost，同时通过 LauncherLivenessMonitor 监控启动器存活，避免启动器被杀后残留子进程（见 StartCommand.cs 与 RunCommand.cs）。

aspire wait：等待资源就绪

aspire wait <resource>是 CI/脚本场景的核心命令，等待指定资源达到目标状态后才返回。关键选项（见 WaitCommand.cs）：

• --status：目标状态，可选healthy（默认）、up、down；
• --timeout：超时秒数，默认120 秒，必须为正数；
• --apphost/--project：指定 AppHost 工程文件。

--status仅接受healthy/up/down三个取值（源码中的IsValidStatus校验），不合法会直接报错退出。成功时会输出资源达到目标状态所消耗的秒数；超时返回WaitTimeout退出码，资源不存在或进入失败状态返回WaitResourceFailed退出码，便于脚本分支处理。

aspire restart/aspire command

• aspire restart <resource>重启正在运行的资源；
• aspire command <resource> <command>在资源上执行由 AppHost 定义的自定义命令（例如数据库迁移、数据种子等）。

监控命令详解

aspire describe：资源状态

aspire describe [<resource>]描述正在运行的 apphost 中的资源状态，别名resources。主要选项（见 DescribeCommand.cs）：

• --follow, -f：持续流式输出资源状态变化；
• --format：输出格式（支持 JSON）；
• --include-hidden：包含隐藏资源；
• --apphost/--project：指定 AppHost 工程文件。

--format json输出ResourcesOutput包装结构（Resources 数组，每个资源含名称、类型、状态、端点、健康报告、关系与命令等字段，见 DescribeCommand.cs）。

aspire logs：查看日志

aspire logs [<resource>]显示资源日志，不传资源名则显示全部资源。支持选项（见 LogsCommand.cs）：

• --follow, -f：持续跟踪新日志（NDJSON 流式输出）；
• --format：输出格式（支持 JSON，快照为 pretty JSON、follow 为 NDJSON，一行一条日志）；
• --tail, -n：只显示末尾 N 行；
• --timestamps, -t：显示时间戳；
• --include-hidden：包含隐藏资源日志；
• --search：按关键字过滤日志；
• --apphost/--project：指定 AppHost 工程文件。

aspire otel：OpenTelemetry 数据

aspire otel查看运行中 apphost 的 OpenTelemetry 数据。从源码目录看，其下细分otel logs（TelemetryLogsCommand.cs）、otel spans（TelemetrySpansCommand.cs）与otel traces（TelemetryTracesCommand.cs）三个子命令，分别查看日志、Span 与 Trace。

部署命令详解

部署命令族覆盖应用从产物生成到环境销毁的完整生命周期：

• aspire publish：为 apphost 生成部署产物（如容器镜像、清单等）；
• aspire deploy：将 apphost 部署到其部署目标（Azure 等）；
• aspire destroy：销毁先前部署的 AppHost 环境（清理云端资源，注意不可逆）；
• aspire do <step>：执行流水线中的特定步骤及其依赖，基于 PipelineCommandBase.cs 构建，用于精细控制部署流水线的执行粒度。

工具与配置命令详解

aspire config：CLI 配置

管理 CLI 配置与功能开关，典型的用法是读写 feature flags，例如开启实验性终端命令：

aspire config set features.terminalCommandsEnabled true

aspire cache：磁盘缓存

管理 CLI 操作产生的磁盘缓存（模板包、NuGet 元数据等），用于清理或查看缓存占用。

aspire doctor：环境诊断

aspire doctor诊断 Aspire 环境问题并验证安装，是排查环境问题的第一站。它会执行一系列环境前置检查（.NET SDK、容器运行时等，见 Utils/EnvironmentChecker 目录与 DoctorCommand.cs），同时发现机器上所有 Aspire 安装信息（含 winget 首启探测）。支持--format json结构化输出检查结果与安装信息；退出码约定为：所有检查通过返回 0，存在失败项（EnvironmentCheckStatus.Fail）返回非零（见 DoctorCommand.cs），便于 CI 判定。

aspire docs：文档与 API 搜索

aspire docs从命令行浏览和搜索 Aspire 文档与 API 参考。典型用法：

# 搜索 API 参考（指定语言过滤） aspire docs api search "RunAsEmulator" --language csharp # 搜索 Aspire 文档 aspire docs search "redis"

aspire agent：AI Agent 配置

aspire agent管理 AI Agent 相关的环境配置。当前仓库中aspire init会链式调用aspire agent init为 Claude Code / OpenCode 等 Agent 安装 Aspire skill（含 aspireify 接线技能）；独立的aspire agent init还可显式注册 MCP 配置（相关设计见 docs/specs/cli-mcp.md）。源码参见 Commands/AgentCommand.cs 与 Commands/AgentInitCommand.cs。

实战示例合集

以下示例覆盖从创建到运维的完整工作流（全部来自文档并补充了说明）：

初始化现有代码库（file-based 模式）

aspire init --file-based --language csharp

该命令从仓库根目录执行时，会在当前目录生成apphost.cs及其配套配置，而不是创建基于解决方案（solution）的 AppHost 工程。要点：

• --file-based模式跳过对现有.sln/.slnx文件的探测，避免被"偶然"发现的解决方案触发交互提示；
• --file-based仅支持 C#：如果显式指定了其他语言、配置了其他语言、或在语言提示中选择了其他语言，都会在脚手架生成前直接报错；
• 省略--file-based（或传--file-based false）则走正常的非 C# 脚手架流程；
• 该命令不会覆盖已有的 AppHost，也不会抑制 Agent 设置（默认仍会执行 agent init 链式流程）。

创建并运行新应用

# 创建新的 Aspire 应用 aspire new # 运行 apphost（开发模式，前台） aspire run

后台启动与状态检查（CI / Agent 场景）

# 后台启动（适合 CI 与 Agent 环境） aspire start --isolated # 检查资源状态 aspire describe # 持续流式跟踪资源状态变化 aspire describe --follow # 查看日志（全部资源或指定资源） aspire logs aspire logs webapi

停止与等待就绪

# 停止 apphost aspire stop # 等待资源达到 healthy 状态（CI/脚本中先启动再等待） aspire start aspire wait webapi --timeout 60

wait默认等待 120 秒，--timeout 60可缩短为 60 秒；如需等待其他状态，可用--status up或--status down。

添加集成与诊断

# 添加 Redis 集成 aspire add redis # 诊断环境问题 aspire doctor

文档与 API 搜索

# 搜索 API 参考（指定语言过滤） aspire docs api search "RunAsEmulator" --language csharp # 搜索 Aspire 文档 aspire docs search "redis"

面向自动化：JSON 输出与退出码

在 CI 流水线与 Agent 场景中，除--non-interactive全局选项外，多个命令支持--format json结构化输出：

• aspire ps --format json：运行中 AppHost 列表；
• aspire describe --format json：资源快照（含端点、健康报告）；
• aspire logs --format json（快照）与aspire logs --format json --follow（NDJSON 流式）；
• aspire start --format json与aspire run --detach --format json：分离启动信息（AppHost PID、CLI PID、Dashboard URL、日志文件路径）；
• aspire doctor --format json：环境检查与安装信息。

这些 JSON 契约的详细字段说明统一维护在 docs/specs/cli-output-formats.md，源码中的 JSON 序列化上下文（如 PsCommand.cs 的PsCommandJsonContext、LogsCommand.cs 的LogsCommandJsonContext）均在注释中明确要求与规范保持同步。

同时注意命令的退出码语义：wait超时与资源失败区分不同退出码；run在用户 Ctrl+C 时返回成功；doctor依据检查结果返回 0 或非零。编写脚本时应针对具体命令的退出码约定做分支处理。

延伸阅读

• CLI 输出格式规范：--format json各命令的字段契约；
• CLI 与 MCP 集成设计：agent命令与 MCP 工具相关设计；
• CLI 身份 sidecar 设计：--version与身份渠道解析机制；
• CLI 实现源码：src/Aspire.Cli/Commands（各命令实现）与 src/Aspire.Cli/Program.cs（入口）。

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire