Aspire CLI 完整命令参考创建、运行、监控与部署分布式应用实战指南【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspireAspire 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选项说明-h, /h显示帮助与用法信息。除-h、/h外--help、-?、/?同样是合法的帮助开关见 CommonOptionNames.cs。-v, --version显示版本信息。-v是--version的短别名由根命令在初始化时注入。版本输出会解析 CLI 的身份渠道identity channel因此能正确反映ASPIRE_CLI_VERSION或安装 sidecar 覆盖后的真实版本。-l, --log-level设置控制台输出的最低日志级别取值为Trace、Debug、Information、Warning、Error、Critical。用于排查 CLI 自身问题。--non-interactive以非交互模式运行命令禁用所有交互式提示与 spinner。适合 CI 流水线与 Agent 环境。--nologo隐藏启动横幅与遥测声明。--banner显示动画版 Aspire CLI 欢迎横幅。--wait-for-debugger在执行命令前等待调试器附加用于调试 CLI 或 AppHost 启动流程。从源码看根命令还内置了一批隐藏选项用于内部诊断--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.csApp 命令应用管理命令说明new从 Aspire 入门模板创建新应用。init在现有代码库中初始化 Aspire。add [integration]向 apphost 添加托管集成。update更新 Aspire 项目中的集成。run以开发模式运行 apphost。stop停止正在运行的 apphost 或指定资源。ps列出正在运行的 apphost。资源管理Resource Management命令说明start resource启动已停止的资源。stop [resource]停止正在运行的 apphost 或指定资源。restart resource重启正在运行的资源。wait resource等待资源达到目标状态。command resource command在资源上执行命令。监控Monitoring命令说明describe [resource]描述正在运行的 apphost 中的资源。logs [resource]显示正在运行的 apphost 中资源的日志。otel查看正在运行的 apphost 的 OpenTelemetry 数据日志、Span、Trace。部署Deployment命令说明publish为 apphost 生成部署产物。deploy将 apphost 部署到其部署目标。destroy销毁先前部署的 AppHost 环境。do step执行特定的流水线步骤及其依赖。工具与配置Tools Configuration命令说明config管理 CLI 配置包括功能开关feature flags。cache管理 CLI 操作的磁盘缓存。doctor诊断 Aspire 环境问题并验证安装。docs浏览与搜索 aspire.dev 上的 Aspire 文档和 API 参考。agent管理 AI Agent 相关的环境配置。除上述命令外根命令还按需挂载了terminal终端与setupBundle 安装等命令。其中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语言选择解析--language或交互式提示选择项目语言方案探测仅 C# 且非 file-based通过ISolutionLocator查找现有.sln/.slnx生成骨架C# 走apphost.cs单文件或aspire-apphost模板工程两条路径其他语言Go、Java、Python、TypeScript 等走 polyglot 脚手架路径信任开发证书C# 路径自动执行证书信任避免首次aspire start出现证书错误失败不阻塞可用aspire doctor/aspire certs trust兜底链式 Agent 初始化预选全部 bundle skill含 aspireify但不注册 MCP——MCP 配置只能通过独立的aspire agent init显式开启输出后续命令若用户选择了一次性 init skill会打印如claude run the aspireify skill或opencode --prompt run the aspireify skill的跟进命令。C# 单文件骨架会生成如下apphost.cs内容InitCommand.cs#:sdk Aspire.AppHost.Sdkversion #:property AspireUseCliBundletrue 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组合使用输出DetachOutputInfoAppHostPath、AppHostPid、CliPid、DashboardUrl、LogFile启动超时可通过ASPIRE_CLI_START_TIMEOUT环境变量配置按下 CtrlC 视为正常退出路径返回成功退出码运行期间会先等待构建完成再等待 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 commandaspire 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 otelOpenTelemetry 数据aspire otel查看运行中 apphost 的 OpenTelemetry 数据。从源码目录看其下细分otel logsTelemetryLogsCommand.cs、otel spansTelemetrySpansCommand.cs与otel tracesTelemetryTracesCommand.cs三个子命令分别查看日志、Span 与 Trace。部署命令详解部署命令族覆盖应用从产物生成到环境销毁的完整生命周期aspire publish为 apphost 生成部署产物如容器镜像、清单等aspire deploy将 apphost 部署到其部署目标Azure 等aspire destroy销毁先前部署的 AppHost 环境清理云端资源注意不可逆aspire do step执行流水线中的特定步骤及其依赖基于 PipelineCommandBase.cs 构建用于精细控制部署流水线的执行粒度。工具与配置命令详解aspire configCLI 配置管理 CLI 配置与功能开关典型的用法是读写 feature flags例如开启实验性终端命令aspire config set features.terminalCommandsEnabled trueaspire 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 redisaspire agentAI 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 60wait默认等待 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 --followNDJSON 流式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在用户 CtrlC 时返回成功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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考