Introduce a bicep reference builder #51370

ArcturusZhang · 2025-07-21T09:17:54Z

This PR introduces two extension methods:

public static BicepExpression ToBicepExpression(this IBicepValue value);
public static BicepExpression ToBicepExpression<T>(this BicepValue<T> value);

which converts a bicep value instance into an expression.

Also fixes the issue that when we try to use out-of-range index on a list or a non-exist key on a dictionary, the ArgumentOutOfRangeException of KeyNotFoundException are thrown.
Now the exception are deferred to throw until we are trying to access the value in it, but if we convert it to an expression, no exception would be thrown at all.

Contributing to the Azure SDK

Please see our CONTRIBUTING.md if you are not familiar with contributing to this repository or have questions.

For specific information about pull request etiquette and best practices, see this section.

github-actions · 2025-07-21T09:27:38Z

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Azure.Provisioning

Copilot

Pull Request Overview

This PR introduces a bicep reference builder that enables generating proper Bicep expressions from BicepValue objects, addressing issue #51371. The implementation provides a way to convert BicepValue instances to their corresponding Bicep reference expressions rather than their literal values.

Key changes include:

Added ToBicepExpression extension methods for converting BicepValue objects to Bicep reference expressions
Implemented specialized indexer classes for list and dictionary access patterns
Enhanced list and dictionary indexers to handle out-of-bounds and missing key scenarios properly

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
BicepValueReferenceExtensions.cs	Core extension methods for converting BicepValue to BicepExpression references
BicepListIndexer.cs	Internal class handling list indexer references with proper error handling
BicepDictionaryIndexer.cs	Internal class handling dictionary indexer references with proper error handling
BicepListOfT.cs	Enhanced indexer logic to return proper reference types and validate bounds
BicepDictionaryOfT.cs	Enhanced dictionary indexer to handle missing keys and return reference types
BicepValue.cs	Made Compile method virtual to allow specialized indexer behavior
BicepValueReferenceExtensionsTests.cs	Comprehensive test suite covering all reference generation scenarios

sdk/provisioning/Azure.Provisioning/src/BicepListIndexer.cs

sdk/provisioning/Azure.Provisioning/src/BicepDictionaryIndexer.cs

sdk/provisioning/Azure.Provisioning/tests/Expressions/BicepValueReferenceExtensionsTests.cs

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

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

ArcturusZhang · 2025-07-23T03:55:47Z

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

+        public static Azure.Provisioning.Expressions.BicepExpression ToBicepExpression(this Azure.Provisioning.IBicepValue value) { throw null; }
+        public static Azure.Provisioning.Expressions.BicepExpression ToBicepExpression<T>(this Azure.Provisioning.BicepValue<T> value) { throw null; }


all the properties with "primitive" types would be of a type of BicepValue<T>.
The IBicepValue overload is here to take up the cases for BicepList<T>, BicepDictionary<T>, ProvisionableConstruct and other stuffs that I did not notice.
Should we change this to a set of more explicit overloads that explicitly takes the above variants?

ArcturusZhang · 2025-07-23T05:13:02Z

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

@@ -75,7 +75,7 @@ internal BicepValue() { }
        public virtual bool IsEmpty { get { throw null; } }
        void Azure.Provisioning.IBicepValue.Assign(Azure.Provisioning.IBicepValue source) { }
        void Azure.Provisioning.IBicepValue.SetReadOnly() { }
-        public Azure.Provisioning.Expressions.BicepExpression Compile() { throw null; }
+        public virtual Azure.Provisioning.Expressions.BicepExpression Compile() { throw null; }


In the implementation, you could see I add this virtual to make sure we could be possible to throw the exception when the item gets compiled.
We could add a private proected virtual BicepExpression CompileCore() in order not to change public API.

ArcturusZhang · 2025-07-24T02:48:57Z

I notice that this implementation might have a challenge in the case that we use BicepFunction.Interpolate(BicepInterpolatedStringHandler).

or maybe not - we could say, if you want one of the argument in your interpolated string to be an expression, you need to call the method and use the output expression as the argument.
The above concern is that would it be possible that we could have something to wrap the interpolated result and wrap all its argument into expression automatically

m-nash · 2025-08-04T05:13:51Z

sdk/provisioning/Azure.Provisioning/src/BicepDictionaryOfT.cs

