Introduce a bicep reference builder (#52742)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: ArcturusZhang

sdk/provisioning/Azure.Provisioning/CHANGELOG.md

@@ -1,21 +1,23 @@
 # Release History
 
-## 1.4.0-beta.2 (Unreleased)
+## 1.4.0-beta.2 (2025-11-10)
 
 ### Features Added
 
+- Added extension method `BicepValueExtensions.ToBicepExpression` which converts any `IBicepValue` into `BicepExpression` to build up complex expressions in bicep. For more details, please refer to the documents in `README`.
 - Added `BicepFunction.GetResourceId` corresponding to bicep built-in function `resourceId`.
 - Added `BicepFunction.GetExtensionResourceId` corresponding to bicep built-in function `extensionResourceId`.
 
-### Breaking Changes
-
 ### Bugs Fixed
 
 - Enabled the ability to assign expressions into a property with type of a `ProvisionableConstruct` via low level APIs.
 - Fixed exception when output variable has a type of array or object.
+- Fixed bug when indexing output list or dictionary, a `KeyNotFoundException` was always thrown. ([#48491](https://github.com/Azure/azure-sdk-for-net/issues/48491))
 
 ### Other Changes
 
+- Now collection types (`BicepList<T>` and `BicepDictionary<T>`) would be able to force to be empty. ([#53346](https://github.com/Azure/azure-sdk-for-net/issues/53346))
+
 ## 1.4.0-beta.1 (2025-09-03)
 
 ### Features Added

sdk/provisioning/Azure.Provisioning/README.md

@@ -20,7 +20,62 @@ dotnet add package Azure.Provisioning
 
 ## Key concepts
 
-This library allows you to specify your infrastructure in a declarative style using dotnet.  You can then use `azd` to deploy your infrastructure to Azure directly without needing to write or maintain `bicep` or arm templates.
+This library allows you to specify your infrastructure in a declarative style using `dotnet`.  You can then use `azd` to deploy your infrastructure to Azure directly without needing to write or maintain `bicep` or `arm` templates.
+
+### Important Usage Guidelines
+
+**Declarative Design Pattern**: `Azure.Provisioning` is designed for declarative infrastructure definition. Each resource and construct instance should represent a single infrastructure component. Avoid reusing the same instance across multiple properties or locations, as this can lead to unexpected behavior in the generated Bicep templates.
+
+```C# Snippet:CreateSeparateInstances
+// ✅ Create separate instances
+StorageAccount storage1 = new(nameof(storage1))
+{
+    Sku = new StorageSku { Name = StorageSkuName.StandardLrs }
+};
+StorageAccount storage2 = new(nameof(storage2))
+{
+    Sku = new StorageSku { Name = StorageSkuName.StandardLrs }
+};
+```
+
+<details>
+<summary>❌ What NOT to do - Click to expand bad example</summary>
+
+```C# Snippet:ReuseInstances
+// ❌ DO NOT reuse the same instance
+StorageSku sharedSku = new() { Name = StorageSkuName.StandardLrs };
+StorageAccount storage1 = new(nameof(storage1)) { Sku = sharedSku }; // ❌ Bad
+StorageAccount storage2 = new(nameof(storage2)) { Sku = sharedSku }; // ❌ Bad
+```
+
+This pattern can lead to incorrect Bicep expressions when you build expressions on them. Details could be found in [this section](#tobicepexpression-method).
+
+</details>
+
+**Safe Collection Access**: You can safely access any index in a `BicepList` or any key in a `BicepDictionary` without exceptions. This is **especially important when working with output properties** from Azure resources, where the actual data doesn't exist at design time but you need to create references for the generated Bicep template.
+
+```C# Snippet:SafeCollectionAccess
+// ✅ Accessing output properties safely - very common scenario
+Infrastructure infra = new();
+CognitiveServicesAccount aiServices = new("aiServices");
+infra.Add(aiServices);
+
+// Safe to access dictionary keys that exist in the deployed resource
+// but not at design time - no KeyNotFoundException thrown
+BicepValue<string> apiEndpoint = aiServices.Properties.Endpoints["Azure AI Model Inference API"];
+
+// Works perfectly for building references in outputs
+infra.Add(new ProvisioningOutput("connectionString", typeof(string))
+{
+    Value = BicepFunction.Interpolate($"Endpoint={apiEndpoint.ToBicepExpression()}")
+});
+// Generates: output connectionString string = 'Endpoint=${aiServices.properties.endpoints['Azure AI Model Inference API']}'
+
+// ⚠️ Note: Accessing .Value will still throw at runtime if the data doesn't exist
+// BicepValue<string> actualValue = apiEndpoint.Value; // Would throw KeyNotFoundException at runtime
+```
+
+This feature resolves common scenarios where you need to reference nested properties or collection items as outputs.
 
 ### `BicepValue` types
 
@@ -33,8 +88,7 @@ This library allows you to specify your infrastructure in a declarative style us
 - A Bicep expression that evaluates to type `T`
 - An unset value (usually one should get this state from the property of a constructed resource/construct)
 
-```csharp
-// Literal value
+```C# Snippet:ThreeKindsOfBicepValue
 BicepValue<string> literalName = "my-storage-account";
 
 // Expression value
@@ -49,23 +103,27 @@ BicepValue<string> unsetName = storageAccount.Name;
 - A Bicep expression that evaluates to an array
 - An unset list (usually one should get this state from the property of a constructed resource/construct)
 
-```csharp
+```C# Snippet:BicepListUsages
 // Literal list
 BicepList<string> tagNames = new() { "Environment", "Project", "Owner" };
 
-// Expression list (referencing a parameter)
-BicepList<string> dynamicTags = parameterReference;
+// Modifying items
+tagNames.Add("CostCenter"); // add an item
+tagNames.Remove("Owner"); // remove an item
+tagNames[0] = "Env"; // modify an item
+tagNames.Clear(); // clear all items
 
-// Adding items
-tagNames.Add("CostCenter");
+// Expression list (referencing a parameter)
+ProvisioningParameter parameter = new(nameof(parameter), typeof(string[]));
+BicepList<string> dynamicTags = parameter;
 ```
 
 **`BicepDictionary<T>`** - Represents a key-value collection where values are `BicepValue<T>`:
 - A dictionary of literal key-value pairs
 - A Bicep expression that evaluates to an object
 - An unset dictionary (usually one should get this state from the property of a constructed resource/construct)
 
-```csharp
+```C# Snippet:BicepDictionaryUsages
 // Literal dictionary
 BicepDictionary<string> tags = new()
 {
@@ -74,31 +132,35 @@ BicepDictionary<string> tags = new()
     ["Owner"] = "DevTeam"
 };
 
-// Expression dictionary
-BicepDictionary<string> dynamicTags = parameterReference;
-
 // Accessing values
 tags["CostCenter"] = "12345";
+
+// Expression dictionary
+ProvisioningParameter parameter = new(nameof(parameter), typeof(object));
+BicepDictionary<string> dynamicTags = parameter;
 ```
 
 #### Working with Azure Resources
 
-**`ProvisionableResource`** - Base class for Azure resources that provides resource-specific functionality. Users typically work with specific resource types like `StorageAccount`, `VirtualMachine`, `AppService`, etc. An instance of type `ProvisionableResource` corresponds to a resource statement in `bicep` language.
+**`ProvisionableResource`** - Base class for Azure resources that provides resource-specific functionality. Users typically work with specific resource types like `StorageAccount`, `VirtualNetwork`, `WebSite`, etc. An instance of type `ProvisionableResource` corresponds to a resource statement in `bicep` language.
 
-**`ProvisionableConstruct`** - Base class for infrastructure components that group related properties and resources. Most users will work with concrete implementations like `StorageAccountSku`, `VirtualNetworkIPConfiguration`, etc. An instance of type `ProvisionableConstruct` usually corresponds to an object definition statement in `bicep` language.
+**`ProvisionableConstruct`** - Base class for infrastructure components that group related properties and resources. Most users will work with concrete implementations like `StorageAccountSku`, `VirtualNetworkEncryption`, etc. An instance of type `ProvisionableConstruct` usually corresponds to an object definition statement in `bicep` language.
 
 Here's how you use the provided Azure resource classes:
 
-```csharp
+```C# Snippet:WorkingWithAzureResources
+// Define parameters for dynamic configuration
+ProvisioningParameter location = new(nameof(location), typeof(string));
+ProvisioningParameter environment = new(nameof(environment), typeof(string));
 // Create a storage account with BicepValue properties
-StorageAccount storage = new("myStorage", StorageAccount.ResourceVersions.V2023_01_01)
+StorageAccount myStorage = new(nameof(myStorage), StorageAccount.ResourceVersions.V2023_01_01)
 {
     // Set literal values
     Name = "mystorageaccount",
     Kind = StorageKind.StorageV2,
 
     // Use BicepValue for dynamic configuration
-    Location = locationParameter, // Reference a parameter
+    Location = location, // Reference a parameter
 
     // Configure nested properties
     Sku = new StorageSku
@@ -110,25 +172,136 @@ StorageAccount storage = new("myStorage", StorageAccount.ResourceVersions.V2023_
     Tags = new BicepDictionary<string>
     {
         ["Environment"] = "Production",
-        ["Project"] = environmentParameter // Mix literal and dynamic values
+        ["Project"] = environment // Mix literal and dynamic values
     }
 };
 
-// Access output properties (these are BicepValue<T> that reference the deployed resource)
-BicepValue<string> storageAccountId = storage.Id;
-BicepValue<Uri> primaryBlobEndpoint = storage.PrimaryEndpoints.BlobUri;
+// Access output properties and use them in output (these are BicepValue<T> that reference the deployed resource)
+ProvisioningOutput storageAccountId = new(nameof(storageAccountId), typeof(string))
+{
+    Value = myStorage.Id
+};
+ProvisioningOutput primaryBlobEndpoint = new(nameof(primaryBlobEndpoint), typeof(string))
+{
+    Value = myStorage.PrimaryEndpoints.BlobUri
+};
+```
+
+### `ToBicepExpression` Method
+
+The `ToBicepExpression()` extension method allows you to create references to resource properties and values for use in Bicep expressions. This is essential when you need to reference one resource's properties in another resource or build dynamic configuration strings.
+
+```C# Snippet:CommonUseCases
+// Create a storage account
+StorageAccount storage = new(nameof(storage), StorageAccount.ResourceVersions.V2023_01_01)
+{
+    Name = "mystorageaccount",
+    Kind = StorageKind.StorageV2
+};
+
+// Reference the storage account name in a connection string
+BicepValue<string> connectionString = BicepFunction.Interpolate(
+    $"AccountName={storage.Name.ToBicepExpression()};EndpointSuffix=core.windows.net"
+);
+// this would produce: 'AccountName=${storage.name};EndpointSuffix=core.windows.net'
+// If we do not call ToBicepExpression()
+BicepValue<string> nonExpressionConnectionString =
+    BicepFunction.Interpolate(
+        $"AccountName={storage.Name};EndpointSuffix=core.windows.net"
+    );
+// this would produce: 'AccountName=mystorageaccount;EndpointSuffix=core.windows.net'
+```
+
+Use `ToBicepExpression()` whenever you need to reference a resource property or value in Bicep expressions, function calls, or when building dynamic configuration values.
+
+#### Important Notes
+
+**NamedProvisionableConstruct Requirement**:
+
+`ToBicepExpression()` requires that the value can be traced back through a chain of properties to a root `NamedProvisionableConstruct`. The method recursively traverses up the property ownership chain until it finds a `NamedProvisionableConstruct` at the root.
+
+**Types that qualify as root `NamedProvisionableConstruct`:**
+- **Azure resources** (like `StorageAccount`, `CognitiveServicesAccount`, etc.) - these inherit from `ProvisionableResource`
+- **Infrastructure components** like:
+  - `ProvisioningParameter` - input parameters to your template
+  - `ProvisioningOutput` - output values from your template  
+  - `ProvisioningVariable` - variables within your template
+  - `ModuleImport` - imported modules
+
+**How the traversal works:**
+- ✅ `storage.Name` - direct property of `StorageAccount` (a `NamedProvisionableConstruct`)
+- ✅ `storage.Sku.Name` - `Sku` is a property of `StorageAccount`, `Name` is a property of `Sku`
+- ✅ `storage.Properties.Encryption.Services.Blob.Enabled` - any depth is supported as long as it traces back to `StorageAccount`
+- ✅ `storage.Tags[0]` - collection element where the collection (`Tags`) is a property of `StorageAccount`
+- ✅ `storage.NetworkRuleSet.VirtualNetworkRules[0].Action` - element of a list property, then accessing a property of that element
+- ❌ `new StorageSku().Name` - standalone `StorageSku` has no traceable path to a `NamedProvisionableConstruct`
+
+This restriction exists because the generated Bicep expression needs an identifier to make it syntax correct (e.g., `storage.sku.name` or `param.someProperty.value`).
+
+```C# Snippet:NamedProvisionableConstructRequirement
+// ✅ Works - calling from a property of StorageAccount which inherits from ProvisionableResource
+StorageAccount storage = new("myStorage");
+BicepExpression nameRef = storage.Name.ToBicepExpression(); // Works
+
+// ✅ Works - calling from a ProvisioningParameter
+ProvisioningParameter param = new("myParam", typeof(string));
+BicepExpression paramRef = param.ToBicepExpression(); // Works
+
+// ❌ Throws exception - StorageSku is just a ProvisionableConstruct (not a NamedProvisionableConstruct)
+StorageSku sku = new() { Name = StorageSkuName.StandardLrs };
+// BicepExpression badRef = sku.Name.ToBicepExpression(); // Throws exception
+// ✅ Works - if you assign it to another NamedProvisionableConstruct first
+storage.Sku = sku;
+BicepExpression goodRef = storage.Sku.Name.ToBicepExpression(); // Works
+```
+
+**Why Instance Sharing Fails**:
+
+As mentioned in the [Declarative Design Pattern](#important-usage-guidelines) section, sharing the same construct instance across multiple properties leads to problems with `ToBicepExpression()`. Here's the correct approach and what happens when you don't follow it:
 
-// Reference properties in other resources
-var appService = new AppService("myApp")
+**The correct approach:**
+
+```C# Snippet:InstanceSharingCorrect
+// ✅ GOOD: Create separate instances with the same values
+StorageAccount storage1 = new("storage1")
 {
-    // Reference the storage account's connection string
-    ConnectionStrings = new BicepDictionary<string>
-    {
-        ["Storage"] = BicepFunction.Interpolate($"DefaultEndpointsProtocol=https;AccountName={storage.Name};AccountKey={storage.GetKeys().Value[0].Value}")
-    }
+    Sku = new StorageSku { Name = StorageSkuName.StandardLrs }
+};
+StorageAccount storage2 = new("storage2")
+{
+    Sku = new StorageSku { Name = StorageSkuName.StandardLrs }
 };
+
+// Each has its own StorageSku instance
+// Bicep expressions work correctly and unambiguously:
+BicepExpression sku1Ref = storage1.Sku.Name.ToBicepExpression(); // "${storage1.sku.name}"
+BicepExpression sku2Ref = storage2.Sku.Name.ToBicepExpression(); // "${storage2.sku.name}"
 ```
 
+**What NOT to do and why it fails:**
+
+```C# Snippet:InstanceSharingProblem
+// ❌ BAD: Sharing the same StorageSku instance
+StorageSku sharedSku = new() { Name = StorageSkuName.StandardLrs };
+
+StorageAccount storage1 = new("storage1") { Sku = sharedSku };
+StorageAccount storage2 = new("storage2") { Sku = sharedSku };
+
+// Now both storage accounts reference the SAME StorageSku object
+// This creates ambiguity when building Bicep expressions:
+
+// ❌ PROBLEM: Which storage account should this reference?
+// storage1.sku.name or storage2.sku.name?
+BicepExpression skuNameRef = sharedSku.Name.ToBicepExpression(); // Confusing and unpredictable!
+
+// The system can't determine whether this should generate:
+// - "${storage1.sku.name}"
+// - "${storage2.sku.name}"
+// This leads to incorrect or unpredictable Bicep output.
+```
+
+**Key takeaway:** Each construct instance must have a single, unambiguous path back to its owning `NamedProvisionableConstruct`. Sharing instances breaks this requirement and makes Bicep reference generation impossible.
+
 ## Examples
 
 ### Create Basic Infrastructure

sdk/provisioning/Azure.Provisioning/api/Azure.Provisioning.net8.0.cs

@@ -5,7 +5,6 @@ public partial class BicepDictionary<T> : Azure.Provisioning.BicepValue, System.
         public BicepDictionary() { }
         public BicepDictionary(System.Collections.Generic.IDictionary<string, Azure.Provisioning.BicepValue<T>>? values) { }
         public int Count { get { throw null; } }
-        public override bool IsEmpty { get { throw null; } }
         public bool IsReadOnly { get { throw null; } }
         public Azure.Provisioning.BicepValue<T> this[string key] { get { throw null; } set { } }
         public System.Collections.Generic.ICollection<string> Keys { get { throw null; } }
@@ -41,7 +40,6 @@ public partial class BicepList<T> : Azure.Provisioning.BicepValue, System.Collec
         public BicepList() { }
         public BicepList(System.Collections.Generic.IList<Azure.Provisioning.BicepValue<T>>? values) { }
         public int Count { get { throw null; } }
-        public override bool IsEmpty { get { throw null; } }
         public bool IsReadOnly { get { throw null; } }
         public Azure.Provisioning.BicepValue<T> this[int index] { get { throw null; } set { } }
         public void Add(Azure.Provisioning.BicepValue<T> item) { }
@@ -81,6 +79,7 @@ void Azure.Provisioning.IBicepValue.SetReadOnly() { }
     }
     public static partial class BicepValueExtensions
     {
+        public static Azure.Provisioning.Expressions.BicepExpression ToBicepExpression(this Azure.Provisioning.IBicepValue bicepValue) { throw null; }
         public static T Unwrap<T>(this Azure.Provisioning.BicepValue<T> value) where T : Azure.Provisioning.Primitives.ProvisionableConstruct, new() { throw null; }
     }
     public enum BicepValueKind

sdk/provisioning/Azure.Provisioning/api/Azure.Provisioning.netstandard2.0.cs

@@ -5,7 +5,6 @@ public partial class BicepDictionary<T> : Azure.Provisioning.BicepValue, System.
         public BicepDictionary() { }
         public BicepDictionary(System.Collections.Generic.IDictionary<string, Azure.Provisioning.BicepValue<T>>? values) { }
         public int Count { get { throw null; } }
-        public override bool IsEmpty { get { throw null; } }
         public bool IsReadOnly { get { throw null; } }
         public Azure.Provisioning.BicepValue<T> this[string key] { get { throw null; } set { } }
         public System.Collections.Generic.ICollection<string> Keys { get { throw null; } }
@@ -41,7 +40,6 @@ public partial class BicepList<T> : Azure.Provisioning.BicepValue, System.Collec
         public BicepList() { }
         public BicepList(System.Collections.Generic.IList<Azure.Provisioning.BicepValue<T>>? values) { }
         public int Count { get { throw null; } }
-        public override bool IsEmpty { get { throw null; } }
         public bool IsReadOnly { get { throw null; } }
         public Azure.Provisioning.BicepValue<T> this[int index] { get { throw null; } set { } }
         public void Add(Azure.Provisioning.BicepValue<T> item) { }
@@ -81,6 +79,7 @@ void Azure.Provisioning.IBicepValue.SetReadOnly() { }
     }
     public static partial class BicepValueExtensions
     {
+        public static Azure.Provisioning.Expressions.BicepExpression ToBicepExpression(this Azure.Provisioning.IBicepValue bicepValue) { throw null; }
         public static T Unwrap<T>(this Azure.Provisioning.BicepValue<T> value) where T : Azure.Provisioning.Primitives.ProvisionableConstruct, new() { throw null; }
     }
     public enum BicepValueKind