目录概述前置条件Cursor 配置步骤1. 获取Aspire MCP配置2. 配置 MCP 服务器配置内容2. 验证配置方法 1: 通过 AI 助手验证 资源概览 Web 应用 (1个) API 服务 (8个)️ 数据库 (9个) 缓存与消息队列 (2个) 日志与监控 (2个)️ 管理工具 (2个) 参数配置 (4个) 快速访问方法 2: 查看 MCP 工具列表3. 常见配置问题问题 1: 找不到 aspire 命令问题 2: MCP 服务器无法连接快速开始启动 Aspire 应用访问 Aspire DashboardMCP 工具详解1. 资源管理工具1.1 列出所有资源 (list_resources)1.2 执行资源命令 (execute_resource_command)2. 日志查看工具2.1 控制台日志 (list_console_logs)2.2 结构化日志 (list_structured_logs)3. 分布式追踪工具3.1 列出追踪 (list_traces)3.2 查看追踪日志 (list_trace_structured_logs)4. 集成管理工具4.1 列出可用集成 (list_integrations)4.2 获取集成文档 (get_integration_docs)5. AppHost 管理工具5.1 列出 AppHost (list_apphosts)5.2 选择 AppHost (select_apphost)调试工作流工作流 1: 启动时资源无法运行工作流 2: 分析性能问题工作流 3: 调查业务逻辑错误工作流 4: 添加新的集成最佳实践1. 开发流程建议2. 日志查看优先级3. 持久化容器注意事项常见问题Q1: 资源启动失败显示端口冲突Q2: Docker 容器无法启动Q3: 看不到日志输出Q4: 追踪数据不完整更新 AppHost更新到最新版本使用 dotnet-outdated 工具官方资源总结概述Aspire MCPModel Context Protocol工具是一套强大的命令行工具集用于管理、监控和调试 .NET Aspire 应用。这些工具通过 AI 助手如 Cursor集成让开发者可以通过自然语言与 Aspire 应用交互。前置条件• .NET Aspire 应用已配置并可运行• 已安装aspireCLI 工具• Aspire AppHost 项目正确配置• 安装 Cursor AI推荐Cursor 配置步骤1. 获取Aspire MCP配置截止至笔者验证时目前该命令识别Cursor故采取手动配置的方式。如图所示选择其他2. 配置 MCP 服务器Cursor 使用 MCPModel Context Protocol服务器来与 Aspire 应用通信。需要在 Cursor 配置文件中添加 Aspire MCP 服务器配置。通过 Cursor 打开配置1. 打开 Cursor2. 打开 Cursor Settings3. 打开 Tools MCP配置内容在mcp.json中添加mcpServers配置{ mcpServers:{ aspire-mcp:{ name:aspire, type:stdio, command:aspire, args:[ mcp, start ] } } }2. 验证配置配置完成后可以验证 MCP 服务器是否正常工作方法 1: 通过 AI 助手验证在 Cursor 的 AI 聊天窗口中输入请列出当前 Aspire 应用的所有资源如果配置正确AI 助手会自动调用list_resources工具并返回资源列表。以下是参考运行效果我来帮您列出当前 Aspire 应用的所有资源。 [1 tool called] 看起来 Aspire 应用目前没有运行。让我先检查一下终端状态然后启动 Aspire 应用。 [1 tool called] 目前没有运行的 Aspire 应用。让我先启动 Aspire 应用然后再列出所有资源。 [1 tool called] Aspire 应用正在启动中让我等待几秒钟让应用完全启动。 [2 tools called] 现在让我再次尝试列出 Aspire 应用的资源。 [1 tool called] 让我检查一下 Aspire 应用的启动日志看看是否有任何问题。 [1 tool called] 很好Aspire 应用已经成功启动仪表板正在运行。让我再等待几秒钟确保所有资源都已注册然后再次尝试列出资源。 [2 tools called] 让我检查一下所有可用的 AppHost 连接。 [1 tool called] 找到了AppHost 正在运行但不在 MCP 服务器的工作目录范围内。让我选择正确的 AppHost。 [1 tool called] 很好现在让我列出所有资源。 [1 tool called]完美以下是当前 Aspire 应用的所有资源 资源概览 Web 应用 (1个)资源名称状态端点webfrontend✅ Runninghttps://localhost:7120 API 服务 (8个)资源名称状态端点identity✅ Runninghttps://localhost:5071config✅ Runninghttps://localhost:5069exam✅ Runninghttps://localhost:5075survey✅ Runninghttps://localhost:5081approval✅ Runninghttps://localhost:7080messaging✅ Runninghttps://localhost:5073file✅ Runninghttps://localhost:5077pathfinder✅ Runninghttps://localhost:5301️ 数据库 (9个)资源名称类型状态健康状态mysql容器✅ Running✅ HealthysettingsMySQL DB✅ Running✅ Healthyidentity-apiMySQL DB✅ Running✅ Healthyconfig-apiMySQL DB✅ Running✅ Healthyexam-apiMySQL DB✅ Running✅ Healthysurvey-apiMySQL DB✅ Running✅ Healthyapproval-apiMySQL DB✅ Running✅ Healthymessaging-apiMySQL DB✅ Running✅ Healthyfile-apiMySQL DB✅ Running✅ Healthypathfinder-apiMySQL DB✅ Running✅ Healthy 缓存与消息队列 (2个)资源名称类型状态端点cacheRedis 容器✅ Running (✅ Healthy)tcp://localhost:6380rabbitmq容器✅ Running (✅ Healthy)管理界面 日志与监控 (2个)资源名称类型状态端点seq日志容器✅ Running (✅ Healthy)http://localhost:5341greptimedb时序数据库✅ Runninghttp://localhost:4000️ 管理工具 (2个)资源名称用途状态端点phpmyadminMySQL 管理✅ Runninghttp://localhost:61495rediscommanderRedis 管理✅ Runninghttp://localhost:8082 参数配置 (4个)• sqlserver-password• mysql-password• rabbitmq-username• rabbitmq-password 快速访问•仪表板: https://localhost:17109•Web 前端: https://localhost:7120•RabbitMQ 管理: http://localhost:15672•Seq 日志: http://localhost:5341•phpMyAdmin: http://localhost:61495•Redis Commander: http://localhost:8082所有29个资源都在正常运行中✨方法 2: 查看 MCP 工具列表在 Cursor 的 AI 聊天窗口中输入你有哪些 Aspire MCP 工具可用3. 常见配置问题问题 1: 找不到 aspire 命令症状配置后无法使用 MCP 工具提示找不到aspire命令解决方案1. 确认已安装aspireCLI 工具aspire --version2. 如果未安装使用以下命令安装dotnet tool install -g aspire问题 2: MCP 服务器无法连接症状Aspire 应用已运行但 MCP 工具无法获取信息解决方案1. 确保 Aspire 应用正在运行aspire run2. 检查 AppHost 项目路径是否正确3. 重启 Cursor 编辑器4. 在 Cursor AI 中运行list_apphosts确认连接状态快速开始启动 Aspire 应用在使用任何 MCP 工具之前首先需要启动 Aspire 应用aspire run说明• 如果已有实例运行系统会提示停止现有实例• 只有修改了apphost.cs文件才需要重启应用• 遇到问题时重启可以重置到初始状态访问 Aspire Dashboard启动后可以通过以下地址访问 Aspire Dashboardhttps://localhost:17109/Dashboard 提供可视化的资源监控、日志查看和性能分析功能。MCP 工具详解1. 资源管理工具1.1 列出所有资源 (list_resources)用途查看应用中定义的所有资源及其状态使用场景• 检查应用启动后的资源状态• 确认所有服务是否正常运行• 获取服务的 HTTP 端点地址• 查看资源的健康状态返回信息• 资源名称• 资源类型.NET 项目、容器、可执行文件• 运行状态Running、Stopped、Failed• HTTP 端点• 健康状态• 配置的环境变量• 资源关系依赖1.2 执行资源命令 (execute_resource_command)用途对资源执行管理操作参数•resourceName: 资源名称•commandName: 命令名称•resource-start: 启动资源•resource-stop: 停止资源•resource-restart: 重启资源使用场景• 重启出现问题的服务• 停止不需要的资源以节省系统资源• 启动之前停止的服务2. 日志查看工具2.1 控制台日志 (list_console_logs)用途查看资源的标准输出和命令执行日志参数•resourceName: 要查看日志的资源名称使用场景• 查看应用启动日志• 检查资源启动失败的原因• 查看容器的输出信息• 调试资源启动问题日志类型• 标准输出stdout• 标准错误stderr• 资源命令执行记录start、stop、restart示例# 查看 Identity API 的控制台日志 list_console_logs(resourceName: identity) # 查看 SQL Server 容器日志 list_console_logs(resourceName: sqlserver)最佳实践• 资源无法启动时第一时间查看控制台日志• 检查是否有端口冲突、连接失败等错误信息• 容器启动失败时控制台日志通常会显示镜像拉取或配置问题2.2 结构化日志 (list_structured_logs)用途查看应用的结构化日志记录参数•resourceName可选指定资源名称不指定则返回所有资源的日志使用场景• 查看详细的应用运行日志• 分析业务逻辑执行情况• 调试应用程序错误• 性能分析和优化日志级别•Trace: 最详细的跟踪信息•Debug: 调试信息•Information: 常规信息•Warning: 警告信息•Error: 错误信息•Critical: 严重错误示例# 查看所有资源的结构化日志 list_structured_logs() # 查看特定资源的日志 list_structured_logs(resourceName: identity)日志字段• 时间戳• 日志级别• 消息内容• 类别/命名空间• 异常信息如果有• 自定义属性如 UserId、TenantId 等最佳实践• 出现业务逻辑错误时先查看结构化日志• 关注Error和Critical级别的日志• 使用资源名称过滤减少信息量• 结合时间戳分析问题发生的时间线3. 分布式追踪工具3.1 列出追踪 (list_traces)用途查看分布式追踪信息跟踪跨服务的操作参数•resourceName可选限定特定资源的追踪使用场景• 分析跨服务调用链路• 定位性能瓶颈• 排查服务间通信问题• 了解请求的完整执行路径追踪信息包含• Trace ID唯一追踪标识符• 涉及的资源列表• 总执行时长• 是否发生错误示例# 查看所有追踪 list_traces() # 查看 Identity API 的追踪 list_traces(resourceName: identity)输出示例追踪列表 - Trace ID: abc123... 资源: [webfrontend, identity, sqlserver] 时长: 245ms 状态: 成功 - Trace ID: def456... 资源: [exam, file, redis] 时长: 1203ms 状态: 错误3.2 查看追踪日志 (list_trace_structured_logs)用途查看特定追踪的详细日志参数•traceId: 追踪 ID从 list_traces 获取使用场景• 深入分析某个请求的完整执行过程• 查看追踪中每个步骤的详细日志• 定位错误发生的具体位置• 分析性能问题的根因日志包含• Span ID每个操作步骤的标识• 时间戳• 日志级别• 消息内容• 操作名称• 父 Span 关系示例# 查看特定追踪的日志 list_trace_structured_logs(traceId: abc123...)最佳实践• 调查分布式系统问题时先用list_traces找到问题追踪• 然后用list_trace_structured_logs查看详细日志• 这种方式比直接查看资源日志更有针对性• 可以清楚看到请求在不同服务间的流转过程4. 集成管理工具4.1 列出可用集成 (list_integrations)用途查看所有可用的 Aspire 托管集成包使用场景• 需要向 AppHost 添加新的资源数据库、消息队列等• 查找特定服务的集成包• 确认集成包的版本和兼容性返回信息• NuGet 包 ID• 包版本• 描述信息• 支持的服务类型示例输出可用的 Aspire 集成 - Aspire.Hosting.Redis (9.0.0) 描述: Redis 缓存集成 - Aspire.Hosting.RabbitMQ (9.0.0) 描述: RabbitMQ 消息队列集成 - Aspire.Hosting.PostgreSQL (9.0.0) 描述: PostgreSQL 数据库集成 - Aspire.Hosting.MongoDB (9.0.0) 描述: MongoDB 数据库集成最佳实践• 添加资源前先用此工具查找合适的集成• 选择与Aspire.AppHost.Sdk版本对齐的集成版本• 某些集成版本可能有 preview 后缀4.2 获取集成文档 (get_integration_docs)用途获取特定集成的详细使用文档参数•packageId: 包 ID如Aspire.Hosting.Redis•packageVersion: 包版本如9.0.0使用场景• 了解如何在 AppHost 中配置集成• 查看集成的配置选项• 获取最佳实践和示例代码示例# 获取 Redis 集成文档 get_integration_docs( packageId: Aspire.Hosting.Redis, packageVersion: 9.0.0 )最佳实践1. 先用list_integrations找到目标集成和版本2. 再用get_integration_docs获取详细文档3. 按照文档指引配置 AppHost4. 测试集成是否正常工作5. AppHost 管理工具5.1 列出 AppHost (list_apphosts)用途列出所有检测到的 AppHost 连接使用场景• 工作区中有多个 AppHost 项目• 确认当前活动的 AppHost• 查看 AppHost 的工作目录范围返回信息• AppHost 路径• 是否在工作目录范围内• 连接状态示例输出AppHost 列表 - d:\repos\code-spirit\Src\CodeSpirit.AppHost\CodeSpirit.AppHost.csproj 范围: 工作目录内 状态: 活动5.2 选择 AppHost (select_apphost)用途在多个 AppHost 之间切换参数•appHostPath: AppHost 项目路径绝对路径或工作区相对路径使用场景• 工作区有多个微服务项目每个都有自己的 AppHost• 需要切换到不同的 AppHost 进行调试示例# 使用相对路径 select_apphost(appHostPath: Src/CodeSpirit.AppHost) # 使用绝对路径 select_apphost(appHostPath: d:\repos\code-spirit\Src\CodeSpirit.AppHost)调试工作流工作流 1: 启动时资源无法运行步骤1.检查资源状态list_resources确认哪些资源处于 Failed 或 Stopped 状态2.查看控制台日志list_console_logs(resourceName: 问题资源名)查看启动失败的原因常见问题• 端口冲突• Docker 镜像无法拉取• 配置错误• 依赖服务未启动3.查看结构化日志list_structured_logs(resourceName: 问题资源名)查看应用级别的错误信息4.修复问题后重启资源execute_resource_command( resourceName: 问题资源名, commandName: resource-restart )工作流 2: 分析性能问题步骤1.列出追踪记录list_traces()找出执行时间异常的追踪2.查看追踪详细日志list_trace_structured_logs(traceId: 慢追踪的ID)分析每个 Span 的耗时3.定位瓶颈资源• 查看哪个服务或数据库查询耗时最长• 检查是否有 N1 查询问题• 查看是否有网络延迟4.优化代码并验证• 修改代码优化性能• 重新测试并对比追踪时间工作流 3: 调查业务逻辑错误步骤1.查看结构化日志list_structured_logs()筛选 Error 和 Critical 级别的日志2.定位问题资源list_structured_logs(resourceName: 疑似问题的资源)聚焦到特定服务的日志3.结合追踪分析list_traces(resourceName: 问题资源) list_trace_structured_logs(traceId: 错误追踪ID)查看完整的调用链路4.修复并验证• 修改代码修复 Bug• 重新测试并检查日志工作流 4: 添加新的集成步骤1.查找可用集成list_integrations找到需要的集成包和版本2.获取集成文档get_integration_docs( packageId: Aspire.Hosting.XXX, packageVersion: 9.0.0 )3.添加到 AppHost• 安装 NuGet 包• 在apphost.cs中配置集成• 设置必要的环境变量和配置4.重启 AppHostaspire run5.验证集成list_resources确认新资源已正确添加并运行最佳实践1. 开发流程建议进行任何代码修改前1. aspire run # 启动应用 2. list_resources # 检查初始状态 3. 进行代码修改 4. 验证修改通常不需要重启 5. 出现问题时查看日志2. 日志查看优先级遇到问题时的日志查看顺序1.先看控制台日志(list_console_logs)• 适合启动失败、容器问题2.再看结构化日志(list_structured_logs)• 适合应用逻辑错误3.最后看追踪日志(list_trace_structured_logs)• 适合分布式调用问题3. 持久化容器注意事项重要提示开发早期避免使用持久化容器原因• 避免状态管理问题• 简化应用重启流程• 防止数据不一致何时使用持久化• 测试环境需要保留数据• 开发环境需要模拟生产数据• 数据初始化成本较高常见问题Q1: 资源启动失败显示端口冲突解决方案1. 查看控制台日志确认冲突端口2. 修改Src/CodeSpirit.AppHost/Program.cs中的端口配置3. 或者停止占用端口的其他应用Q2: Docker 容器无法启动可能原因• Docker Desktop 未运行• 镜像无法拉取网络问题• 磁盘空间不足解决方案1. 确保 Docker Desktop 正在运行2. 配置镜像加速或使用 VPN3. 清理 Docker 镜像释放空间Q3: 看不到日志输出解决方案1. 确认资源正在运行list_resources2. 检查日志级别配置3. 查看 Aspire Dashboard 的日志面板Q4: 追踪数据不完整可能原因• 分布式追踪未正确配置• 某些服务未启用追踪• 追踪数据未传播解决方案1. 检查所有服务的追踪配置2. 确保 HTTP 头正确传递3. 查看 Aspire 官方文档的追踪配置指南更新 AppHost更新到最新版本aspire update说明• 更新 AppHost 到最新版本• 更新部分 Aspire 相关包• 可能需要手动更新其他包以确保兼容性使用 dotnet-outdated 工具安装dotnet tool install --global dotnet-outdated-tool使用dotnet outdated该工具会列出所有过时的 NuGet 包。官方资源• Aspire 官方网站• Microsoft Learn - .NET Aspire• NuGet 包详情总结Aspire MCP 工具提供了强大的应用管理和调试能力✅资源管理查看状态、执行命令✅日志查看控制台日志、结构化日志✅分布式追踪跨服务调用分析✅集成管理查找和配置新集成✅AppHost 管理多项目切换通过熟练使用这些工具可以大大提高开发效率和问题排查速度。引入地址
目录概述前置条件Cursor 配置步骤1. 获取Aspire MCP配置2. 配置 MCP 服务器配置内容2. 验证配置方法 1: 通过 AI 助手验证 资源概览 Web 应用 (1个) API 服务 (8个)️ 数据库 (9个) 缓存与消息队列 (2个) 日志与监控 (2个)️ 管理工具 (2个) 参数配置 (4个) 快速访问方法 2: 查看 MCP 工具列表3. 常见配置问题问题 1: 找不到 aspire 命令问题 2: MCP 服务器无法连接快速开始启动 Aspire 应用访问 Aspire DashboardMCP 工具详解1. 资源管理工具1.1 列出所有资源 (list_resources)1.2 执行资源命令 (execute_resource_command)2. 日志查看工具2.1 控制台日志 (list_console_logs)2.2 结构化日志 (list_structured_logs)3. 分布式追踪工具3.1 列出追踪 (list_traces)3.2 查看追踪日志 (list_trace_structured_logs)4. 集成管理工具4.1 列出可用集成 (list_integrations)4.2 获取集成文档 (get_integration_docs)5. AppHost 管理工具5.1 列出 AppHost (list_apphosts)5.2 选择 AppHost (select_apphost)调试工作流工作流 1: 启动时资源无法运行工作流 2: 分析性能问题工作流 3: 调查业务逻辑错误工作流 4: 添加新的集成最佳实践1. 开发流程建议2. 日志查看优先级3. 持久化容器注意事项常见问题Q1: 资源启动失败显示端口冲突Q2: Docker 容器无法启动Q3: 看不到日志输出Q4: 追踪数据不完整更新 AppHost更新到最新版本使用 dotnet-outdated 工具官方资源总结概述Aspire MCPModel Context Protocol工具是一套强大的命令行工具集用于管理、监控和调试 .NET Aspire 应用。这些工具通过 AI 助手如 Cursor集成让开发者可以通过自然语言与 Aspire 应用交互。前置条件• .NET Aspire 应用已配置并可运行• 已安装aspireCLI 工具• Aspire AppHost 项目正确配置• 安装 Cursor AI推荐Cursor 配置步骤1. 获取Aspire MCP配置截止至笔者验证时目前该命令识别Cursor故采取手动配置的方式。如图所示选择其他2. 配置 MCP 服务器Cursor 使用 MCPModel Context Protocol服务器来与 Aspire 应用通信。需要在 Cursor 配置文件中添加 Aspire MCP 服务器配置。通过 Cursor 打开配置1. 打开 Cursor2. 打开 Cursor Settings3. 打开 Tools MCP配置内容在mcp.json中添加mcpServers配置{ mcpServers:{ aspire-mcp:{ name:aspire, type:stdio, command:aspire, args:[ mcp, start ] } } }2. 验证配置配置完成后可以验证 MCP 服务器是否正常工作方法 1: 通过 AI 助手验证在 Cursor 的 AI 聊天窗口中输入请列出当前 Aspire 应用的所有资源如果配置正确AI 助手会自动调用list_resources工具并返回资源列表。以下是参考运行效果我来帮您列出当前 Aspire 应用的所有资源。 [1 tool called] 看起来 Aspire 应用目前没有运行。让我先检查一下终端状态然后启动 Aspire 应用。 [1 tool called] 目前没有运行的 Aspire 应用。让我先启动 Aspire 应用然后再列出所有资源。 [1 tool called] Aspire 应用正在启动中让我等待几秒钟让应用完全启动。 [2 tools called] 现在让我再次尝试列出 Aspire 应用的资源。 [1 tool called] 让我检查一下 Aspire 应用的启动日志看看是否有任何问题。 [1 tool called] 很好Aspire 应用已经成功启动仪表板正在运行。让我再等待几秒钟确保所有资源都已注册然后再次尝试列出资源。 [2 tools called] 让我检查一下所有可用的 AppHost 连接。 [1 tool called] 找到了AppHost 正在运行但不在 MCP 服务器的工作目录范围内。让我选择正确的 AppHost。 [1 tool called] 很好现在让我列出所有资源。 [1 tool called]完美以下是当前 Aspire 应用的所有资源 资源概览 Web 应用 (1个)资源名称状态端点webfrontend✅ Runninghttps://localhost:7120 API 服务 (8个)资源名称状态端点identity✅ Runninghttps://localhost:5071config✅ Runninghttps://localhost:5069exam✅ Runninghttps://localhost:5075survey✅ Runninghttps://localhost:5081approval✅ Runninghttps://localhost:7080messaging✅ Runninghttps://localhost:5073file✅ Runninghttps://localhost:5077pathfinder✅ Runninghttps://localhost:5301️ 数据库 (9个)资源名称类型状态健康状态mysql容器✅ Running✅ HealthysettingsMySQL DB✅ Running✅ Healthyidentity-apiMySQL DB✅ Running✅ Healthyconfig-apiMySQL DB✅ Running✅ Healthyexam-apiMySQL DB✅ Running✅ Healthysurvey-apiMySQL DB✅ Running✅ Healthyapproval-apiMySQL DB✅ Running✅ Healthymessaging-apiMySQL DB✅ Running✅ Healthyfile-apiMySQL DB✅ Running✅ Healthypathfinder-apiMySQL DB✅ Running✅ Healthy 缓存与消息队列 (2个)资源名称类型状态端点cacheRedis 容器✅ Running (✅ Healthy)tcp://localhost:6380rabbitmq容器✅ Running (✅ Healthy)管理界面 日志与监控 (2个)资源名称类型状态端点seq日志容器✅ Running (✅ Healthy)http://localhost:5341greptimedb时序数据库✅ Runninghttp://localhost:4000️ 管理工具 (2个)资源名称用途状态端点phpmyadminMySQL 管理✅ Runninghttp://localhost:61495rediscommanderRedis 管理✅ Runninghttp://localhost:8082 参数配置 (4个)• sqlserver-password• mysql-password• rabbitmq-username• rabbitmq-password 快速访问•仪表板: https://localhost:17109•Web 前端: https://localhost:7120•RabbitMQ 管理: http://localhost:15672•Seq 日志: http://localhost:5341•phpMyAdmin: http://localhost:61495•Redis Commander: http://localhost:8082所有29个资源都在正常运行中✨方法 2: 查看 MCP 工具列表在 Cursor 的 AI 聊天窗口中输入你有哪些 Aspire MCP 工具可用3. 常见配置问题问题 1: 找不到 aspire 命令症状配置后无法使用 MCP 工具提示找不到aspire命令解决方案1. 确认已安装aspireCLI 工具aspire --version2. 如果未安装使用以下命令安装dotnet tool install -g aspire问题 2: MCP 服务器无法连接症状Aspire 应用已运行但 MCP 工具无法获取信息解决方案1. 确保 Aspire 应用正在运行aspire run2. 检查 AppHost 项目路径是否正确3. 重启 Cursor 编辑器4. 在 Cursor AI 中运行list_apphosts确认连接状态快速开始启动 Aspire 应用在使用任何 MCP 工具之前首先需要启动 Aspire 应用aspire run说明• 如果已有实例运行系统会提示停止现有实例• 只有修改了apphost.cs文件才需要重启应用• 遇到问题时重启可以重置到初始状态访问 Aspire Dashboard启动后可以通过以下地址访问 Aspire Dashboardhttps://localhost:17109/Dashboard 提供可视化的资源监控、日志查看和性能分析功能。MCP 工具详解1. 资源管理工具1.1 列出所有资源 (list_resources)用途查看应用中定义的所有资源及其状态使用场景• 检查应用启动后的资源状态• 确认所有服务是否正常运行• 获取服务的 HTTP 端点地址• 查看资源的健康状态返回信息• 资源名称• 资源类型.NET 项目、容器、可执行文件• 运行状态Running、Stopped、Failed• HTTP 端点• 健康状态• 配置的环境变量• 资源关系依赖1.2 执行资源命令 (execute_resource_command)用途对资源执行管理操作参数•resourceName: 资源名称•commandName: 命令名称•resource-start: 启动资源•resource-stop: 停止资源•resource-restart: 重启资源使用场景• 重启出现问题的服务• 停止不需要的资源以节省系统资源• 启动之前停止的服务2. 日志查看工具2.1 控制台日志 (list_console_logs)用途查看资源的标准输出和命令执行日志参数•resourceName: 要查看日志的资源名称使用场景• 查看应用启动日志• 检查资源启动失败的原因• 查看容器的输出信息• 调试资源启动问题日志类型• 标准输出stdout• 标准错误stderr• 资源命令执行记录start、stop、restart示例# 查看 Identity API 的控制台日志 list_console_logs(resourceName: identity) # 查看 SQL Server 容器日志 list_console_logs(resourceName: sqlserver)最佳实践• 资源无法启动时第一时间查看控制台日志• 检查是否有端口冲突、连接失败等错误信息• 容器启动失败时控制台日志通常会显示镜像拉取或配置问题2.2 结构化日志 (list_structured_logs)用途查看应用的结构化日志记录参数•resourceName可选指定资源名称不指定则返回所有资源的日志使用场景• 查看详细的应用运行日志• 分析业务逻辑执行情况• 调试应用程序错误• 性能分析和优化日志级别•Trace: 最详细的跟踪信息•Debug: 调试信息•Information: 常规信息•Warning: 警告信息•Error: 错误信息•Critical: 严重错误示例# 查看所有资源的结构化日志 list_structured_logs() # 查看特定资源的日志 list_structured_logs(resourceName: identity)日志字段• 时间戳• 日志级别• 消息内容• 类别/命名空间• 异常信息如果有• 自定义属性如 UserId、TenantId 等最佳实践• 出现业务逻辑错误时先查看结构化日志• 关注Error和Critical级别的日志• 使用资源名称过滤减少信息量• 结合时间戳分析问题发生的时间线3. 分布式追踪工具3.1 列出追踪 (list_traces)用途查看分布式追踪信息跟踪跨服务的操作参数•resourceName可选限定特定资源的追踪使用场景• 分析跨服务调用链路• 定位性能瓶颈• 排查服务间通信问题• 了解请求的完整执行路径追踪信息包含• Trace ID唯一追踪标识符• 涉及的资源列表• 总执行时长• 是否发生错误示例# 查看所有追踪 list_traces() # 查看 Identity API 的追踪 list_traces(resourceName: identity)输出示例追踪列表 - Trace ID: abc123... 资源: [webfrontend, identity, sqlserver] 时长: 245ms 状态: 成功 - Trace ID: def456... 资源: [exam, file, redis] 时长: 1203ms 状态: 错误3.2 查看追踪日志 (list_trace_structured_logs)用途查看特定追踪的详细日志参数•traceId: 追踪 ID从 list_traces 获取使用场景• 深入分析某个请求的完整执行过程• 查看追踪中每个步骤的详细日志• 定位错误发生的具体位置• 分析性能问题的根因日志包含• Span ID每个操作步骤的标识• 时间戳• 日志级别• 消息内容• 操作名称• 父 Span 关系示例# 查看特定追踪的日志 list_trace_structured_logs(traceId: abc123...)最佳实践• 调查分布式系统问题时先用list_traces找到问题追踪• 然后用list_trace_structured_logs查看详细日志• 这种方式比直接查看资源日志更有针对性• 可以清楚看到请求在不同服务间的流转过程4. 集成管理工具4.1 列出可用集成 (list_integrations)用途查看所有可用的 Aspire 托管集成包使用场景• 需要向 AppHost 添加新的资源数据库、消息队列等• 查找特定服务的集成包• 确认集成包的版本和兼容性返回信息• NuGet 包 ID• 包版本• 描述信息• 支持的服务类型示例输出可用的 Aspire 集成 - Aspire.Hosting.Redis (9.0.0) 描述: Redis 缓存集成 - Aspire.Hosting.RabbitMQ (9.0.0) 描述: RabbitMQ 消息队列集成 - Aspire.Hosting.PostgreSQL (9.0.0) 描述: PostgreSQL 数据库集成 - Aspire.Hosting.MongoDB (9.0.0) 描述: MongoDB 数据库集成最佳实践• 添加资源前先用此工具查找合适的集成• 选择与Aspire.AppHost.Sdk版本对齐的集成版本• 某些集成版本可能有 preview 后缀4.2 获取集成文档 (get_integration_docs)用途获取特定集成的详细使用文档参数•packageId: 包 ID如Aspire.Hosting.Redis•packageVersion: 包版本如9.0.0使用场景• 了解如何在 AppHost 中配置集成• 查看集成的配置选项• 获取最佳实践和示例代码示例# 获取 Redis 集成文档 get_integration_docs( packageId: Aspire.Hosting.Redis, packageVersion: 9.0.0 )最佳实践1. 先用list_integrations找到目标集成和版本2. 再用get_integration_docs获取详细文档3. 按照文档指引配置 AppHost4. 测试集成是否正常工作5. AppHost 管理工具5.1 列出 AppHost (list_apphosts)用途列出所有检测到的 AppHost 连接使用场景• 工作区中有多个 AppHost 项目• 确认当前活动的 AppHost• 查看 AppHost 的工作目录范围返回信息• AppHost 路径• 是否在工作目录范围内• 连接状态示例输出AppHost 列表 - d:\repos\code-spirit\Src\CodeSpirit.AppHost\CodeSpirit.AppHost.csproj 范围: 工作目录内 状态: 活动5.2 选择 AppHost (select_apphost)用途在多个 AppHost 之间切换参数•appHostPath: AppHost 项目路径绝对路径或工作区相对路径使用场景• 工作区有多个微服务项目每个都有自己的 AppHost• 需要切换到不同的 AppHost 进行调试示例# 使用相对路径 select_apphost(appHostPath: Src/CodeSpirit.AppHost) # 使用绝对路径 select_apphost(appHostPath: d:\repos\code-spirit\Src\CodeSpirit.AppHost)调试工作流工作流 1: 启动时资源无法运行步骤1.检查资源状态list_resources确认哪些资源处于 Failed 或 Stopped 状态2.查看控制台日志list_console_logs(resourceName: 问题资源名)查看启动失败的原因常见问题• 端口冲突• Docker 镜像无法拉取• 配置错误• 依赖服务未启动3.查看结构化日志list_structured_logs(resourceName: 问题资源名)查看应用级别的错误信息4.修复问题后重启资源execute_resource_command( resourceName: 问题资源名, commandName: resource-restart )工作流 2: 分析性能问题步骤1.列出追踪记录list_traces()找出执行时间异常的追踪2.查看追踪详细日志list_trace_structured_logs(traceId: 慢追踪的ID)分析每个 Span 的耗时3.定位瓶颈资源• 查看哪个服务或数据库查询耗时最长• 检查是否有 N1 查询问题• 查看是否有网络延迟4.优化代码并验证• 修改代码优化性能• 重新测试并对比追踪时间工作流 3: 调查业务逻辑错误步骤1.查看结构化日志list_structured_logs()筛选 Error 和 Critical 级别的日志2.定位问题资源list_structured_logs(resourceName: 疑似问题的资源)聚焦到特定服务的日志3.结合追踪分析list_traces(resourceName: 问题资源) list_trace_structured_logs(traceId: 错误追踪ID)查看完整的调用链路4.修复并验证• 修改代码修复 Bug• 重新测试并检查日志工作流 4: 添加新的集成步骤1.查找可用集成list_integrations找到需要的集成包和版本2.获取集成文档get_integration_docs( packageId: Aspire.Hosting.XXX, packageVersion: 9.0.0 )3.添加到 AppHost• 安装 NuGet 包• 在apphost.cs中配置集成• 设置必要的环境变量和配置4.重启 AppHostaspire run5.验证集成list_resources确认新资源已正确添加并运行最佳实践1. 开发流程建议进行任何代码修改前1. aspire run # 启动应用 2. list_resources # 检查初始状态 3. 进行代码修改 4. 验证修改通常不需要重启 5. 出现问题时查看日志2. 日志查看优先级遇到问题时的日志查看顺序1.先看控制台日志(list_console_logs)• 适合启动失败、容器问题2.再看结构化日志(list_structured_logs)• 适合应用逻辑错误3.最后看追踪日志(list_trace_structured_logs)• 适合分布式调用问题3. 持久化容器注意事项重要提示开发早期避免使用持久化容器原因• 避免状态管理问题• 简化应用重启流程• 防止数据不一致何时使用持久化• 测试环境需要保留数据• 开发环境需要模拟生产数据• 数据初始化成本较高常见问题Q1: 资源启动失败显示端口冲突解决方案1. 查看控制台日志确认冲突端口2. 修改Src/CodeSpirit.AppHost/Program.cs中的端口配置3. 或者停止占用端口的其他应用Q2: Docker 容器无法启动可能原因• Docker Desktop 未运行• 镜像无法拉取网络问题• 磁盘空间不足解决方案1. 确保 Docker Desktop 正在运行2. 配置镜像加速或使用 VPN3. 清理 Docker 镜像释放空间Q3: 看不到日志输出解决方案1. 确认资源正在运行list_resources2. 检查日志级别配置3. 查看 Aspire Dashboard 的日志面板Q4: 追踪数据不完整可能原因• 分布式追踪未正确配置• 某些服务未启用追踪• 追踪数据未传播解决方案1. 检查所有服务的追踪配置2. 确保 HTTP 头正确传递3. 查看 Aspire 官方文档的追踪配置指南更新 AppHost更新到最新版本aspire update说明• 更新 AppHost 到最新版本• 更新部分 Aspire 相关包• 可能需要手动更新其他包以确保兼容性使用 dotnet-outdated 工具安装dotnet tool install --global dotnet-outdated-tool使用dotnet outdated该工具会列出所有过时的 NuGet 包。官方资源• Aspire 官方网站• Microsoft Learn - .NET Aspire• NuGet 包详情总结Aspire MCP 工具提供了强大的应用管理和调试能力✅资源管理查看状态、执行命令✅日志查看控制台日志、结构化日志✅分布式追踪跨服务调用分析✅集成管理查找和配置新集成✅AppHost 管理多项目切换通过熟练使用这些工具可以大大提高开发效率和问题排查速度。引入地址
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
