[Breaking change]: Deprecating various known parameters in AzureBicepResource

[davidfowl]

Description

Known bicep parameter injection has been removed. The known parameters AzureBicepResource.KnownParameters.KeyVaultName and AzureBicepResource.KnownParameters.LogAnalyticsWorkspaceId are now [Obsolete] and ignored during infrastructure generation.
Developers must explicitly model Key Vault and Log Analytics resources (or use the new helper APIs), because Aspire can no longer decide which instance to inject once multiple compute environments are present.

This also applies to "containerAppEnvironmentId" and "containerAppEnvironmentName".

This behavior change will only apply when using AddAzureContainerAppEnvironment.

Version

Other (please put exact version in description textbox)

Previous behavior

Previous behavior

When you added a Container App Environment via the old infrastructure helper (or relied on azd’s hybrid mode), any AzureBicepResource that declared one of these known parameters was auto-populated at build time:

Bicep parameter name	Known parameter constant	Typical use
keyvaultName	KeyVaultName	Reference a per resource KeyVault to store secrets mapped to AzureBicepResource.GetSecretOutput
logAnalyticsWorkspaceId	LogAnalyticsWorkspaceId	Reference the log analytics workspace id associated with the container app environment
containerAppEnvironmentId	N/A	Reference the container app environment id
containerAppEnvironmentName	N/A	Reference container app environment name

Because Aspire injected the values, the following worked without extra wiring:

// keyvault.bicep
param keyVaultName string
resource kv 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: keyVaultName
  ...
}

// App code
builder.AddBicepTemplateFile("kv", "keyvault.bicep");   // no parameter assignment needed
builder.AddContainer("api", "image");

All four parameters were resolved automatically—the template deployed successfully even though you never set them in code.

New behavior

Aspire no longer pre-populates the parameters listed below. If a Bicep template still declares any of them without an explicit assignment, deployment fails with an “undefined parameter” error.

Deprecated auto-filled parameter	What to do now
keyVaultName (KnownParameters.KeyVaultName)	Add a Key Vault resource and pass its name explicitly (or use AddAzureKeyVault).
logAnalyticsWorkspaceId (KnownParameters.LogAnalyticsWorkspaceId)	Add a Log Analytics Workspace and associate it with App Insights via WithLogAnalyticsWorkspace(workspace)  – or omit the call and let App Insights auto-create one.
containerAppEnvironmentId (KnownParameters.ContainerAppEnvironmentId)	Add an AzureContainerAppEnvironmentResource. Pass its name (env.NameOutputReference) to your template, then use standard Bicep resource-reference syntax to obtain the ID inside the template.
containerAppEnvironmentName (KnownParameters.ContainerAppEnvironmentName)	Use AzureContainerAppEnvironmentResource.NameOutputReference directly.

Example – explicit wiring

// 1. Explicit resources
var env = builder.AddAzureContainerAppEnvironment("env");
var kv  = builder.AddAzureKeyVault("kv");
var la  = builder.AddAzureLogAnalyticsWorkspace("la");

// 2. Pass parameters explicitly
builder.AddBicepTemplateFile("kvTemplate", "keyvault.bicep")
       .WithParameter("keyVaultName", kv.NameOutputReference);

// Pass *name* of the environment, let Bicep resolve ID inside the template
builder.AddBicepTemplateFile("apiTemplate", "api.bicep")
       .WithParameter("containerAppEnvironmentName", env.NameOutputReference);

builder.AddAzureApplicationInsights("ai")
       .WithLogAnalyticsWorkspace(la);

Inside api.bicep, resolve the environment ID in native Bicep:

param containerAppEnvironmentName string

resource env 'Microsoft.App/managedEnvironments@2024-03-01' existing = {
  name: containerAppEnvironmentName
}

var environmentId = env.id

The template no longer expects Aspire to inject containerAppEnvironmentId; instead it derives the ID from the name you supplied.

Addendum — AzureContainerAppEnvironment Bicep outputs