+        }
+        set
+        {
+            if (_kind == BicepValueKind.Expression || _isOutput)


what happened before if someone tried to set such a value?

they will succeed at setting it.
You could refer the implementation of BicepList<T> - it has this check therefore if they tried to

list[0] = ...

on an output property, it would throw.

m-nash · 2025-08-04T05:16:38Z

sdk/provisioning/Azure.Provisioning/src/BicepListOfT.cs

+                // ensure there is a value
+                if (index >= _values.Count)
+                {
+                    return new BicepListIndexer<T>(_self, index);


is it safe to assume that if you pass in an index that is too big you meant to get back something that is only present at runtime? I am not sure this assumption is safe here.

well this is the part that I once said "the exceptions are deferred".

Here are possible scenarios:

the list is not output only, and the user used a "valid" index: everything works just fine.

the list is output, and the user used an index to reference an item:
when the list is output, no one could add items into it, therefore the index must be out of range here - we will always go into this branch.

the list is not output, and the user used a "valid" index: everything works just fine.

the list is not output, and the user used a "invalid" index: now we do not have a value that we could get from the list. Therefore we go into this branch.

In the 2 cases that we go into this branch, if the user wants to get the value, we throw because there is no such a value. If they want an expression, I think the best we could do is to spit out the expression and let ARM to throw the error, we do not have a way to know if this is valid.

m-nash · 2025-08-04T05:17:19Z

sdk/provisioning/Azure.Provisioning/src/Expressions/BicepValueReferenceExtensions.cs

+    /// <returns></returns>
+    public static BicepExpression ToBicepExpression<T>(this BicepValue<T> value)
+    {
+        if (value is BicepListIndexer<T> indexer)


can we use a switch here?

sdk/provisioning/Azure.Provisioning/src/Primitives/BicepValueReference.cs

…n-builder

ArcturusZhang · 2025-08-04T06:42:38Z

sdk/provisioning/Azure.Provisioning/tests/Expressions/BicepValueReferenceExtensionsTests.cs

+                Properties = new TestProperties()
+            };
+            var nestedOutputList = resource.Properties.OutputList;
+            Assert.AreEqual("[]", nestedOutputList.ToString()); // TODO -- should this throw? or just like right now we return an empty list?


@m-nash what do you think about this?

ArcturusZhang · 2025-08-06T01:34:58Z

sdk/provisioning/Azure.Provisioning/src/BicepListOfT.cs

-    public void Add(BicepValue<T> item) => _values.Add(item);
+    public void Insert(int index, BicepValue<T> item)
+    {
+        if (_kind == BicepValueKind.Expression || _isOutput)


let us revert these changes on throwing exceptions

ArcturusZhang · 2025-08-06T01:41:50Z

sdk/provisioning/Azure.Provisioning/src/BicepListOfT.cs

+                    case BicepValueKind.Unset:
+                        return new BicepListIndexer<T>(_self, index);
+                    case BicepValueKind.Expression:
+                        return new BicepListIndexer<T>(_self, index, value.Expression!);
+                    case BicepValueKind.Literal:
+                        return new BicepListIndexer<T>(_self, index, (T)value.LiteralValue!);
+                    default:
+                        throw new InvalidOperationException($"Unknown {value.Kind}!");


change one of these to default

ArcturusZhang · 2025-08-06T02:00:23Z

sdk/provisioning/Azure.Provisioning/src/BicepListOfT.cs

+                    throw new ArgumentOutOfRangeException(nameof(index), "Index must be non-negative.");
+                }
+                // ensure there is a value
+                if (index >= _values.Count)


how would this works on a list of models?

var x = resource.Models[1];
var xName = x.Name;

…n-builder

some initial attempts

574c1aa

github-actions bot added the Provisioning label Jul 21, 2025

implement the feature and introduce tests

3d2d1cb

ArcturusZhang marked this pull request as ready for review July 22, 2025 04:14

Copilot AI review requested due to automatic review settings July 22, 2025 04:14

ArcturusZhang requested review from ArthurMa1978 and m-nash as code owners July 22, 2025 04:14

Copilot AI reviewed Jul 22, 2025

View reviewed changes

ArcturusZhang and others added 6 commits July 22, 2025 12:19

Update sdk/provisioning/Azure.Provisioning/src/BicepListIndexer.cs

edc9dc8

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

Update sdk/provisioning/Azure.Provisioning/tests/Expressions/BicepVal…

8f9f2cd

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

export api

510d919

fix the exception type

eb23ad2

update doc

20f66ce

add some more unit tests

f2f8571

ArcturusZhang commented Jul 23, 2025

View reviewed changes

Merge branch 'main' into bicep-value-expression-builder

0cfcb12

m-nash reviewed Aug 4, 2025

View reviewed changes

ArcturusZhang added 3 commits August 4, 2025 13:52

Merge remote-tracking branch 'origin/main' into bicep-value-expressio…

2248f17

…n-builder

change a complicated if to switch

7afee6e

resolve comments and add some new test cases

595ae81

ArcturusZhang commented Aug 4, 2025

View reviewed changes

refine

0dc53e1

ArcturusZhang mentioned this pull request Aug 5, 2025

Fix the dictionary indexer issue #50265

Closed

ArcturusZhang commented Aug 6, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into bicep-value-expressio…

22687dc

…n-builder

ArcturusZhang added 5 commits August 6, 2025 10:38

add test case for list of models

cd8a46e

hide the virtual on compile

91a2b02

the implementation needs to improve to support this extra case

ca93ed5

a few progress but not much

5eb5548

change the way of implementation

bb122a6

		public static Azure.Provisioning.Expressions.BicepExpression ToBicepExpression(this Azure.Provisioning.IBicepValue value) { throw null; }
		public static Azure.Provisioning.Expressions.BicepExpression ToBicepExpression<T>(this Azure.Provisioning.BicepValue<T> value) { throw null; }

Introduce a bicep reference builder #51370

Are you sure you want to change the base?

Introduce a bicep reference builder #51370

Uh oh!

Conversation

ArcturusZhang commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Contributing to the Azure SDK

Uh oh!

github-actions bot commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Change Check

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ArcturusZhang commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ArcturusZhang Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ArcturusZhang commented Jul 21, 2025 •

edited

Loading

github-actions bot commented Jul 21, 2025 •

edited

Loading

ArcturusZhang commented Jul 24, 2025 •

edited

Loading

ArcturusZhang Aug 4, 2025 •

edited

Loading