Improve Azure provisioning diagnostics

[davidfowl]

Description

Azure provisioning failures can leave users with generic ARM wrapper errors and little guidance about which resource failed or how to recover. This change normalizes Azure provisioning failures, enriches deployment operation details, and surfaces actionable diagnostics in resource state, command results, and aspire deploy output.

The dashboard stays Azure-agnostic: resource providers can now advertise highlighted properties through generic resource property metadata, and Azure uses that path to highlight provisioning failure details. The Azure-specific parsing and recovery guidance remains in Aspire.Hosting.Azure.

Handled errors and diagnostics

Error or condition	What Aspire extracts	Run mode recovery guidance	Publish/deploy recovery guidance
LocationNotAvailableForResourceType	Provider, resource type/name, target resource ID, current location, supported locations when ARM exposes them, request IDs	Use the resource change-location command with a supported region	Set Azure:Location or Azure__Location to a supported region, then rerun deployment; use --clear-cache when cached deployment context must be refreshed
ResourceGroupBeingDeleted	Resource group deletion failure details and Azure request context	Use change-context with a different resource group, or wait for deletion to finish	Set Azure:ResourceGroup or Azure__ResourceGroup to a different resource group, or wait for deletion to finish
SubscriptionNotFound	Subscription/tenant mismatch and request context	Use change-context with an accessible subscription	Set Azure:SubscriptionId or Azure__SubscriptionId to a subscription in the selected tenant, and verify account access
Missing cached resource ID	Aspire deployment state exists but lacks the Azure resource ID needed for recovery	Reprovision the resource, or change Azure context if the resource group is wrong	Rerun deployment with --clear-cache to rebuild deployment state, or set a different resource group
Missing live resource	Cached state points at an Azure resource that no longer exists	Reprovision the resource, forget state if deletion was intentional, or change Azure context	Rerun deployment with --clear-cache to recreate missing resources, or set the correct resource group
ServiceModelDeprecated	Azure OpenAI model/version deprecation details	Update the configured model/version, then reprovision	Update the deployment model/version configuration, then rerun deployment
InvalidResourceProperties	Provider validation details for unsupported SKU, model, scale, or resource properties	Update the resource configuration for the selected provider/SKU/region	Update the AppHost/resource configuration for the selected provider/SKU/region, then rerun deployment
ARM wrapper errors such as DeploymentFailed and ResourceDeploymentFailure	The actionable nested provider error from details[], including deployment-operation statusMessage.error.details[]	Resource state shows the promoted provider error and highlighted failure properties	aspire deploy prints the promoted provider error instead of only the generic wrapper
Failed deployment LROs	Recursive deployment operation summaries and failed provider operations	Run mode continues polling operations and updates dashboard/resource state while deployment is running	Deploy mode does a one-shot operation lookup after LRO failure, avoiding steady-state polling on successful deployments

User-facing usage

In run mode, Azure resource details and commands can show highlighted properties such as provider, resource type, target resource ID, current location, supported locations, error code, request IDs, and recommended actions without the dashboard hardcoding Azure property names.

In deploy mode, recovery guidance uses deployment configuration instead of dashboard resource commands. Example captured from a full aspire deploy validation against the Azure Search playground in an unsupported region:

Recommended action: Set the Azure:Location configuration value, or Azure__Location
environment variable, to australiaeast or another supported region, then rerun the deployment.

For the Bicep sample policy workaround, the sample-only setting remains opt-in:

{
  "Azure": {
    "Sql": {
      "ClearDefaultRoleAssignments": "true"
    }
  }
}

Validation

Validation	Result
AzureBicepProvisionerTests	Passed, 37/37
Focused deploy diagnostics tests	Passed
Full aspire deploy against playground/AzureSearchEndToEnd with unsupported australiacentral location	Failed as expected with enriched LocationNotAvailableForResourceType details and deploy-safe Azure:Location / Azure__Location recommendation
Full aspire deploy against playground samples	Confirmed deploy-mode provisioning paths were exercised; unrelated local/container or sample prerequisite failures were captured separately

Screenshots / Recordings

This PR includes UI changes. Please add screenshots or screen recordings so reviewers can evaluate the visual changes without running locally.

• For before/after comparisons, place them side-by-side or label them clearly.
• For interactive changes (animations, transitions, new flows), prefer a short screen recording (GIF or video).
• If you cannot capture visuals now, note what scenario to test and mark this section as TODO.

Fixes #18109

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 18132

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 18132"

[Copilot]

Pull request overview