Output name	Meaning	Exposed as property?
AZURE_LOG_ANALYTICS_WORKSPACE_NAME	Log-Analytics workspace name	No
AZURE_LOG_ANALYTICS_WORKSPACE_ID	Log-Analytics workspace resource ID	No
AZURE_CONTAINER_REGISTRY_NAME	ACR name	Yes via IContainerRegistry.Name
AZURE_CONTAINER_REGISTRY_ENDPOINT	ACR login server ( *.azurecr.io )	Yes via IContainerRegistry.Endpoint
AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID	Managed-identity ID that can push/pull from ACR	Yes via IAzureContainerRegistry.ContainerRegistryManagedIdentityId
AZURE_CONTAINER_APPS_ENVIRONMENT_NAME	Container-app environment name	Yes via NameOutputReference
AZURE_CONTAINER_APPS_ENVIRONMENT_ID	Container-app environment resource ID	No
AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN	Default DNS domain for apps	No

Only the bold “Yes” items are surfaced as first-class properties; the rest may evolve.

Migration helper

var env = builder.AddAzureContainerAppEnvironment("env");

// Outputs not promoted to strongly-typed properties can still be referenced:
var laWorkspaceId           = env.GetOutput("AZURE_LOG_ANALYTICS_WORKSPACE_ID");
var containerAppEnvironmentId = env.GetOutput("AZURE_CONTAINER_APPS_ENVIRONMENT_ID");

// Pass them as parameters where needed
builder.AddBicepTemplateFile("myTemplate", "file.bicep")
       .WithParameter("logAnalyticsWorkspaceId", laWorkspaceId)
       .WithParameter("containerAppEnvironmentId", containerAppEnvironmentId);

Use GetOutput(string) sparingly—these names could change in future versions; prefer the strongly-typed properties when available.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

With Aspire’s new ability to model multiple compute environments in a single application graph, a single “global” Key Vault or Log Analytics workspace is no longer unambiguous.
Implicitly pushing those values into every Bicep module hid dependencies, complicated debugging, and blocked future scenarios where resources must target specific environments. Removing the automatic injection and marking the old known-parameter constants as obsolete forces explicit, predictable wiring and keeps the resource graph self-describing.

Recommended action

Recommended action

1. Stop using the obsolete constants
   Remove any code that sets or relies on
   AzureBicepResource.KnownParameters.KeyVaultName,
   AzureBicepResource.KnownParameters.LogAnalyticsWorkspaceId, or AzureBicepResource that depend on containerAppEnvironmentId, and containerAppEnvironmentName.

2. Model resources explicitly

   var env = builder.AddAzureContainerAppEnvironment("env");
   
   var kv = builder.AddAzureKeyVault("kv");                 // explicit Key Vault
   var la = builder.AddAzureLogAnalyticsWorkspace("la");    // explicit workspace
   
   var ai = builder.AddAzureApplicationInsights("ai")
                   .WithLogAnalyticsWorkspace(la);          // explicit link

3. Reference environment outputs when needed
   Use the strongly-typed properties first (env.NameOutputReference).
   For transitional scenarios you can still fetch raw outputs:

   var laWorkspaceId = env.GetOutput("AZURE_LOG_ANALYTICS_WORKSPACE_ID");
   var containerAppEnvId = env.GetOutput("AZURE_CONTAINER_APPS_ENVIRONMENT_ID");
   
   builder.AddBicepTemplateFile("custom.bicep")
          .WithParameter("logAnalyticsWorkspaceId", laWorkspaceId)
          .WithParameter("containerAppEnvironmentId", containerAppEnvId);

4. Address compile warnings
   [Obsolete] warnings now appear where the old constants or helper methods are used.
   Replace them with the explicit approaches shown above.

5. Update applications
   If your applications assumed Aspire would inject these parameters, ensure they now pass the required values (or update the templates to rely on explicit resources instead).

Affected APIs

Namespace / Type	Member	Change
Aspire.Hosting.Azure	AzureBicepResource.KnownParameters.KeyVaultName	[Obsolete] – no longer injected
	AzureBicepResource.KnownParameters.LogAnalyticsWorkspaceId	[Obsolete] – no longer injected