bicep improve documentation for extendable parameter files

Description

Documented the new base keyword for extendable param files (PR #17850 merged) with clearer object/array merge examples and updated notes on overrides.

Checklist

[x] I have read and adhere to the contribution guide.

Microsoft Reviewers: Open in CodeFlow

Dec 08 '25 21:12 polatengin

Test this change out locally with the following install scripts (Action run 20316379441)

VSCode

Mac/Linux

bash <(curl -Ls https://aka.ms/bicep/nightly-vsix.sh) --run-id 20316379441

Windows

iex "& { $(irm https://aka.ms/bicep/nightly-vsix.ps1) } -RunId 20316379441"

Azure CLI

Mac/Linux

bash <(curl -Ls https://aka.ms/bicep/nightly-cli.sh) --run-id 20316379441

Windows

iex "& { $(irm https://aka.ms/bicep/nightly-cli.ps1) } -RunId 20316379441"

Dec 08 '25 21:12 github-actions[bot]

Dotnet Test Results

102 files - 51 102 suites - 51 39m 20s ⏱️ - 28m 28s 12 572 tests - 13 12 572 ✅ - 13 0 💤 ±0 0 ❌ ±0 28 889 runs - 14 438 28 889 ✅ - 14 438 0 💤 ±0 0 ❌ ±0

Results for commit 505704c1. ± Comparison against base commit b0d5e2f8.

This pull request removes 1959 and adds 661 tests. Note that renamed tests count towards both.


		nestedProp1: 1
		nestedProp2: 2
		prop1: true
		prop2: false
	1
	2
	\$'")
	prop1: true
	prop2: false
…

Bicep.Cli.UnitTests.Services.ReplEnvironmentTests ‑ ShouldSubmitBuffer_terminates_at_expected_point ("var foo = {
")
Bicep.Cli.UnitTests.Services.ReplEnvironmentTests ‑ ShouldSubmitBuffer_terminates_at_expected_point ("var multilineString = '''
Line 1
Line 2
Line 3
'''")
Bicep.Cli.UnitTests.Services.ReplEnvironmentTests ‑ ShouldSubmitBuffer_terminates_at_expected_point ("var outRoleAssignments object[] = union(map(
  filter(varMockedEntraGroupIds, item => !contains(item.uniqueName, 'DevOps')),
  group => {
    principalId: group.groupId
    definition: group.roleToAssign
    relativeScope: ''
    principalType: 'Group'
  }
),[
  {
    principalId: '22222222-2222-2222-2222-222222222222'
    definition: 'Reader'
    relativeScope: ''
    principalType: 'ServicePrincipal'
  }
])")
Bicep.Cli.UnitTests.Services.ReplEnvironmentTests ‑ ShouldSubmitBuffer_terminates_at_expected_point ("var test = {
  abc: 'def' // boo
}")
Bicep.Cli.UnitTests.Services.ReplEnvironmentTests ‑ ShouldSubmitBuffer_terminates_at_expected_point ("var varMockedEntraGroupIds = [
  {
    uniqueName: 'Reader-Group'
    roleToAssign: 'Reader'
    groupId: '11111111-1111-1111-1111-111111111111'
  }
  {
    uniqueName: 'Contributor-Group'
    roleToAssign: 'Contributor'
    groupId: '22222222-2222-2222-2222-222222222222'
  }
  {
    uniqueName: 'DevOps-Group'
    groupId: '33333333-3333-3333-3333-333333333333'
  }
]")
Bicep.Core.IntegrationTests.AzTypesViaRegistryTests ‑ Bicep_compiler_handles_corrupted_extension_package_gracefully (\u001f�\u0008\u0000\u0000\u0000\u0000\u0000\u0000
��;
�0\u0010\u0004Э}
�@���R\u001a�)s\u0005A\u000c�`9�C\u000c!w\u000fI\u0015ܤq��z�4[\u000c,��C\u0018�U8Vm��\u0011](�\u001b\u00008k?	`���ɽwN(\u001fi\u0001Cׇ�\u0000�&��-��r���ܣ�tM��.��s]��h\u0003�(o\u0005�}�v�dV��?��hba\u0016g
\u000c\u0013\u0018��E69l{����
�$I\u0012Z�\u000b\u0017�+�\u0000\u000c\u0000\u0000,"The path: index.json was not found in artifact contents")
Bicep.Core.IntegrationTests.AzTypesViaRegistryTests ‑ Bicep_compiler_handles_corrupted_extension_package_gracefully (\u001f�\u0008\u0000\u0000\u0000\u0000\u0000\u0000
��=
\u00021\u0010\u0005�=E�\u0003d�$�D\u0005{\u001b��\u0003DwD�]e`A��`#���S��y�\u0014\u000f���e\u001c�\u0012KiZm�3��w\u0003\u0000_\u0014�\u0004�\u000bO��\u0007Cj�/��.6\u0004��:�n7�ץ\u000c�О�\u0019���W2����`�F\u0008c�x��ɛ=�N\u001f�r�� v��\u0017\u0016�\u0013\u0018@ ��M������V�\u000cg�tR.�ZK�M�6\u001e[���[�$IB\u001fs\u0003g��B\u0000\u000c\u0000\u0000,"Value cannot be null. (Parameter 'source')")
Bicep.Core.IntegrationTests.AzTypesViaRegistryTests ‑ Bicep_compiler_handles_corrupted_extension_package_gracefully (\u001f�\u0008\u0000\u0000\u0000\u0000\u0000\u0000
��=
�@\u0010\u0005�=Œ\u0003l�l�G�\u0014���� �J��\u0011\u0012%�\u0010�\ud9c8\udf58�&F����L10���&ifirH�J�ȨPR�\u0000�j�H\u0000�\u0004�k�;�\u0014��zp��$��\u0013��%��qV\u001c�F��s1PC��Y���Q\u0011\u0018F:3�������:��;}���+Ml���\u0011"&0\u0000&�K'����[0_�&��t�خW�X8���=��<�Ewy\u000f�\u0011\u0000\u000c\u0000\u0000,"'7' is an invalid end of a number. Expected a delimiter. Path: $.INVALID_JSON | LineNumber: 0 | BytePositionInLine: 20.")
Bicep.Core.IntegrationTests.AzTypesViaRegistryTests ‑ Bicep_compiler_handles_corrupted_extension_package_gracefully (\u001f�\u0008\u0000\u0000\u0000\u0000\u0000\u0000\u0003�Խ
�@\u000c\u0007��}��\u000fpMλ\+t\u0010\u001c��
��\u0014Z�B��\u0003
���"��T\u0005�ߒ%�@�G\u0006봟�i�׍\u001c!����!"�ַ���\u0015�ا~�ւ��\u0003��Mk@��D�8��>.�,��9V�
E�\u0016e\u001e�e�T\u0014\u0019�\u0014\u0012+&���:\u0003��\u001d��e��\u00062D��bԀt\u001d\u0000�Lv�����,��E2��7��?\u0016�>>c�q\u001c\u0007~�\u0005�\u0011ۢ\u0000\u000c\u0000\u0000,"'7' is an invalid end of a number. Expected a delimiter. Path: $.INVALID_JSON | LineNumber: 0 | BytePositionInLine: 20.")
Bicep.Core.IntegrationTests.AzTypesViaRegistryTests ‑ Bicep_compiler_handles_corrupted_extension_package_gracefully (\u001f�\u0008\u0000\u0000\u0000\u0000\u0000\u0000\u0003��=
�@\u0010\u0005�=Œ\u0003�o��I��6��\u0007X͈\u0011\u0013%�\u0010\u0010�.�\u000866�\u0016ٯy�\u0014\u000f�'�Я8\u0014ܴr\u0001��%

\u0000�1�\u0004��\u001f��yO��\u001f��]h\u0008�iR���u��<��z�SQueŹ��j�e�I
\u000b��ٿ�F\u0003{��F�u�\u000bC�*e��\u000e��\u0000x\u0012?��m����d[s�}�Ś�\u001d7�R\u001c¹�ǿ�EQ\u0014E4�';�Խ\u0000\u000c\u0000\u0000,"Value cannot be null. (Parameter 'source')")
…

Dec 08 '25 21:12 github-actions[bot]