This PR adds structured Azure provisioning diagnostics to the Aspire hosting pipeline and dashboard. When Azure deployments fail, resources now surface actionable details including the failing Azure provider, resource type/name, target resource ID, error codes, HTTP status, supported locations, and recommended recovery actions. The dashboard receives these diagnostics through a generic "highlighted properties" mechanism that allows resource providers to advertise important properties without hardcoding Azure-specific names in the dashboard.

Changes:

• Introduces AzureProvisioningFailureDetails and AzureDeploymentOperationDetails records that parse, normalize, and render ARM error responses and deployment operation summaries into structured diagnostics for commands, resource snapshots, and human-readable messages.
• Adds DisplayName and IsHighlighted properties to ResourcePropertySnapshot and the gRPC proto, flowing through the snapshot pipeline so the dashboard can show provider-advertised properties by default without requiring the "show all" toggle.
• Updates the Bicep playground sample with opt-in SQL policy workaround (clearing default role assignments for restricted subscriptions) and Redis access-key auth via Key Vault, plus the SQL client Azure auth provider package reference.

Show a summary per file

File	Description
src/Aspire.Hosting.Azure/AzureProvisioningFailureDetails.cs	New file: canonical failure details record with ARM error parsing, nested error promotion, recommended actions, and rendering to JSON/properties/messages
src/Aspire.Hosting.Azure/AzureDeploymentOperationDetails.cs	New file: deployment operation tracking records and summary type for ARM operation polling
src/Aspire.Hosting.Azure/Provisioning/Provisioners/BicepProvisioner.cs	Deployment operation progress tracking loop, failure enrichment with supported locations, deployment-start error handling
src/Aspire.Hosting.Azure/AzureProvisioningController.cs	Structured failure command results, Disabled inputs for dynamic loading, failure properties on resource snapshots, orphan warning on state reset
src/Aspire.Hosting.Azure/AzureBicepResource.cs	Refactored ExtractDetailedErrorMessage to delegate to AzureProvisioningFailureDetails
src/Aspire.Hosting.Azure/Provisioning/Internal/DefaultArmClientProvider.cs	New GetSupportedLocationsAsync and GetDeploymentOperationsAsync implementations with recursive nested-deployment walking
src/Aspire.Hosting.Azure/Provisioning/Internal/IProvisioningServices.cs	New GetSupportedLocationsAsync and GetDeploymentOperationsAsync interface methods with default implementations
src/Aspire.Hosting/ApplicationModel/CustomResourceSnapshot.cs	Added DisplayName and IsHighlighted properties to ResourcePropertySnapshot
src/Aspire.Hosting/Dashboard/ResourceSnapshot.cs	Updated property tuple to include DisplayName and IsHighlighted
src/Aspire.Hosting/Dashboard/GenericResourceSnapshot.cs	Updated property mapping to pass DisplayName and IsHighlighted
src/Shared/CustomResourceSnapshotExtensions.cs	Updated SetResourceProperty/SetResourcePropertyRange to compare and propagate new properties
src/Aspire.Hosting/Dashboard/proto/dashboard_service.proto	Added is_highlighted field to ResourceProperty message
src/Aspire.Hosting/Dashboard/proto/Partials.cs	Updated proto mapping to include DisplayName and IsHighlighted
src/Aspire.Dashboard/ServiceClient/Partials.cs	Dashboard property mapping with DisplayName and IsHighlighted
src/Aspire.Dashboard/Model/ResourceViewModel.cs	Added DisplayName and IsHighlighted to view models; display name resolution prefers provider-set name
src/Aspire.Dashboard/Components/Controls/ResourceDetails.razor.cs	Highlighted properties shown by default alongside known properties
src/Aspire.Hosting.Azure/Resources/AzureProvisioningStrings.resx	New localized display names for failure properties
src/Aspire.Hosting.Azure/Resources/AzureProvisioningStrings.Designer.cs	Auto-generated resource accessors
src/Aspire.Hosting.Azure/Resources/xlf/*.xlf	XLF translations (13 language files)
playground/bicep/BicepSample.AppHost/AppHost.cs	SQL policy workaround, Redis access-key auth
playground/bicep/BicepSample.ApiService/BicepSample.ApiService.csproj	Added Microsoft.Data.SqlClient.Extensions.Azure reference
Directory.Packages.props	Added Microsoft.Data.SqlClient.Extensions.Azure version 1.0.0
tests/Aspire.Hosting.Azure.Tests/AzureEnvironmentResourceExtensionsTests.cs	New assertions for Disabled inputs, failure details, recommended actions
tests/Aspire.Hosting.Azure.Tests/AzureBicepProvisionerTests.cs	Tests for deployment operation tracking, failure enrichment, stale property clearing
tests/Aspire.Hosting.Azure.Tests/ProvisioningTestHelpers.cs	Test helper updates for new ARM client methods
tests/Aspire.Hosting.Tests/Dashboard/DashboardServiceDataTerminalTests.cs	Updated tuple signature
tests/Aspire.Dashboard.Tests/Model/ResourceViewModelTests.cs	Tests for DisplayName and IsHighlighted mapping
tests/Aspire.Dashboard.Components.Tests/Controls/ResourceDetailsTests.cs	Test for highlighted unknown properties in default view

Copilot's findings

Files not reviewed (1)

• src/Aspire.Hosting.Azure/Resources/AzureProvisioningStrings.Designer.cs: Generated file

• Files reviewed: 39/40 changed files
• Comments generated: 0

[Copilot]

Copilot's findings

Files not reviewed (1)

• src/Aspire.Hosting.Azure/Resources/AzureProvisioningStrings.Designer.cs: Generated file

• Files reviewed: 39/40 changed files
• Comments generated: 1

[Copilot]

Copilot's findings

Files not reviewed (1)

• src/Aspire.Hosting.Azure/Resources/AzureProvisioningStrings.Designer.cs: Generated file

• Files reviewed: 37/38 changed files
• Comments generated: 2

[Copilot]

Copilot's findings

Files not reviewed (1)

• src/Aspire.Hosting.Azure/Resources/AzureProvisioningStrings.Designer.cs: Generated file

• Files reviewed: 38/39 changed files
• Comments generated: 0 new

[davidfowl]

//deployment-test

[davidfowl]

/deployment-test

[JamesNK]

Minor performance observations: 3 comments around allocation avoidance on the 2-second polling path. No correctness or security issues found — the diagnostics pipeline logic is sound.

[Copilot]

Copilot's findings

Files not reviewed (1)

• src/Aspire.Hosting.Azure/Resources/AzureProvisioningStrings.Designer.cs: Generated file

• Files reviewed: 44/45 changed files
• Comments generated: 0 new

[github-actions]

❓ CLI E2E Tests unknown — 115 passed, 0 failed, 2 unknown (commit f24dca1)

View all recordings

-	Test	Detail
✅	AddPackageInteractiveWhileAppHostRunningDetached	Recording · Job · CLI logs
✅	AddPackageWhileAppHostRunningDetached	Recording · Job · CLI logs
✅	AgentCommands_AllHelpOutputs_AreCorrect	Recording · Job · CLI logs
✅	AgentInitCommand_DefaultSelection_InstallsDefaultSkills	Recording · Job · CLI logs
✅	AgentInitCommand_MigratesDeprecatedConfig	Recording · Job · CLI logs
✅	AgentInit_NonInteractive_BundleOnlySkillsNotInCatalog	Recording · Job · CLI logs
✅	AgentMcpListResources_ExcludesResourceMarkedWithExcludeFromMcp	Recording · Job · CLI logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp	Recording · Job · CLI logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp_DevLocalhost	Recording · Job · CLI logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp_Isolated	Recording · Job · CLI logs
✅	AllPublishMethodsBuildDockerImages	Recording · Job · CLI logs
✅	AspireAddAndStartWorkAgainstLegacyAppHostTs	Recording · Job · CLI logs
✅	AspireAddPackageVersionToDirectoryPackagesProps	Recording · Job · CLI logs
✅	AspireInitSingleFileAppHostRunsViaDotnetRunAppHost	Recording · Job · CLI logs
✅	AspireInit_ExistingAppHostDir_RecreatesNuGetConfigKeepsFiles	Recording · Job · CLI logs
❔	AspireInit_SolutionFile_BuildsAgainstChannelHive	Recording · Job · CLI logs
✅	AspireStartUpdatesStaleTypeScriptAppHostPath	Recording · Job · CLI logs
✅	AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	Recording · Job · CLI logs
✅	AspireUpdateRemovesOrphanAppHostPackageVersionWhenSdkAlreadyCurrent	Recording · Job · CLI logs
✅	Banner_DisplayedOnFirstRun	Recording · Job · CLI logs
✅	Banner_DisplayedWithExplicitFlag	Recording · Job · CLI logs
✅	Banner_NotDisplayedWithNoLogoFlag	Recording · Job · CLI logs
✅	CertificatesClean_RemovesCertificates	Recording · Job · CLI logs
✅	CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate	Recording · Job · CLI logs
✅	CertificatesTrust_WithUntrustedCert_TrustsCertificate	Recording · Job · CLI logs
✅	ConfigSetGet_CreatesNestedJsonFormat	Recording · Job · CLI logs
✅	CreateAndRunAspireStarterProject	Recording · Job · CLI logs
✅	CreateAndRunAspireStarterProjectWithBundle	Recording · Job · CLI logs
✅	CreateAndRunEmptyAppHostProject	Recording · Job · CLI logs
✅	CreateAndRunJavaEmptyAppHostProject	Recording · Job · CLI logs
✅	CreateAndRunJsReactProject	Recording · Job · CLI logs
✅	CreateAndRunPolyglotAppHostWithDevLocalhostUrls	Recording · Job · CLI logs
✅	CreateAndRunPythonReactProject	Recording · Job · CLI logs
✅	CreateAndRunTypeScriptEmptyAppHostProject	Recording · Job · CLI logs
✅	CreateAndRunTypeScriptStarterProject	Recording · Job · CLI logs
✅	CreateJavaAppHostWithViteApp	Recording · Job · CLI logs
✅	CreateTypeScriptAppHostWithViteApp_UsesConfiguredToolchain	Recording · Job · CLI logs
✅	DashboardRunWithAgentMcpListTracesReturnsNoTraces	Recording · Job · CLI logs
✅	DashboardRunWithAgentMcpListTracesReturnsNoTraces_DevLocalhost	Recording · Job · CLI logs
✅	DashboardRunWithOtelTracesReturnsNoTraces	Recording · Job · CLI logs
✅	DashboardRunWithOtelTracesReturnsNoTraces_DevLocalhost	Recording · Job · CLI logs
✅	DeployK8sBasicApiService	Recording · Job · CLI logs
✅	DeployK8sWithExternalHelmChart	Recording · Job · CLI logs
✅	DeployK8sWithGarnet	Recording · Job · CLI logs
✅	DeployK8sWithMongoDB	Recording · Job · CLI logs
✅	DeployK8sWithMySql	Recording · Job · CLI logs
✅	DeployK8sWithPostgres	Recording · Job · CLI logs
✅	DeployK8sWithRabbitMQ	Recording · Job · CLI logs
✅	DeployK8sWithRedis	Recording · Job · CLI logs
✅	DeployK8sWithSqlServer	Recording · Job · CLI logs
✅	DeployK8sWithValkey	Recording · Job · CLI logs
✅	DeployTypeScriptAppToKubernetes	Recording · Job · CLI logs
✅	DescribeCommandResolvesReplicaNames	Recording · Job · CLI logs
✅	DescribeCommandShowsRunningResources	Recording · Job · CLI logs
✅	DetachFormatJsonProducesValidJson	Recording · Job · CLI logs
✅	DetachFormatJsonProducesValidJsonWhenRestartingExistingInstance	Recording · Job · CLI logs
✅	DoPublishAndDeployListStepsWork	Recording · Job · CLI logs
✅	DocsCommand_RendersInteractiveMarkdownFromLocalSource	Recording · Job · CLI logs
✅	DoctorCommand_DetectsDeprecatedAgentConfig	Recording · Job · CLI logs
✅	DoctorCommand_TypeScriptAppHostReportsMissingConfiguredToolchain	Recording · Job · CLI logs
✅	DoctorCommand_WithSslCertDir_ShowsTrusted	Recording · Job · CLI logs
✅	DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	Recording · Job · CLI logs
✅	DotNetRunFileBasedAppHostUsesAspireCliBundle	Recording · Job · CLI logs
✅	DotNetRunProjectAppHostUsesAspireCliBundle	Recording · Job · CLI logs
✅	GatewayWithoutExternalEndpoint_FailsPublishWithGuidance	Recording · Job · CLI logs
✅	GeneratedAspireDevScript_StartsWatchMode_WithConfiguredToolchain	Recording · Job · CLI logs
✅	GlobalMigration_HandlesCommentsAndTrailingCommas	Recording · Job · CLI logs
✅	GlobalMigration_HandlesMalformedLegacyJson	Recording · Job · CLI logs
✅	GlobalMigration_PreservesAllValueTypes	Recording · Job · CLI logs
✅	GlobalMigration_SkipsWhenNewConfigExists	Recording · Job · CLI logs
✅	GlobalSettings_MigratedFromLegacyFormat	Recording · Job · CLI logs
✅	IngressWithoutExternalEndpoint_FailsPublishWithGuidance	Recording · Job · CLI logs
✅	InitTypeScriptAppHost_AugmentsExistingViteRepoInWorkspaceSubdirectory	Recording · Job · CLI logs
✅	InteractiveCSharpInitCreatesExpectedFiles	Recording · Job · CLI logs
✅	InvalidAppHostPathWithComments_IsHealedOnRun	Recording · Job · CLI logs
✅	JavaScriptHostingApisRunFromTypeScriptAppHost	Recording · Job · CLI logs
✅	LatestCliCanStartStableChannelAppHost	Recording · Job · CLI logs
✅	LatestCliCanStartStableChannelTypeScriptAppHost	Recording · Job · CLI logs
✅	LegacySettingsMigration_AdjustsRelativeAppHostPath	Recording · Job · CLI logs
✅	LogsCommandShowsResourceLogs	Recording · Job · CLI logs
✅	OtelLogsReturnsStructuredLogsFromStarterApp	Recording · Job · CLI logs
✅	OtelLogsReturnsStructuredLogsFromStarterAppIsolated	Recording · Job · CLI logs
✅	ProcessCommandCallbackReceivesCliArguments	Recording · Job · CLI logs
✅	PsCommandListsRunningAppHost	Recording · Job · CLI logs
✅	PsFormatJsonOutputsOnlyJsonToStdout	Recording · Job · CLI logs
✅	PublishJavaScriptPatternsGeneratesExpectedDockerComposeArtifacts	Recording · Job · CLI logs
✅	PublishWithConfigureEnvFileUpdatesEnvOutput	Recording · Job · CLI logs
✅	PublishWithDockerComposeServiceCallbackSucceeds	Recording · Job · CLI logs
✅	PublishWithoutOutputPathUsesAppHostDirectoryDefault	Recording · Job · CLI logs
✅	ResourceCommand_FailedExec_ShowsLogPathAndLogHasEntries	Recording · Job · CLI logs
✅	ResourceCommand_SetAndDeleteParameterUpdatesDescribeOutput	Recording · Job · CLI logs
✅	RestoreGeneratesSdkFiles	Recording · Job · CLI logs
✅	RestoreGeneratesSdkFiles_WithConfiguredToolchain	Recording · Job · CLI logs
✅	RestoreRefreshesGeneratedSdkAfterAddingIntegration	Recording · Job · CLI logs
✅	RestoreSupportsConfigOnlyHelperPackageAndCrossPackageTypes	Recording · Job · CLI logs
✅	RunFromParentDirectory_UsesExistingConfigNearAppHost	Recording · Job · CLI logs
✅	RunReportsSyntaxErrorsForDotNetAppHost	Recording · Job · CLI logs
✅	RunReportsSyntaxErrorsForTypeScriptAppHost	Recording · Job · CLI logs
✅	SecretCrudOnDotNetAppHost	Recording · Job · CLI logs
✅	SecretCrudOnTypeScriptAppHost	Recording · Job · CLI logs
✅	StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	Recording · Job · CLI logs
✅	StartAndWaitForTypeScriptSqlServerAppHostWithNativeAssets	Recording · Job · CLI logs
✅	StartReportsSyntaxErrorsForDotNetAppHost	Recording · Job · CLI logs
✅	StartReportsSyntaxErrorsForTypeScriptAppHost	Recording · Job · CLI logs
✅	StopAllAppHostsFromAppHostDirectory	Recording · Job · CLI logs
✅	StopJavaPolyglotAppHostUsingApphostDirectory	Recording · Job · CLI logs
✅	StopNonInteractiveSingleAppHost	Recording · Job · CLI logs
✅	StopTypeScriptPolyglotAppHostUsingApphostDirectory	Recording · Job · CLI logs
✅	StopWithNoRunningAppHostExitsSuccessfully	Recording · Job · CLI logs
✅	TerminalAttachFrontend_ShowsViteHelpAndDetaches	Recording · Job · CLI logs
✅	TypeScriptAppHostRunDoesNotDeadlockWhenLazyOptionsInvokeAsyncCallback	Recording · Job · CLI logs
✅	TypeScriptAppHostWithVite_AllowsDifferentGuestPkgManager	Recording · Job · CLI logs
✅	UnAwaitedChainsCompileWithAutoResolvePromises	Recording · Job · CLI logs
❔	UpdateToStable_CSharpEmptyAppHost_KeepsConfigChannel	Recording · Job · CLI logs
✅	UpdateToStable_CSharpSingleFileInit_KeepsConfigChannel	Recording · Job · CLI logs
✅	UpdateToStable_TypeScriptSingleFileInit_KeepsConfigChannel	Recording · Job · CLI logs
✅	UpdateToStable_TypeScript_PreviewsStablePkgsAndKeepsChannel	Recording · Job · CLI logs

---

_{📹 Recordings uploaded automatically from CI run #27489269979}