Aspire 构建期诊断码全解ASPIRE001–ASPIRE011 的触发条件、源码定位与处置方案【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspireAspire 通过 MSBuild targets 和 Roslyn 分析器两类机制在构建 AppHost 项目时产出一组以ASPIRE为前缀的诊断码ASPIRE001–ASPIRE011用于在编码/构建早期暴露 SDK 引用缺失、项目资源配置错误、CLI 调用链路不可用等问题。本文基于仓库中的 诊断清单文档 与 AppHost targets、AppHost SDK targets、分析器实现 逐一给出每个诊断码的触发条件、源码出处和修复/抑制方式读完后可独立定位并解决绝大多数 Aspire 构建期报错。诊断体系总览Aspire 的诊断来自两个互不重叠的层面MSBuild 诊断由Aspire.Hosting.AppHost包附带的 targets 文件 与Aspire.AppHost.Sdk的 SDK targets 中的Warning/Error任务产生覆盖ASPIRE001–ASPIRE005、ASPIRE007–ASPIRE011。它们在构建或dotnet run前的目标执行阶段生效。Roslyn 分析器诊断由 Aspire.Hosting.Analyzers 项目在编译期产生目前只有一个错误级诊断ASPIRE006校验应用模型项如AddProject传入的名称是否为合法标识符。两类诊断都带有指向aka.ms/aspire/diagnostics/aspireXXX的帮助链接见源码中各Warning HelpLink...属性可结合本文的源码定位深入排查。MSBuild 诊断码完整列表下表完整继承自 docs/list-of-diagnostics.md原文档中指向src/Aspire.Hosting.Sdk/的链接在当前仓库中对应的实际实现位于Aspire.AppHost.Sdk项目下表 Location 列已修正为真实存在的路径诊断码严重级别说明源码位置ASPIRE001Warning[ProjectLanguage]语言未被 Aspire 完整支持——部分代码生成目标不会运行需要手工编写AppHost.in.targetsASPIRE002Warning[ProjectName]是 Aspire AppHost 项目但必要依赖缺失是否缺少Aspire.Hosting.AppHost的 PackageReferenceSdk.in.targetsASPIRE003Warning[ProjectName]需要 Visual Studio 17.10 或更高版本当前为$(MSBuildVersion)Sdk.in.targetsASPIRE004Warning[ProjectName]被 Aspire Host 项目引用但它不是可执行程序。是否想设置IsAspireProjectResourcefalseAppHost.in.targetsASPIRE005Error已废弃该诊断不再使用—ASPIRE007Error[ProjectName]需要引用版本不低于9.0.0的Aspire.AppHost.Sdk请在Project声明后添加Sdk NameAspire.AppHost.Sdk Version9.0.0 /AppHost.in.targetsASPIRE008Error[ProjectName]必须启用GenerateAssemblyInfoAppHost 依赖程序集元数据特性来定位所需依赖请移除GenerateAssemblyInfofalse/GenerateAssemblyInfo或将其设为 trueAppHost.in.targetsASPIRE009Error[ProjectName]配置为使用 Aspire CLI bundle但 bundle 无法解析AppHost.in.targetsASPIRE010Warning[ProjectName]配置了AspireUseCliBundlefalse。部分 Aspire 功能需要 CLI bundle可设置AspireUseCliBundletrue启用或抑制ASPIRE010继续无 bundle 构建AppHost.in.targetsASPIRE011Error[ProjectName]配置为通过 DNX 调用 Aspire CLI但在 PATH 上找不到dnx命令AppHost.in.targets语言与项目资源校验ASPIRE001 / ASPIRE004ASPIRE001由_WarnOnUnsupportedLanguage目标产生触发条件是$(Language)不为C#见 AppHost.in.targets L152-L154。从源码结构看项目元数据的生成目标_CSharpWriteProjectMetadataSources、_CSharpWriteHostProjectMetadataSources均以$(Language) C#为前置条件因此非 C# 的 AppHost 会缺少Projects命名空间下的*.ProjectMetadata.g.cs生成文件需要手工编写。ASPIRE004由_ValidateAspireHostProjectResources目标产生AppHost.in.targets L166-L188。其流程是将带IsAspireProjectResourcetrue元数据的ProjectReference收集为_AspireProjectResource通过嵌套 MSBuild 调用获取各引用项目的目标框架再用GetNonExecutableReferencesMSBuild Task 判断其中哪些不是可执行程序只要存在非可执行引用即报ASPIRE004提示对纯库引用设置IsAspireProjectResourcefalse。注意该目标的条件中带有SkipValidateAspireHostProjectResources ! true的开关在确属有意引用库项目如文件式应用中无法为单个ProjectReference设置元数据时可将该属性设为true跳过校验。背景上SDK targets 会在TreatProjectReferencesAsResourcestrue默认时把所有ProjectReference默认升级为 Aspire 资源并关闭程序集输出引用这正是AppHost 里引用一个库会触发 ASPIRE004的根源。环境前置条件ASPIRE002 / ASPIRE003 / ASPIRE007 / ASPIRE008这四个诊断都挂在PrepareForBuild之前执行ASPIRE002__WarnOnAspireCapabilityMissingSdk.in.targets L45-L47检查项目是否具备Aspire项目能力。该能力由 AppHost.in.targets L26-L29 在IsAspireHosttrue时注册。如果项目声明了Aspire.AppHost.Sdk却没有隐式引入Aspire.Hosting.AppHost包该包由 AddImplicitAspireAppHostPackage 目标 自动添加可通过SkipAddAspireDefaultReferencestrue关闭能力缺失即触发此警告。ASPIRE003__WarnOnMininumVsVersionMissingSdk.in.targets L49-L51仅在BuildingInsideVisualStudiotrue且$(MSBuildVersion)小于17.10.0时触发命令行构建不受影响。ASPIRE007__ErrorOnMininumSdkVersionMissingAppHost.in.targets L721-L727IsAspireHosttrue但AspireHostingSDKVersion为空或低于9.0.0时以Error终止构建提示在 csproj 中显式声明带版本的 SDK 引用。ASPIRE008__ErrorOnGenerateAssemblyInfoDisabledAppHost.in.targets L729-L735GenerateAssemblyInfofalse时报错。原因是 AppHost 依赖程序集元数据属性来定位 DCP 与 DashboardSetOrchestrationDiscoveryAttributes、SetDashboardDiscoveryAttributes等目标会向程序集注入dcpclipath、aspiredashboardpath、apphostprojectpath等AssemblyMetadataAppHost.in.targets L626-L695关闭程序集信息生成就切断了这条发现链路。ASPIRE005已在当前版本中废弃源码里不再有任何产生该码的路径保留编号只为兼容历史。CLI bundle 相关ASPIRE009 / ASPIRE010 / ASPIRE011这三个诊断围绕同一个开关AspireUseCliBundle在 Sdk.in.targets L25 中默认为false及其配套的 CLI 调用模式属性AspireUseCliBundletrue启用 CLI 委托构建时把运行职责交给 Aspire CLI而非直接启动 AppHost由 CLI 提供 DCP 与 Dashboard 的运行时布局。AspireCliInvocationModePath默认值见 AppHost.in.targets L199-L203使用 PATH 上的aspire命令当 PATH 上的 CLI 不可用或不满足要求时回退到与 AppHost SDK 配套的Aspire.Cli版本并通过 DNX 调用。AspireCliInvocationModeDnx通过 DNX 调用不带版本号的Aspire.Cli包从而尊重当前作用域内的工具清单tool manifest无清单适用时使用最新包。AspireCliInvocationModeDnxPinned调用与Aspire.AppHost.Sdk精确配套版本的Aspire.Cli即固定为aspire.cli$(AspireHostingSDKVersion)见 AppHost.in.targets L204-L211 中_AspireCliDnxPackageReference的两种取值。在此背景上逐条看诊断ASPIRE010_WarnOnAspireCliBundleDisabledAppHost.in.targets L156-L160IsAspireHosttrue且AspireUseCliBundlefalse时在PrepareForBuild前发出警告属于当前默认配置下的提示。抑制方式二选一设置AspireUseCliBundletrue或按提示抑制ASPIRE010。ASPIRE009ResolveAspireCliBundlePaths目标末尾的ErrorAppHost.in.targets L433-L435启用 bundle 后targets 会先解析 CLI 调用_ResolveAspireCliInvocation再调用ResolveAspireCliBundle任务求值DcpDir、AspireDashboardDir、AspireTerminalHostPath等布局若 bundle 缺失还会自动执行aspire setupPATH CLI 或 DNX 回退两种链路尝试就地准备 bundle。最终仍解析不到 DCP 或 Dashboard 布局时报错错误文本会附上可复现的诊断命令引导检查AspireCliBundlePath/AspireCliPath配置。ASPIRE011_ValidateAspireCliDnxInvocationModeAppHost.in.targets L617-L623调用模式为Dnx/DnxPinned且未显式指定AspireCliPath时若 PATH 上找不到dnx命令则报错提示升级 .NET SDK 10.0、改回AspireCliInvocationModePath或显式设置AspireCliPath。补充一个从源码可确认的相关约束当AspireUseCliBundletrue时_AspireCheckCliVersion目标AppHost.in.targets L446-L566会以--version探测实际选中的 CLI 可执行文件要求版本不低于_AspireMinimumCliVersion当前为13.5.0才允许 CLI 代跑PATH 上的 CLI 不达标时会尝试经 DNX 回退到配套包。该版本门槛不产生独立的 ASPIRE 码但会以裸 Error 文本终止构建排查dotnet run失败时需一并考虑。分析器诊断ASPIRE006 应用模型名称校验ASPIRE006是唯一由 Roslyn 分析器发出的诊断定义在 AppHostAnalyzer.Diagnostics.cs严重级别Error分类Design默认启用语义应用模型项application model items必须具有合法名称消息为{0}占位符填入具体校验信息。检测逻辑在 AppHostAnalyzer.DetectInvalidModelNames.cs分析器收集模型名称相关的操作ModelNameOperation对每个候选名称调用ModelName.TryValidateName(modelType, modelName, out validationMessage)做白名单式校验失败即在命中的 token 位置报告ASPIRE006。典型触发场景是在builder.AddProject(...)、AddContainer(...)等 API 中传入包含空格、连字符或以数字开头这类非法 C# 标识符的资源名——Aspire 会为资源名生成类型/属性非法名称会在编译期直接失败帮助链接指向aka.ms/aspire/diagnostics/ASPIRE006。验证与测试入口构建期诊断的行为在仓库测试中有对应断言可作为预期触发条件的可执行参照tests/Aspire.Hosting.Sdk.Tests/AppHostSdkTargetsTests.cs针对Aspire.AppHost.SdktargetsASPIRE002/ASPIRE003 所在的 SDK 层的构建行为测试tests/Aspire.Hosting.Tests/MSBuildTests.cs针对Aspire.Hosting.AppHosttargets 中各诊断码触发条件的 MSBuild 测试。快速排障清单现象首查项警告ASPIRE001AppHost 是否非 C# 语言需要手工编写生成类代码警告ASPIRE002是否缺少Aspire.Hosting.AppHost包引用正常应被 SDK 隐式添加检查SkipAddAspireDefaultReferences是否被误设警告ASPIRE003升级 Visual Studio 到 17.10仅 IDE 内构建触发警告ASPIRE004对库类ProjectReference设置IsAspireProjectResourcefalse或用SkipValidateAspireHostProjectResourcestrue跳过校验错误ASPIRE007在 csproj 中声明Sdk NameAspire.AppHost.Sdk Version9.0.0 /错误ASPIRE008移除GenerateAssemblyInfofalse错误ASPIRE009按报错附带的诊断命令运行aspire setup核对AspireCliPath/AspireCliBundlePath确保 CLI 可安装错误文本会给出自动 setup 失败原因与退出码警告ASPIRE010需要 CLI 功能时设AspireUseCliBundletrue否则抑制该警告错误ASPIRE011安装 .NET SDK 10.0提供dnx或改用AspireCliInvocationModePath/ 显式AspireCliPath编译期ASPIRE006检查资源名是否合法 C# 标识符无空格/连字符、不以数字开头等所有 MSBuild 诊断都带有HelpLinkaka.ms/aspire/diagnostics/aspireXXX系列配合上表与 源码位置 可精确定位到对应的 Target 与判定条件。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考