I had provisioned an Azure Key Vault with enabled_for_template_deployment set to true. I was familiar with this setting from working with Bicep and ARM templates, where it allows the vault to be used for secret retrieval during a deployment.

Note The deployment identity still needs the required ARM deployment permission.

The Key Vault deployed successfully. I then used Terraform to create a secret in it and expected the setting to cover that deployment as well. It did not.

That was the point where I had to stop thinking about the setting and look at what was actually making each request.

variable "secret_value" {
	type      = string
	sensitive = true
}

resource "azurerm_key_vault" "example" {
	name                          = "example-key-vault"
	location                      = azurerm_resource_group.example.location
	resource_group_name           = azurerm_resource_group.example.name
	tenant_id                     = data.azurerm_client_config.current.tenant_id
	sku_name                      = "standard"
	enable_rbac_authorization     = true
	enabled_for_template_deployment = true
}

resource "azurerm_key_vault_secret" "example" {
	name         = "example-secret"
	value        = var.secret_value
	key_vault_id = azurerm_key_vault.example.id
}

What I had missed

The Key Vault itself is an Azure Resource Manager resource. Configuring it with azurerm_key_vault is a control plane operation. That part matched what I expected.

Creating a secret is different. azurerm_key_vault_secret uses the Key Vault service API, which is the data plane. The Terraform identity therefore needs an appropriate Azure RBAC role to set secrets, and the machine running Terraform must be able to reach the Key Vault endpoint.

That meant checking two separate things:

• Did the Terraform identity have permission to write secrets?
• Could the Terraform runner reach the vault through its networking configuration?

Having successfully deployed the vault through ARM did not answer either question. The vault request and the secret request were taking different paths.

Where AzAPI fits

Looking at AzAPI helped clarify the difference between the two providers.

AzureRM gives us typed Terraform resources. Many of those resources manage Azure Resource Manager resources through the control plane, but some resources, such as Key Vault secrets, use the service’s data-plane API.

AzAPI works directly with Azure Resource Manager REST APIs. It is useful when AzureRM has not yet exposed a control-plane resource, API version, or property that is available in Azure.

That makes AzAPI useful for an AzureRM capability gap, but it is not a general replacement for AzureRM data-plane resources. It is a different route to the Azure Resource Manager API, not a switch that makes every AzureRM resource use ARM.

There is a useful detail here. Azure also exposes secrets as the ARM resource Microsoft.KeyVault/vaults/secrets, which AzAPI can target. That provides an ARM-based way to create a secret and may avoid the Terraform runner needing direct access to the Key Vault data-plane endpoint. It still requires the appropriate ARM permissions, and the ARM resource is intended for deployment scenarios; for normal secret interaction, Azure recommends the data-plane API.

The thing worth remembering

enabled_for_template_deployment enables secret retrieval during an ARM or Bicep template deployment (The deployment identity still needs the required ARM deployment permission). The setting does not grant the deployment identity permission to create/read secrets.

When a deployment behaves unexpectedly, it is worth asking which identity is making the request and which endpoint it is calling. In this case, the vault was deployed through ARM, but the AzureRM secret resource was created through the Key Vault data plane. AzAPI can use a different ARM-based resource path, but that comes with different permissions and lifecycle considerations.

That distinction is easy to miss, particularly when moving between Bicep, ARM, and Terraform, so I am noting it here for the next time I run into it.

Useful references:

• Azure control plane and data plane
• Use Azure Key Vault in template deployments
• Azure Key Vault RBAC guide
• Key Vault Set Secret REST API
• AzureRM Key Vault secret resource
• Microsoft.KeyVault/vaults/secrets ARM resource
• AzAPI provider overview

When deploying Azure solutions with Infrastructure as Code, we often create role assignments as part of the deployment. For example, a Bicep deployment may give a Function App’s managed identity access to a Key Vault, storage account, or Service Bus namespace.

It is easy to focus on the role being assigned and forget about the identity performing the deployment. The deployment service principal needs permission to create the role assignment itself. Access to the target resource does not automatically provide this permission.

When that permission is missing, the deployment commonly fails with an error similar to:

The client '<deployment-client-id>' with object id '<object-id>' does not have authorization to perform action 'Microsoft.Authorization/roleAssignments/write' over scope '<scope>'.

And then comes the familiar question: what was that role I needed to assign to the deployment identity?

Explanation

The role is Role Based Access Control Administrator.

This is an Azure built-in role that allows an identity to manage role assignments at the scope where the role is assigned. In practical terms, it gives the deployment service principal permission to create and remove the RBAC assignments declared by the IaC templates.

This role is separate from the role being granted by the deployment:

• The deployment service principal needs permission to write the role assignment.
• The managed identity or application receives the role assignment.
• The target resource is where that access is granted.

The Role Based Access Control Administrator role has the built-in role ID f58310d9-a9f6-439a-9e8d-f62e7b41a168. It should not be confused with User Access Administrator, which is another role that can manage access and has a different permission boundary.

Solution

Assign the Role Based Access Control Administrator role to the deployment service principal at the narrowest scope that contains the role assignments. For example, at resource-group scope.

Once this has been assigned, the deployment identity can create the resource role assignments in that resource group, subject to the normal restrictions on which roles it is allowed to assign.

The identity used to assign this permission must already be authorized to create role assignments. This is usually a one-time platform or subscription setup task, rather than something the deployment should attempt to grant to itself.

⚠️ Best Practice of Least Privilege: avoid assigning this role at subscription scope when the deployment only needs to manage assignments within one resource group or resource.

So, when an Azure IaC deployment fails while creating a role assignment, check the deployment service principal first. This is to jog my memory as well as yours, the role you are looking for is Role Based Access Control Administrator.

Hope this helps, and have fun.

WEBSITE_CONTENTSHARE is an app setting used by Azure Functions and Logic Apps Standard (which runs on the Functions runtime) alongside WEBSITE_CONTENTAZUREFILECONNECTIONSTRING to identify the Azure Files share the app uses for its content.

The important thing to call out up front: you don’t always need to set this. When left unmanaged, Azure generates a share name for you automatically and everything just works.

There are, however, scenarios where you must set it to a predefined value. The most common is when you use a secured storage account in a virtual network - in that case, you must set a unique share name for the main app and for the app associated with each deployment slot. For a storage account secured by a virtual network, you must also create the share itself as part of your automated deployment (see Secured deployments).

The reason it’s worth understanding at all is that getting it wrong doesn’t fail loudly.

How the File Share Backs Your Logic App

Rather than storing your workflow definitions and related files directly on the Logic App instance, the runtime uses an Azure Files share (identified by WEBSITE_CONTENTSHARE, within the storage account referenced by WEBSITE_CONTENTAZUREFILECONNECTIONSTRING) and treats it as the source of truth for the app’s content such as your workflow .json definitions, host.json, and inline code .csx.

In other words, the file share isn’t just a supporting piece of infrastructure - it is the app, from a content perspective. Whatever is in that share is what the app runs.

The Incident

I came across a case where two separate Logic App Standard resources had been deployed referencing the same storage account, and whether through copy-pasted deployment parameters or a naming convention that didn’t account for it, had both ended up with the same WEBSITE_CONTENTSHARE value.

The symptoms were bizarre (mainly due to always having had isolation of storage accounts and certainly file shares). Workflows authored in one Logic App started showing up in the other. A deployment or a change made through one app’s designer would be reflected in the second app, and vice versa. Two Logic Apps, with different names, different resource IDs, sitting in different places in the resource group, yet behaving as if they were the same application. Nothing about the apps themselves looked wrong, which made it a genuinely uncomfortable thing to debug. The only thing that was the same was the workflow name.

Root Cause

Once traced back, the explanation was straightforward, both Logic Apps were pointed at the exact same Azure Files share. Since the content share is the app’s set of workflows and artifacts, both Logic App resources were reading from and writing to the identical set of files.

There weren’t two apps with similar configuration that happened to drift into sync, there was only ever one set of workflow content, fronted by two separate compute resources. Both apps were simply reading and writing the same underlying files the whole time.

Recommendation

If you never explicitly manage WEBSITE_CONTENTSHARE, Azure will generate a unique value for you and you won’t hit this. Where you do need to set it, such as with a VNet-secured storage account, or when cloning an app or restoring from a backup, make sure the value is unique per app instance, including for the main app and each deployment slot.

⚠️ Note

After deploying, it’s worth a quick sanity check against the Files service in the storage account to confirm each app has its own distinct share, particularly if your deployment pipeline sets this value explicitly or reuses parameter files across environments.

Conclusion

It’s a strange situation to land in, two apps that are, for all practical purposes, one app hosted twice, but it’s also entirely avoidable. WEBSITE_CONTENTSHARE is one of those settings you can safely ignore most of the time, but if you do find yourself setting it explicitly, uniqueness per app is non-negotiable.

Role assignments are one of those areas in Azure that look simple on the surface, but can become awkward pretty quickly once you start automating them properly.

Anyone who has worked with RBAC through IaC for long enough will usually run into the same set of problems.

There are usually three things in play:

• The role assignment name needs to be deterministic
• The roleDefinitionId is represented by a GUID that is not especially readable nor indicative of which role it is referring
• When something already exists, the resulting deployment error has not always been particularly helpful

Thankfully, there have been some recent improvements here that are worth knowing about. Some help with troubleshooting, some help with authoring, and one in particular helps with conformance across tooling.

In this post I wanted to walk through three of them:

1. Improved ARM error messages when a role assignment already exists
2. A defined standard for role assignment ID generation
3. Bicep support for resolving role definition IDs from the friendly role name

Improved Error Message for Existing Role Assignments

Historically, if you attempted to deploy a role assignment that already existed but with a different name ID, ARM would return the following:

{
	"code": "RoleAssignmentExists",
	"message": "The role assignment already exists."
}

Technically correct, but not overly helpful.

You knew something was already there, but not which role assignment, not what its ID was, and not how quickly you could correlate that back to the target scope. In environments with multiple deployment paths or platform teams supporting shared subscriptions, that usually meant extra investigation.

The updated message is much better:

{
	"code": "RoleAssignmentExists",
	"message": "The role assignment already exists. The ID of the existing role assignment is a3f1c9e2-7b4d-4e8a-bf62-1d0c5a9e34f7."
}

This is a small change, but a useful one. You can now go straight to the existing assignment, confirm the scope and principal, and decide whether the issue is:

• A valid existing assignment that your deployment should align to
• A duplicate assignment attempt from another deployment path
• A stale or unexpected assignment that needs to be cleaned up

From an operational perspective, this should make diagnosis much quicker, especially when you are dealing with shared scopes or multiple deployment paths.

Standardised Role Assignment ID Generation

For me, this is one of the more important changes because it helps establish consistency across teams and tooling.

There is now a defined standard for how role assignment IDs should be generated across Portal, Bicep, AzCLI, PowerShell, and Terraform:

guid(scope, principalId, roleDefinitionId)

This matters because role assignments should not have arbitrary names. If one tool or team generates the assignment name using one set of inputs and another tool uses something different, you can end up with the same assignment intent represented by different assignment names. That is exactly the sort of inconsistency that makes troubleshooting harder than it needs to be.

Using the standard generation pattern gives you a few benefits:

• Consistent behaviour across tooling
• Better conformance with the broader Azure platform expectation
• Easier reasoning when comparing manually created and IaC-created assignments
• Fewer surprises when different teams or delivery tools interact with the same scope

If you are still generating the role assignment name using arbitrary values, or values that do not include the scope, principal ID, and role definition ID, it is worth correcting that.

For example, this is the pattern I would now avoid:

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
	name: guid('contributor', principalId) // <-- Avoid
	scope: resourceGroup()
	properties: {
		roleDefinitionId: contributorRoleDefinitionId
		principalId: principalId
		principalType: 'ServicePrincipal'
	}
}

And this is the pattern to prefer:

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
	name: guid(resourceGroup().id, principalId, contributorRoleDefinitionId)
	scope: resourceGroup()
	properties: {
		roleDefinitionId: contributorRoleDefinitionId
		principalId: principalId
		principalType: 'ServicePrincipal'
	}
}

It is deterministic, aligned to the standard, and much easier to reason about when you need to compare behaviour across tools.

Friendly Role Definition Lookup in Bicep

The next improvement is the Bicep roleDefinitions() function introduced in v0.42.1.

This allows you to retrieve the role definition ID from the friendly role name:

properties: {
	roleDefinitionId: roleDefinitions('Data Factory Contributor').id
	...
}

From a readability point of view, this is a nice improvement, and probably the part most people will notice first.

If you compare a friendly name such as Data Factory Contributor to a raw GUID, it is immediately obvious which role is being assigned. That helps with:

• Code reviews
• Onboarding team members into your templates
• General maintainability when revisiting code months later

Compare the older style:

var contributorRoleDefinitionGuid = 'b24988ac-6180-42a0-ab88-20f7382dd24c'

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
	name: guid(resourceGroup().id, principalId, contributorRoleDefinitionId)
	scope: resourceGroup()
	properties: {
		roleDefinitionId: contributorRoleDefinitionId
		principalId: principalId
		principalType: 'ServicePrincipal'
	}
}

With the newer style:

var contributorRoleDefinition = roleDefinitions('Contributor')

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
	name: guid(resourceGroup().id, principalId, contributorRoleDefinition.id)
	scope: resourceGroup()
	properties: {
		roleDefinitionId: contributorRoleDefinition.id
		principalId: principalId
		principalType: 'ServicePrincipal'
	}
}

I think there is a very fair maintainability argument in favour of the second example. The intent is clearer and there is less mental translation required when reading the template.

The Trade-Off

This is where I would urge a little caution.

Whilst roleDefinitions() improves readability, it also introduces a dependency on the display name of the role definition. The underlying role definition ID may remain stable, but the role display name can change over time, even when the underlying role definition ID remains the same.

Is that likely to happen frequently? No, probably not.

Is it impossible? Also no.

That is the trade-off.

If a built-in role display name changes and your template is resolving the role definition by name, then your deployment can break even though the underlying role definition itself still exists and still has the same stable ID.

So I think the balanced view here is:

• If readability and authoring clarity are your primary concern, roleDefinitions() is a very welcome improvement
• If you are optimising for resilience and want to minimise dependency on mutable display names, stable GUID-based references are still a valid approach

This is also a good argument for centralising stable role definition GUIDs if you choose to keep using them, for example through shared variables or imports. That way you still gain maintainability benefits without scattering raw IDs throughout your codebase.

Recommended Practice

My current view would be:

• Always generate the role assignment name using guid(scope, principalId, roleDefinitionId)
  • Treat that pattern as the standard regardless of whether you are using Portal, Bicep, AzCLI, PowerShell, or Terraform
• Use roleDefinitions() where readability and maintainability are more valuable than the small risk of role display name changes
• Use stable GUID-based role definition references where deployment resilience is the higher priority

The important point is not that one of these approaches is universally right and the other universally wrong. It is that you should make the choice consciously.

What I do think should now be treated as non-negotiable is the role assignment naming pattern. That should follow the platform standard.

Conclusion

Recent changes around role assignments are moving things in the right direction.

The improved RoleAssignmentExists message makes diagnosis easier. The defined standard for role assignment ID generation improves conformance across teams and tooling. And the roleDefinitions() function in Bicep improves readability and maintainability when you want friendlier authoring.

For me, the key takeaway is fairly simple: adopt the standard assignment naming pattern everywhere, and then decide whether friendly-name lookup or stable GUID references are the better fit for your environment.

Hope this helps, and happy Bicep-ing!

In many teams, validation still leans heavily on run history inspection and ad-hoc manual testing. That works in early stages, but it does not scale when you have multiple workflows, shared dependencies, environment-specific behavior, and frequent change. It also makes regression detection harder than it needs to be.

I want to put this series together because Logic Apps teams need a practical, repeatable testing approach that fits the way Standard workflows are designed and delivered.

Why This Series Is Needed

The challenge is not that testing options do not exist. The challenge is that testing is often fragmented across techniques, tools, and stages of delivery.

From a delivery perspective, we need faster confidence loops before deployment, stronger validation after deployment, and clearer boundaries between unit-level behavior and integration-level behavior. Without that, each workflow change carries avoidable uncertainty.

The goal of this series is to bring those pieces together into a coherent testing strategy that teams can adopt incrementally.

Testing Layers for Logic Apps Standard

To make this practical, I will frame testing as layers that move from fast feedback to high confidence in real-world behavior.

1. Workflow design practices for testability and manageability - Shape workflow architecture so tests stay reliable, maintainable, and useful over time.
2. Mock output testing in workflows - Validate control flow and branch logic quickly by simulating action outputs and edge-case responses.
3. Unit tests from Standard workflow definitions in Visual Studio Code - Use workflow definitions as testable assets and automate checks for expected behavior under controlled inputs.
4. Integration tests - Validate connector interactions, contracts, and downstream dependencies in representative environments.
5. Agent loop testing options - Explore iterative, agent-assisted test patterns for scenario generation, replay, and change validation.

Design Principles to Keep in Focus

As this series progresses, a few principles will stay constant:

1. Prefer deterministic workflow boundaries - Keep triggers, actions, and side effects structured so the same input consistently drives predictable outcomes.
2. Separate orchestration from connector-heavy implementation details - Where possible, isolate complex connector behavior behind clean workflow steps to simplify test setup and reduce blast radius.
3. Treat observability as part of test design - Meaningful tracking properties, correlation IDs, and consistent result surfaces improve both debugging and test assertions.
4. Design for environment parity, not environment identity - Your test strategy should tolerate differences between dev, test, and prod while still validating the behavior that truly matters.

In Summary

I am aiming to keep the series practical and implementation-oriented.

If your team has ever said “it worked in one run, but we are not sure why it failed later,” this series is for you.

In most Infrastructure as Code teams, Bicep quality checks start to look mature as soon as linting and deployment validation are in place. In practice, there is still a blind spot: logic-level testing of exported functions, types, and variables.

Most teams validate by deploying to a subscription and checking outcomes afterwards. That is useful, but it is also slow and expensive when what you actually want to verify is pure logic. A shared Bicep library changes, everything still compiles, and then a downstream module fails later in a deployment pipeline because a naming function or constructor behaviour subtly changed. That is exactly the type of issue we normally catch early in application development with unit tests.

If you maintain shared Bicep libraries, this gap hurts quickly:

• Naming functions drift without anyone noticing
• Type constructors change and break downstream modules
• Refactors feel risky because feedback loops are too long

I wanted a way to unit test Bicep logic directly, without deploying anything.

Introducing BicepConsoleTTK

To solve that problem, I created BicepConsoleTTK (Bicep Console Test Tool Kit).

It is a Pester-based framework that executes Bicep expressions through the Bicep console REPL, so you can assert outputs in fast, repeatable unit tests.

Repository:

At a high level, the toolkit gives you two commands:

• Import-Bicep: reads one or more Bicep files and extracts the exports you ask for
• Invoke-BicepExpression: runs those declarations plus your expression in bicep console and returns the result

Why This Approach Works

This lets you test Bicep logic in isolation, before template deployment.

Practical outcomes:

• Faster feedback during development
• More confidence when refactoring shared functions
• Cleaner CI pipelines for template libraries
• Better separation between unit tests (logic) and integration tests (deployment)

Features

• Familiar import syntax (named imports and wildcard imports)
• Multi-file import composition with preserved order
• Deduplication when the same member is imported multiple ways
• Setup declarations for multi-step scenarios
• Pipeline input support
• Cleaner Bicep console error reporting
• CI/CD-friendly, non-interactive execution

Prerequisites

• PowerShell 5.1 (Desktop) or 7+
• Pester 5.x
• Bicep CLI 0.42.1+
• bicep available on your PATH

Installation

From PowerShell Gallery

Install-Module -Name BicepConsoleTTK -Repository PSGallery

In your test file:

BeforeAll {
	Import-Module BicepConsoleTTK -Force
}

From Source

git clone https://github.com/Andrew-D-Wilson/bicep-console-test-framework.git
Import-Module "$PSScriptRoot/../src/BicepConsoleTTK" -Force

Copilot Integration

This repository ships two complementary artefacts that teach GitHub Copilot how to write BicepConsoleTTK tests.

Agent Skill (Recommended)

The .github/skills/bicepconsolettk/SKILL.md file is a GitHub Copilot agent skill. When Copilot is working in agent mode, it automatically loads this skill whenever the task is related to writing Bicep tests, injecting the full authoring guide into its context.

The skill is discovered automatically from .github/skills/ in any repository that contains it.

VS Code Instructions File

The bicepconsolettk.instructions.md file is a VS Code Copilot custom instructions file.

To use it in your own repository:

1. Copy the file to .github/instructions/bicepconsolettk.instructions.md
2. Keep applyTo: "**/*.Tests.ps1" so it is scoped to Pester test files
3. Ask Copilot to generate or refactor tests in your *.Tests.ps1 files

With both artefacts in place, Copilot gets better guidance in both agent-driven workflows and editor-scoped instruction workflows.

Usage

1. Import exports from Bicep files

$imports = Import-Bicep @(
	"import {coreParams, newCoreParams} from '$PSScriptRoot/../shared/Types.bicep'",
	"import {basicResource}             from '$PSScriptRoot/../shared/NamingFunctions.bicep'"
)

2. Evaluate an expression

$result = Invoke-BicepExpression -b $imports -e "newCoreParams('uksouth', 'uks', 'prod', 'myapp')"

3. Use setup declarations when needed

$setupDeclarations = @(
	"var projectNameStart = 'hello'",
	"var projectNameComplete = '`${projectNameStart}world'",
	"var coreParameters coreParams = newCoreParams('uksouth', 'uks', 'dev', projectNameComplete)"
)

$result = Invoke-BicepExpression -b $imports -s $setupDeclarations -e "basicResource('aks', coreParameters)"

Example Pester Test

BeforeAll {
	Import-Module BicepConsoleTTK -Force
}

Describe "Naming Functions" {
	BeforeAll {
		$script:imports = Import-Bicep @(
			"import {coreParams, newCoreParams} from '$PSScriptRoot/../shared/Types.bicep'",
			"import {basicResource, csResource} from '$PSScriptRoot/../shared/NamingFunctions.bicep'"
		)
	}

	It "basicResource includes abbreviation, project, environment and location" {
		$result = Invoke-BicepExpression -b $script:imports `
			-e "basicResource('aks', newCoreParams('uksouth', 'uks', 'dev', 'myapp'))"

		$result | Should -Be "'aks-myapp-dev-uksouth'"
	}
}

Run tests with:

Invoke-Pester -Path ./tests

How It Works (Short Version)

Import-Bicep parses import strings, resolves file paths, and extracts exported declarations from source files.

Invoke-BicepExpression sends those declarations and your expression into bicep console, captures output, and translates console noise into readable exceptions when failures occur.

That gives you deterministic, fast unit tests focused on logic instead of deployment orchestration.

Where This Fits in Your Testing Strategy

Use BicepConsoleTTK for:

• Function output verification
• Naming convention enforcement
• Shared type constructor validation
• Regression checks during refactoring

Still keep deployment/integration tests for:

• Resource runtime behavior
• Policy and RBAC interactions
• End-to-end environment validation

Both layers matter. This tool improves the unit-testing layer.

In Short

BicepConsoleTTK helps you test Bicep exports the same way you test application code: quickly, repeatedly, and early.

If your team relies on shared Bicep libraries, this can remove a lot of friction from your delivery pipeline while increasing confidence in every change.

I recently had to troubleshoot an issue where two App Registrations in the same tenant had the same display name.

Azure allows this. Operationally, it hurts.

When names are duplicated, diagnosis gets slower and riskier because engineers cannot trust what they see first in the portal.

Why It Matters

Display names are not unique identifiers. They are labels.

That creates avoidable failure modes:

• Wrong app selected during incident response
• Secrets/certificates updated on the wrong registration
• Permission checks performed against the wrong object
• Longer time to restore service because every step needs extra ID validation

What Is Actually Unique

• Display name: not unique
• Application (client) ID: unique
• Object ID: unique
• Service principal object ID: unique per tenant instance

Humans start with names; Azure enforces uniqueness with IDs. Good naming closes that gap.

Good Practice Guidance

1. Adopt a Naming Standard

Use a format that encodes identity and purpose, for example:

<org>-<workload>-<environment>-<purpose>

Example:

contoso-orders-prod-api

2. Make Environment Explicit

Always include dev/test/stage/prod in the display name, especially for production.

3. Avoid Generic Labels

Names like api, webapp, or integration will collide over time.

4. Add Ownership Metadata

Capture owning team, support channel, and source repo in notes or linked documentation.

5. Review Regularly

Run periodic tenant hygiene checks for:

• Duplicate names
• Missing owner data
• Stale or unused app registrations

If You Already Have Duplicates

1. Inventory duplicates.
2. Map each app to workload and owner.
3. Rename to standard format.
4. Update runbooks and operational docs.
5. Add pre-create checks so the issue does not return.

In Short

Yes, you can rename later. In practice, teams usually do not until an incident forces it.

Just because duplicate display names are allowed does not mean they are a good idea.

⚠️ NOTE

Microsoft guidance is clear that Azure RBAC should be used for data plane authorization moving forward, instead of legacy access policies

• Azure role-based access control (Azure RBAC) vs. access policies (legacy)
• Provide access to Key Vault keys, certificates, and secrets with Azure role-based access control

Problem Space

When multiple applications share a single Azure Key Vault, access policy management can become an unexpected source of deployment risk → and the root cause is easy to miss.

// BICEP
resource KeyVaultDeploy 'Microsoft.KeyVault/vaults@2025-05-01' = {
  name: ''
  location: ''
  properties: {
    ...
    accessPolicies: []
    ...
  }
}

The accessPolicies property on the Microsoft.KeyVault/vaults ARM resource is a required field. In a shared Key Vault scenario, where the vault is owned and deployed by one application, the natural thing to do is set this to an empty array as the application does not own the other applications access policies, so it does not declare them.

This is where the problem begins.

When ARM deploys the Key Vault resource with accessPolicies set to an empty array [], it treats that as the desired state for the vault. Any access policies that existed previously (including those belonging to other applications) are removed.

Here is how the failure pattern plays out in practice:

1. Application A owns the Key Vault and deploys it with accessPolicies: [].
2. Immediately after, Application A’s IaC deploys its own access policies via a separate step (for example, using the Microsoft.KeyVault/vaults/accessPolicies child resource). Access is restored for Application A without apparent issue.
3. Application B’s access policies have been silently removed — it never re-deploys the key vault, only its own access policy step.
4. Application B fails at runtime when attempting secret, key, or certificate operations — authorization errors with no obvious cause.
5. Application B is re-deployed, its access policies are restored, and both applications work again — until the next time Application A’s pipeline runs.

This cycle repeats silently. Each Application A deployment is an outage for Application B, and the connection between the two is not obvious unless you know to look for it.

This can happen if you have the following setup:

• Multiple applications or pipelines sharing a Key Vault
• The Key Vault instance deployed as part of one application’s IaC
• Access configured through Key Vault access policies
• Each application’s pipeline independently managing only its own policy entries

Workarounds (Still Using Access Policies)

If moving to RBAC immediately is not possible, the following workarounds address the underlying coupling problem — but each comes with trade-offs.

1. Move the Key Vault to a Core Resources Deployment

Extract the Key Vault resource into a dedicated core infrastructure deployment, separate from any application pipeline. Application pipelines then only manage their own access policy entries against the pre-existing vault.

Benefits:

• The vault is no longer redeployed as part of application changes
• Eliminates the empty accessPolicies overwrite problem
• Makes ownership of the shared resource explicit

Trade-off:

• When the core resources deployment runs (for environment rebuilds, configuration changes, or disaster recovery), all dependent applications will need to be re-deployed afterwards to restore their access policy entries. This creates an operational dependency that must be planned for and communicated clearly across teams.

2. Provision a Separate Key Vault Per Application

Give each application its own dedicated Key Vault, eliminating the shared resource entirely.

Benefits:

• No cross-application policy coupling — each key vault is fully owned by one application
• Reduces blast radius of deployment mistakes
• Cleaner isolation and tenancy boundaries

Trade-offs:

• More key vaults to provision, monitor, rotate secrets in, and govern
• Increases operational overhead for certificate and secret lifecycle management
• Harder to get a unified view of secrets across the estate

This option improves isolation but does not solve the root-cause pattern; it just limits the blast radius per key vault.

The Real Solution: Move to Azure RBAC

The correct long-term fix is to stop using access policies for Key Vault data plane authorization entirely and adopt Azure RBAC role assignments.

With RBAC:

• Role assignments are additive and independently managed — assigning a role for Application B does not affect Application A’s assignments
• Authorization state is managed through Azure’s centralized RBAC model, consistent with the rest of the Azure platform
• Microsoft explicitly recommends RBAC over access policies for new and migrating workloads

The deployment pattern becomes:

1. Deploy the Key Vault resource. The accessPolicies field becomes irrelevant.
2. Each application independently deploys Microsoft.Authorization/roleAssignments scoped to the vault for its own managed identity or service principal.
3. An application deployment wont affect another application’s authorization.
4. A redeploy of the Key Vault resource won’t remove existing application’s authorizations.

Practical migration approach:

1. Enable the RBAC permission model on the Key Vault IaC (enableRbacAuthorization: true).
2. Map existing access policy permissions to the appropriate built-in Key Vault RBAC roles (for example Key Vault Secrets User, Key Vault Certificates User).
   • Assign roles to the required identities at the appropriate scope (Key Vault, Key Vault Secret/Certificate).
3. Remove legacy access policy configuration from all IaC templates.
4. Deploy IaC and Validate application behavior against the new authorization model.

Useful Microsoft documentation:

• RBAC vs access policy comparison and recommendation
• RBAC implementation guidance for Key Vault

Closing Thoughts

The empty accessPolicies: [] pattern is easy to arrive at — the field is required, the application does not own the other policies, so an empty array seems reasonable. In a single-application setup it causes no problems. In a shared-vault, multi-application setup it causes silent, repeating outages that are hard to diagnose without knowing where to look.

The workarounds described here reduce the risk while a migration is planned, but neither fully resolves the underlying problem.

The right answer is Azure RBAC. Role assignments are independent, additive, and do not interfere with each other across application boundaries. Moving to RBAC removes this class of problem entirely.

As Bicep adoption grows, so does the complexity of the environments and teams using it. Without clear authoring practices, Bicep codebases can quickly become inconsistent, hard to maintain, and error-prone. In this post I wanted to share some practical authoring practices and anti-patterns to help you and your team write better Bicep code.

Why Define and Stick to Your Authoring Practices

Defining and following authoring practices ensures:

• Consistency across your codebase and team
• Easier onboarding for new contributors
• Fewer errors and less technical debt
• Improved maintainability and clarity

Below are some key practices and common anti-patterns to consider.

Authoring Practices

1. Folder Structure

Organise your Bicep files in a logical folder structure. For example, group modules by resource type or deployment context. This makes navigation and reuse easier:

├── modules/
│   ├── storage/
│   └── networking/
├── main.bicep
├── parameters/

2. Template Structure

Keep your templates clean and modular. Use modules for reusable components, and keep your main entry point focused on orchestration. Avoid putting everything in a single file.

3. Well Defined Names

Use clear, descriptive names for resources, parameters, and variables. Avoid abbreviations that aren’t widely understood. For example, prefer storageAccountName over saName.

4. Descriptions

Add descriptions to parameters, outputs, and resources. This helps users understand intent and usage:

@description('Configurable name for the application storage account')
param storageAccountName string

5. Comments

Use comments to explain why something is done, not what is done. Avoid echoing the code. Good comments provide context or rationale.

6. Constraints and Metadata

Leverage allowed values, min/max length, and metadata to enforce constraints and provide guidance:

@minLength(3)
@maxLength(24)
@allowed([ 'dev' 'test' 'prod' ])
param environment string

Make sure to use these where there is a specific need, over constraining parameters can equally cause issues.

7. Contracts

Define clear contracts for your modules: what parameters are required, what outputs are provided, and what assumptions are made. Document these in the module and in a README.

8. README

Modules and major orchestrating templates should have a README explaining its purpose and usage. This is invaluable for onboarding and reuse.

9. Bicep Linting

Use Bicep linting as part of your authoring workflow to catch issues early and enforce consistency. Define team linting rules in bicepconfig.json, run lint checks locally during development, and enforce them in CI to prevent low-quality or non-compliant templates from being merged.

10. AI-Generated Templates and Conformance

If you are using AI to generate Bicep, treat your authoring practices as executable guardrails rather than optional guidance.

Start by defining a clear generation contract in your prompt and repository standards:

• Require a specific folder structure and file naming convention
• Require module contracts (documented params/outputs and assumptions)
• Require descriptions, meaningful names, and no dead code
• Require lint-clean output before a template is considered complete

Then enforce conformance automatically in CI:

• Validate formatting and linting on every pull request
• Fail builds when lint rules are violated
• Optionally add policy checks (for example, naming, locations, and SKUs)
• Require human review for architectural decisions, not just syntax correctness

Finally, use a feedback loop. When reviewers find repeated AI mistakes, update your prompt template, lint configuration, and module examples so the next generation cycle improves by default.

Anti-Patterns

1. Premature Abstraction

Don’t create modules or abstractions before you have a real need. Over-abstraction leads to unnecessary complexity and maintenance overhead.

2. Over-Specification

Avoid making every resource parameter configurable if it’s not needed. Too many parameters can confuse users and make templates harder to use.

3. Echo Comments

Comments that simply restate the code add no value. For example:

// Set the storage account name
param storageAccountName string

Instead, explain why a value is needed or any constraints.

4. Dead Code

Remove unused parameters, variables, and resources. Dead code clutters templates and can cause confusion or errors.

5. Generic Copy-Paste Documentation

Avoid boilerplate documentation that doesn’t reflect the actual template. Tailor docs and comments to the specific module or resource.

6. Poorly Defined Names

Names like var1 or resource2 make templates hard to understand. Use meaningful, descriptive names everywhere.

Conclusion

Establishing and following authoring practices for Bicep will help your team deliver infrastructure as code that is robust, maintainable, and easy to understand. Avoid common anti-patterns, and invest in clarity and documentation.

I have been writing integration tests using MSTest recently and have encountered the need to control the level of parallelism required. MSTest, by default, runs your tests in parallel to maximise performance and reduce overall test execution time. This is great for independent unit tests, but it can quickly become a problem when you’re writing integration tests that access shared resources like databases, APIs, or cloud services. I recently encountered this issue when my integration test suite started failing randomly due to parallel tests competing for the same data or creating conflicting test data. The solution? Learning to control MSTest’s parallelism settings.

This post covers the various options available for controlling parallelism in your MSTest projects, from completely disabling parallel execution to fine-tuning which tests run in parallel and which ones run sequentially.

The Problem Scenario

Imagine you have a suite of integration tests for a customer management system. You have 20 integration tests that interact with a shared test database. Without parallelism control, MSTest might run all 20 tests simultaneously:

• Test A creates a customer with email “test@example.com”
• Test B simultaneously tries to create the same customer, causing a duplicate key error
• Test C queries the database expecting 5 records, but gets 25 because other tests are also inserting data
• Test D rolls back a transaction that Test E is still trying to read from

The result? Intermittent test failures that are hard to debug and unreliable CI/CD pipelines. By controlling parallelism, you can ensure tests that share resources run sequentially while still leveraging parallel execution where it’s safe.

Configuration Options

MSTest provides two main approaches for configuring parallelism:

1. Per unit test file - Add the Parallelize attribute directly in your test files
2. Global configuration - Set it once in the MSTestSettings.cs configuration file for all tests

Understanding the Parallelize Attribute

The Parallelize attribute controls how tests run in parallel:

[assembly: Parallelize(Scope = ExecutionScope.MethodLevel, Workers = 0)]

Parameters

• Workers: Specifies the number of threads to run the tests. Set to 0 to automatically use the number of CPU cores available on your machine. You can also specify an explicit number like Workers = 4 to limit parallelism.

• Scope: Determines the level at which tests are parallelized:

  • ExecutionScope.MethodLevel - Runs all test methods in parallel, regardless of which class they belong to
  • ExecutionScope.ClassLevel - Runs test classes in parallel, but tests within the same class execute sequentially. Use this when tests within a class have interdependencies or shared state.

Applying Per Test File

Add the assembly attribute at the top of your test file:

[assembly: Parallelize(Scope = ExecutionScope.MethodLevel, Workers = 0)]

namespace Test.UnitTests
{

Global Configuration with MSTestSettings.cs

For project-wide settings, create or update your MSTestSettings.cs file:

[assembly: Parallelize(Scope = ExecutionScope.MethodLevel, Workers = 0)]

This approach keeps parallelization settings consistent across all test files in your project.

Running Tests Sequentially

To run all unit tests sequentially, simply remove the Parallelize assembly attribute from either the individual test file or the MSTestSettings.cs file, depending on which tests you want to run sequentially.

Mixed Parallelism: Running Specific Tests Sequentially

In some scenarios, you may want most tests to run in parallel, but certain tests need to execute sequentially (e.g., tests that access shared resources or databases). To achieve this:

1. Keep the Parallelize assembly attribute in place
2. Mark specific test methods with the [DoNotParallelize] attribute

[TestClass]
public class DatabaseTests
{
    [TestMethod]
    [DoNotParallelize]
    public async Task TestDatabaseConnection()
    {
        // This test will run sequentially
    }

    [TestMethod]
    public async Task TestDataRetrieval()
    {
        // This test will run in parallel with other parallel tests
    }
}

Controlling Test Execution Order

While the best practice is to write independent unit tests that don’t rely on execution order, there are legitimate cases where ordering is necessary, such as:

• Integration tests with setup/teardown dependencies
• Tests that validate a sequence of operations
• End-to-end scenarios that must execute in a specific order

For more details on ordering tests, see the official Microsoft documentation on ordering unit tests.

Ensuring Consistent Ordering

To guarantee that test ordering works consistently in both Visual Studio Test Explorer and command-line test runs, add a .runsettings file to the root of your test project:

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <MSTest>
    <OrderTestsByNameInClass>true</OrderTestsByNameInClass>
  </MSTest>
</RunSettings>

This ensures tests within a class are ordered alphabetically by method name. You can then control order by naming your test methods accordingly (e.g., Test01_FirstStep, Test02_SecondStep).

Best Practices

1. Default to parallel execution for unit tests to maximize performance
2. Apply [DoNotParallelize] selectively to tests where there are specific dependencies
3. Avoid test ordering when possible by ensuring tests are independent
4. Monitor test execution time and adjust the Workers parameter if needed

Conclusion

MSTest provides flexible options for controlling test parallelism, allowing you to balance execution speed with reliability. Start with parallel execution at the method level, and only introduce restrictions where necessary based on your specific test requirements.

Hope this helps and Happy Testing.

When building integration workflows with Azure Logic Apps Standard, there’s often a need to track custom business events that sit between pure technical telemetry and business process monitoring. Recently, while authoring a Logic App Standard workflow, I needed to track the total number of items processed along with a breakdown of successful versus failed processing attempts.

While Logic Apps provides excellent run history and built-in diagnostics, custom events allow you to capture specific business actions and metrics that align with your reporting requirements. In this post, I’ll show you how to send custom events directly to Azure Application Insights using the ingestion endpoint from the Application Insights connection string.

The Use Case

I needed to answer questions like:

• How many items were processed in total for a workflow run?
• What’s the success vs. failure rate for different item types?
• Can I correlate these metrics with other application telemetry?

Standard Logic Apps diagnostics don’t easily provide this level of custom business metric tracking, making Application Insights custom events the perfect solution.

Understanding the Application Insights Ingestion Endpoint

The Application Insights connection string contains several components, including the ingestion endpoint. It looks something like this:

InstrumentationKey=<key>;IngestionEndpoint=https://<region>.in.applicationinsights.azure.com/;LiveEndpoint=https://<region>.livediagnostics.monitor.azure.com/;ApplicationId=<ID>

// Broken Down
//------------
InstrumentationKey=<key>

IngestionEndpoint=https://<region>.in.applicationinsights.azure.com/

LiveEndpoint=https://<region>.livediagnostics.monitor.azure.com/

ApplicationId=<ID>

The Ingestion Endpoint component as the name suggests is used for the ingest of telemetry/metrics/events/etc. The component points to a regional Application Insights endpoint with the Instrumentation key supplied later in in the ingestion request for targeting your specific Application Insights instance.

The missing part to this endpoint that allows you to post your telemetry is a trailing v2/track. Combined this appears as follows: https://<region>.in.applicationinsights.azure.com/v2/track

We’ll use the IngestionEndpoint combined with the InstrumentationKey to send custom events via HTTP requests.

Implementation

Step 1: Configure Application Insights Connection in Bicep

First, we need to extract the ingestion endpoint and instrumentation key from Application Insights and make them available to our Logic App as application settings:

resource applicationInsights 'Microsoft.Insights/components@2020-02-02' existing = {
  name: applicationInsightsName
}

resource logicAppDeployment 'Microsoft.Web/sites@2025-03-01' = {
  name: logicAppName
  location: Location
  kind: 'functionapp,workflowapp'
  properties: {
    ...
    siteConfig: {
      ...
      appSettings: [
        ...
        {
          name: 'appInsightsIngestUrl'
          value: '${split(filter(split(applicationInsights.properties.ConnectionString, ';'), val => contains(val, 'IngestionEndpoint='))[0], '=')[1]}v2/track'
        }
        {
          name: 'appInsightsKey'
          value: applicationInsights.properties.InstrumentationKey
        }
      ]
    }
  }
}

The Bicep code above parses the connection string to extract the ingestion endpoint and appends the required v2/track path. It also captures the instrumentation key needed to point to your instance.

Step 2: Create Logic App Parameters

Add parameters to your Logic App Workflow’s parameters.json file to reference these application settings:

{
    "AppInsightsIngestionUrl": {
        "type": "String",
        "value": "@appsetting('appInsightsIngestUrl')"
    },
    "AppInsightsKey": {
        "type": "String",
        "value": "@appsetting('appInsightsKey')"
    }
}

These parameters allow your workflow to access the ingestion URL and key at runtime.

Step 3: Add the Workflow Actions and Event Payload

In your Logic App workflow, use a Compose action to build the Application Insights event payload. The payload follows the Application Insights telemetry schema:

{
  "name": "Microsoft.ApplicationInsights.@{parameters('AppInsightsKey')}.Event",
  "time": "@{utcNow()}",
  "iKey": "@{parameters('AppInsightsKey')}",
  "data": {
    "baseType": "EventData",
    "baseData": {
      "ver": "2",
      "name": "LogicAppWorkflowName",
      "properties": {
        "workflowRunId": "@{workflow().run.name}",
        "ItemsProcessed": "",
        "Type1Count":  "",
        "Type1CountFailures":  "",
        "Type2Count":  "",
        "Type2CountFailures":  "",
        "Type3Count":  "",
        "Type3CountFailures":  ""
      }
    }
  }
}

Key components of the payload:

• name: Event identifier following Application Insights naming convention
• time: Timestamp in UTC format
• iKey: Your instrumentation key
• data.baseData.name: The custom event name that will appear in Application Insights
• data.baseData.properties: Your custom properties containing business metrics

Step 4: Send the Event via HTTP

Add an HTTP action to send the composed payload to Application Insights:

Configure the HTTP action with:

• Method: POST
• URI: @{parameters('AppInsightsIngestionUrl')}
• Headers: Content-Type: application/json
• Body: Output from the Compose action

The HTTP action will receive a 200 OK response when the event is successfully ingested.

The response body should indicate a successful ingestion as follows:

{
    "itemsReceived": 1,
    "itemsAccepted": 1,
    "errors": []
}

Step 5: Query Your Events

After your workflow runs, navigate to Application Insights and use the following KQL query to view your custom events:

customEvents
| where name == "LogicAppWorkflowName"
| project timestamp, 
          workflowRunId = tostring(customDimensions.workflowRunId),
          itemsProcessed = toint(customDimensions.ItemsProcessed),
          type1Success = toint(customDimensions.Type1Count),
          type1Failures = toint(customDimensions.Type1CountFailures)
| order by timestamp desc

You can create custom dashboards, alerts, and reports based on these events.

Summary

By leveraging the Application Insights ingestion endpoint directly via HTTP actions, you can easily track custom business metrics from your Logic Apps Standard workflows without external dependencies. This approach lets you correlate workflow execution with wider integration components/applications and build comprehensive dashboards based on your specific use case.

Hope this helps, and keep Workflow-ing!

I recently upgraded an Azure Function from .NET 8 to .NET 9, and at the same time migrated from the in-process worker to the isolated worker model. After the upgrade, my function that returned OkObjectResult started returning an empty JSON object {} instead of the expected data.

[Function("MyFunction")]
public IActionResult Run([HttpTrigger(AuthorizationLevel.Function,  "post")] HttpRequest req)
{
    var data = new MyResponse { Name = "Test", Value = 123 };
    return new OkObjectResult(data); // Returns {} instead of expected JSON
}

Why This Happens

There are two key changes that caused this issue:

1. In-Process to Isolated Worker Migration

The isolated worker process runs in a separate process from the Functions host. Unlike the in-process model, it doesn’t inherit any configuration or serialization settings. You’re starting with a clean slate and need to explicitly configure everything.

2. JSON Serializer Change

Starting with ASP.NET Core 3.0, Microsoft replaced Newtonsoft.Json with System.Text.Json as the default serializer. While both serialize JSON, they have different behaviors:

• Newtonsoft.Json: More lenient, serializes public properties and fields
• System.Text.Json: Stricter, only serializes public properties by default

When using OkObjectResult (an ASP.NET Core MVC type) in an isolated worker, you need to explicitly configure MVC services. Without this configuration, the serialization doesn’t work as expected.

The Solutions

You have two approaches to fix this, each with different trade-offs:

Option 1: Use Native Isolated Worker Types (Recommended)

Embrace the isolated worker model by using the native types designed for it:

[Function("MyFunction")]
public async Task<HttpResponseData> Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req)
{
    var data = new MyResponse { Name = "Test", Value = 123 };
    
    var response = req.CreateResponse(HttpStatusCode.OK);
    await response.WriteAsJsonAsync(data); // Uses System.Text.Json by default
    
    return response;
}

Advantages:

• Better Performance: System.Text.Json is significantly faster than Newtonsoft.Json
• Lower Costs: Reduced latency means less execution time, which directly reduces Azure Functions costs (billed per execution time)
• Lighter Dependencies: No need for additional MVC services or packages
• Future-Proof: Aligned with the modern .NET isolated worker architecture
• Native Support: Uses types specifically designed for isolated workers

Disadvantages:

• Requires code changes to migrate from IActionResult to HttpResponseData
• May need adjustments if you rely on specific Newtonsoft.Json features

Option 2: Add MVC Services with Newtonsoft.Json (Quick Fix)

If you need a quick fix or have complex serialization requirements, you can add MVC services with Newtonsoft.Json support to your Program.cs:

using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

// Add MVC services and configure Newtonsoft.Json
builder.Services.AddMvc().AddNewtonsoftJson();

builder.Build().Run();

You’ll also need to add the NuGet package:

dotnet add package Microsoft.AspNetCore.Mvc.NewtonsoftJson

Advantages:

• Minimal code changes - keeps existing OkObjectResult code working
• Maintains backward compatibility with Newtonsoft.Json serialization behavior
• Good for quick migration when you have tight deadlines

Disadvantages:

• Higher Costs: Slower serialization means longer execution time and higher Azure Functions bills
• Additional Dependencies: Requires MVC framework which adds overhead
• Technical Debt: You’re opting back into older patterns instead of embracing the new architecture

Which Should You Choose?

For new projects or if you can afford the refactoring time: Go with Option 1 (native types). The performance benefits and cost savings will compound over time, especially for high-traffic functions.

For quick migrations with tight deadlines: Option 2 can get you unstuck quickly, but consider it temporary. Plan to refactor to native types when time permits.

Takeaway

When migrating to .NET 9 isolated worker Functions, you’re working in a fresh environment that requires explicit configuration. While adding Newtonsoft.Json gets things working quickly, embracing the native isolated worker types with System.Text.Json offers better performance and lower costs (⚠️important factors when Azure Functions are billed per execution time). Choose the approach that balances your immediate needs with long-term architecture goals.

Hope this helps, Happy Coding.

There have been few times where I have landed into this particular predicament whereby either by my own doing or through the use of another’s code base, a deep nested or thoroughly utilised (parameter/variable/or other defined item) has been created with the same name as a Bicep function. As by Murphy’s law, its only once you have reached this point of no return that you realise that your items name conflicts.

Now if you are like many in your unawares, your thoughts and actions will conclude to a singular one of ’that sucks… followed by a nasty refactor'.

Solution - Namespaces

Namespaces are a declarative scope in which identifiers such as the names of types, functions, and variables can be declared. These namespaces are used to organise code into logical groups and to prevent name collisions such as the one you are currently experiencing.

Thankfully, in Bicep there are two namespaces where all functions are split, az and sys.

• az | Contains functions that are specific to an Azure deployment such as:
  • deployment
  • environment
  • resourceGroup
  • subscription
• sys | Contains functions that are used to construct values, and decorators for parameters and resource loops. This includes but is not limited to:
  • [Array] concat
  • [File] loadJsonContent
  • [Lambda] filter
  • [Logical] bool
  • [Numeric] int
  • [String] contains

To make use of these namespaces, simply add the namespace identifier in front of the function. The example below shows a real world example of this issue where a parameter name ‘environment’ has been extensively utilised in this template and many others. This particular template is being used to deploy an AuthProvider in API Management, and the author wishes to utilise the environment function for the authentication.loginEndpoint. Without the use of the az namespace, the environment parameter would need to be refactored both in this template and wider templates for consistency.

/******************************************
Bicep Template: Function Namespace Example
Author: Andrew Wilson
******************************************/

targetScope = 'resourceGroup'

// ** Parameters **
// ****************

@description('The environment to deploy the resources to.')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string = 'dev'

...

// ** Resources **
// ***************

...

// Create a new Auth Provider in APIM Credential Manager
resource AuthorizationProvider 'Microsoft.ApiManagement/service/authorizationProviders@2024-05-01' = {
  ...
  properties: {
    ...
    oauth2: {
      ...
      grantTypes: {
        clientCredentials: {
          loginUri: az.environment().authentication.loginEndpoint
        }
      }
    }
  }
}

As always, have a play, and happy Bicep-ing!

Building on our previous exploration of Typed Variables, today we’re diving into one of my favorite patterns for creating maintainable and reusable Bicep templates: the Shared Variable File Pattern. This approach transforms your templates from being tightly coupled to specific configurations into truly agnostic, environment-ready solutions.

The beauty of this pattern lies in its simplicity - by extracting configuration data into external JSON or YAML files, you can create templates that adapt without modification. When combined with typed variables, this approach becomes even more powerful, providing compile-time validation and enhanced developer experience.

Why Use Config Files?

Before diving into the implementation, let’s understand why this pattern is so valuable:

1. Separation of Concerns: Keep your infrastructure logic separate from configuration data
2. Reduced Template Complexity: Remove large, complex variable definitions from your templates for better readability
3. Reusability: Share common configurations across multiple templates without duplication
4. Team Collaboration: Non-technical team members can modify configurations without touching Bicep code

The Pattern in Action

Traditional Approach (What We Want to Avoid)

Traditionally, you might embed all configuration directly in your Bicep template:

var nsgRules = [
  {
    name: 'AllowManagementEndpoint'
    properties: {
      description: 'Management endpoint for Azure portal and PowerShell'
      sourceAddressPrefix: 'ApiManagement'
      sourcePortRange: '*'
      destinationAddressPrefix: 'VirtualNetwork'
      destinationPortRange: '3443'
      protocol: 'Tcp'
      access: 'Allow'
      priority: 100
      direction: 'Inbound'
    }
  }
  {
    name: 'AllowAzureInfrastructureLoadBalancer'
    properties: {
      description: 'Azure Infrastructure Load Balancer'
      sourceAddressPrefix: 'AzureLoadBalancer'
      sourcePortRange: '*'
      destinationAddressPrefix: 'VirtualNetwork'
      destinationPortRange: '6390'
      protocol: 'Tcp'
      access: 'Allow'
      priority: 110
      direction: 'Inbound'
    }
  }
  // ... many more rules
]

This approach has several downsides:

• Templates become bloated and hard to read
• Changes require modifying Bicep code
• No separation between infrastructure logic and configuration data

Modern Approach with Config Files

Let’s transform this using the shared variable file pattern combined with typed variables.

Step 1: Create Your Config File

Create the configuration file for your deployment:

configs/nsg-rules.json

{
  "securityRules": [
    {
      "name": "AllowManagementEndpoint",
      "properties": {
        "description": "Management endpoint for Azure portal and PowerShell",
        "sourceAddressPrefix": "ApiManagement",
        "sourcePortRange": "*",
        "destinationAddressPrefix": "VirtualNetwork",
        "destinationPortRange": "3443",
        "protocol": "Tcp",
        "access": "Allow",
        "priority": 100,
        "direction": "Inbound"
      }
    },
    {
      "name": "AllowDeveloperAccess",
      "properties": {
        "description": "Allow developer access from corporate network",
        "sourceAddressPrefix": "10.0.0.0/8",
        "sourcePortRange": "*",
        "destinationAddressPrefix": "VirtualNetwork",
        "destinationPortRange": "443",
        "protocol": "Tcp",
        "access": "Allow",
        "priority": 200,
        "direction": "Inbound"
      }
    }
  ]
}

Step 2: Define Typed Variables

Create a user-defined type to ensure your config files match the expected structure:

// User-Defined Types
// ******************

@sealed()
@description('Defines the structure for NSG security rule properties.')
type nsgSecurityRuleProperties = {
  @description('Description of the security rule.')
  description: string
  @description('Source address prefix or tag.')
  sourceAddressPrefix: string
  @description('Source port range.')
  sourcePortRange: string
  @description('Destination address prefix or tag.')
  destinationAddressPrefix: string
  @description('Destination port range.')
  destinationPortRange: string
  @description('Network protocol (Tcp, Udp, or *).')
  protocol: 'Tcp' | 'Udp' | '*'
  @description('Access type (Allow or Deny).')
  access: 'Allow' | 'Deny'
  @description('Priority value (100-4096).')
  priority: int
  @description('Direction (Inbound or Outbound).')
  direction: 'Inbound' | 'Outbound'
}

@sealed()
@description('Defines the structure for NSG security rule.')
type nsgSecurityRule = {
  @description('Name of the security rule.')
  name: string
  @description('Properties of the security rule.')
  properties: nsgSecurityRuleProperties
}

@sealed()
@description('Defines the structure for NSG configuration file.')
type nsgConfig = {
  @description('Array of security rules.')
  securityRules: nsgSecurityRule[]
}

Step 3: Load and Use Configuration

Now your Bicep template becomes clean and agnostic:

// Parameters
// **********

@description('Environment to deploy to.')
param environment string

// Variables
// *********

// Load configuration with full type safety
var nsgConf nsgConfig = loadJsonContent('./configs/nsg-rules.json')

// Resources
// *********

resource networkSecurityGroup 'Microsoft.Network/networkSecurityGroups@2024-01-01' = {
  name: 'nsg-apim'
  location: resourceGroup().location
  properties: {
    securityRules: nsgConfig.securityRules
  }
}

Advanced Techniques

Multi-Component Configuration Files

You can organise multiple configuration aspects in a single file and load only what you need:

configs/apim-config.json

{
  "networking": {
    "securityRules": [...],
    "subnets": [...]
  },
  "apim": {
    "sku": {
      "name": "Developer",
      "capacity": 1
    },
    "policies": [...]
  },
  "monitoring": {
    "logAnalytics": {...},
    "alerts": [...]
  }
}

Load specific sections using JSONPath:

// Load only the networking configuration
var networkingConfig = loadJsonContent('./configs/apim-config.json', 'networking')

// Load only the APIM configuration
var apimConfig = loadJsonContent('./configs/apim-config.json', 'apim')

Best Practices

1. Use Typed Variables: Define user-defined types for your configuration structures - this provides compile-time validation and excellent IntelliSense support
2. Logical File Organisation: Create separate config files for different aspects (networking, security, monitoring) rather than one monolithic file
3. Validate Early: Let typed variables catch configuration mismatches during authoring, not deployment
4. Size Considerations: Remember that loaded content is included in the generated ARM template (4MB limit)
5. Version Control: Keep config files in source control alongside your Bicep templates

Real-World Benefits

This pattern has transformed how I approach Bicep development:

• Faster Development: IntelliSense support with typed variables makes configuration editing a breeze
• Fewer Deployment Failures: Compile-time validation catches configuration errors before deployment
• Better Team Collaboration: Operations teams can modify configs without touching infrastructure code
• Easier Maintenance: Changes to configuration don’t require Bicep code modifications

Summary

The shared variable file pattern, enhanced with typed variables, creates a powerful combination for building maintainable, agnostic Bicep templates. By separating configuration from infrastructure logic, you gain flexibility, reusability, and compile-time safety that makes your Infrastructure as Code truly robust. Happy Bicep-ing!

One of my core goals when writing IaC templates is ensuring reusability of common components, resources, and in this case, configuration. More often than not, I see configuration that is broadly common between resources (except for one or two properties) being duplicated throughout templates. This duplication means that changing a single property value requires updates across the entire codebase—a change that’s not trivial to manage unless you’re well-versed with the codebase and understand all areas where the configuration is implemented.

This pattern becomes particularly problematic as your infrastructure grows in complexity. Consider scenarios where you need to update a common tag value, modify a naming convention, or adjust a configuration parameter across dozens of resources. Without proper abstraction, these seemingly simple changes can become error-prone maintenance nightmares.

In this post, I’ll demonstrate two powerful Bicep techniques to transform static, duplicated configuration into dynamic, reusable patterns that will make your templates more maintainable and less prone to configuration drift.

Common Configuration Scenarios

Before diving into solutions, let’s examine two common scenarios where static configuration creates maintenance headaches:

Scenario 1: Resource Tagging

Every Azure resource should be properly tagged for governance, cost tracking, and management. However, I frequently see templates where tags are copy-pasted across resources, creating maintenance debt:

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-01-01' = {
  // ... other properties
  tags: {
    BusinessUnit: 'BicepTipsAndTricks'
    Version: deployment().properties.template.contentVersion
    Environment: environment
    Region: region
    ResourceName: 'Storage Account'
    'hidden-title': 'Bicep Tips and Tricks Storage'
  }
  // ... other properties
}

This approach works for a single resource, but imagine maintaining this across 50+ resources. When the business unit name changes or you need to add a new compliance tag, you’re looking at a significant refactoring effort.

Scenario 2: Complex Configuration Structures

Complex JSON configurations, such as Consumption Logic App workflow definitions, often contain embedded values that need to vary between environments or deployments:

{
    "definition": {
        "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
        "actions": {
            "Condition_-_Morning_or_Afternoon": {
                "actions": {
                    "Terminate_-_Afternoon": {
                        "inputs": {
                            "runStatus": "Succeeded"
                        },
                        "runAfter": {},
                        "type": "Terminate"
                    }
                },
                "else": {
                    "actions": {
                        "Terminate_-_Morning": {
                            "inputs": {
                                "runStatus": "Succeeded"
                            },
                            "runAfter": {},
                            "type": "Terminate"
                        }
                    }
                },
                "expression": {
                    "and": [
                        {
                            "greaterOrEquals": [
                                "@utcNow('H:mm:ss')",
                                "12:00:00" // ← Currently hard-coded static configuration
                            ]
                        }
                    ]
                },
                "runAfter": {},
                "type": "If"
            }
        },
        "contentVersion": "1.0.0.0",
        "outputs": {},
        "parameters": {},
        "triggers": {
            "Recurrence_-_Start": {
                "evaluatedRecurrence": {
                    "frequency": "Day",
                    "interval": 1, // ← Currently hard-coded static configuration
                    "schedule": {
                        "hours": [
                            "11"
                        ]
                    }
                },
                "recurrence": {
                    "frequency": "Hour",
                    "interval": "2" // ← Currently hard-coded static configuration
                },
                "type": "Recurrence"
            }
        }
    },
    "parameters": {}
}

In this Consumption Logic App workflow, the recurrence interval, evaluatedRecurrence interval, and condition time values are hard-coded. If you need different intervals or values for different environments (perhaps more frequent polling in production), you’d need to maintain separate configuration files or manually edit values during deployment.

My Recommended Approaches

Approach 1: Union Function for Object Composition

The union() function is perfect for combining base configuration with resource-specific overrides. This approach works exceptionally well for scenarios like tagging, where you have a core set of common properties and some resource-specific additions.

The Problem: Without union, you end up repeating common tags across every resource:

// Bad: Repeated configuration
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-01-01' = {
  tags: {
    BusinessUnit: 'BicepTipsAndTricks'
    Version: deployment().properties.template.contentVersion
    Environment: environment
    Region: region
    ResourceName: 'Storage Account'
    'hidden-title': 'Bicep Tips and Tricks Storage'
  }
}

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  tags: {
    BusinessUnit: 'BicepTipsAndTricks'  // Duplicated!
    Version: deployment().properties.template.contentVersion  // Duplicated!
    Environment: environment  // Duplicated!
    Region: region  // Duplicated!
    ResourceName: 'Key Vault'
    'hidden-title': 'Bicep Tips and Tricks Key Vault'
  }
}

The Solution: Use union to combine base and specific configurations:

// Good: Centralized common configuration
// ** Parameters **
@description('The environment to deploy to')
param environment string = 'dev'

@description('The Azure region to deploy to')
param region string = 'UkSouth'

// ** Variables **
var coreTags = {
  BusinessUnit: 'BicepTipsAndTricks'
  Version: deployment().properties.template.contentVersion
  Environment: environment
  Region: region
}

// Create resource-specific tag combinations
var storageAccountTags = union(coreTags, {
  ResourceName: 'Storage Account'
  'hidden-title': 'Bicep Tips and Tricks Storage'
})

var keyVaultTags = union(coreTags, {
  ResourceName: 'Key Vault'
  'hidden-title': 'Bicep Tips and Tricks Key Vault'
  DataClassification: 'Confidential'  // Additional tag specific to Key Vault
})

// ** Resources **
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-01-01' = {
  name: 'mystorageaccount'
  location: region
  tags: storageAccountTags
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: 'mykeyvault'
  location: region
  tags: keyVaultTags
  properties: {
    sku: {
      family: 'A'
      name: 'standard'
    }
    tenantId: subscription().tenantId
  }
}

Key Benefits:

• Single source of truth: Common tags are defined once in coreTags
• Easy maintenance: Update business unit name? Change it in one place
• Flexible: Each resource can still have unique tags

Approach 2: Token Replacement for Complex Configurations

For complex JSON configurations that need dynamic values, token replacement provides an elegant solution. This approach is particularly powerful when working with imported JSON files that contain configuration.

The Problem: Static values embedded in complex configurations:

The Solution: Use token placeholders and replacement functions.

First, modify your JSON configuration file to use tokens:

{
    "definition": {
        "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
        "actions": {
            "Condition_-_Morning_or_Afternoon": {
                "actions": {
                    "Terminate_-_Afternoon": {
                        "inputs": {
                            "runStatus": "Succeeded"
                        },
                        "runAfter": {},
                        "type": "Terminate"
                    }
                },
                "else": {
                    "actions": {
                        "Terminate_-_Morning": {
                            "inputs": {
                                "runStatus": "Succeeded"
                            },
                            "runAfter": {},
                            "type": "Terminate"
                        }
                    }
                },
                "expression": {
                    "and": [
                        {
                            "greaterOrEquals": [
                                "@utcNow('H:mm:ss')",
                                "__schedule_time__"  // ← Token for schedule time
                            ]
                        }
                    ]
                },
                "runAfter": {},
                "type": "If"
            }
        },
        "contentVersion": "1.0.0.0",
        "outputs": {},
        "parameters": {},
        "triggers": {
            "Recurrence_-_Start": {
                "evaluatedRecurrence": {
                    "frequency": "Day",
                    "interval": 1,
                    "schedule": {
                        "hours": [
                            "__schedule_hour__"  // ← Token for schedule hour
                        ]
                    }
                },
                "recurrence": {
                    "frequency": "Hour",
                    "interval": "__interval__"  // ← Token for interval
                },
                "type": "Recurrence"
            }
        }
    },
    "parameters": {}
}

Then, create a robust token replacement system in your Bicep template:

// ** Imported Types and Functions **
@description('Token Replacement Definition')
@sealed()
@export()
type TokenReplacement = {
  @description('Token to be replaced')
  token: string
  @description('Replacement value')
  replacement: string
}

@description('String Tokens Replacement Function')
@export()
func stringTokensReplacement(stringValue string, tokenReplacements TokenReplacement[]) string =>
  reduce(tokenReplacements, stringValue, (current, next) => replace(string(current), next.token, next.replacement))

// ** Parameters **
@description('The interval for the Logic App trigger')
param logicAppInterval int = 2

@description('The schedule hour for the Logic App trigger')
param scheduleHour int = 11

@description('The schedule time for condition comparison')
param scheduleTime string = '12:00:00'

@description('The environment for deployment')
param environment string = 'dev'

// ** Variables **
var logicAppConsumptionWorkflow = loadJsonContent('./logicAppConsumptionWorkflow.json')

// Define all token replacements in one place
var tokenReplacements = [
  {
    token: '__interval__'
    replacement: string(logicAppInterval)
  }
  {
    token: '__schedule_hour__'
    replacement: string(scheduleHour)
  }
  {
    token: '__schedule_time__'
    replacement: scheduleTime
  }
]

// Apply all token replacements
var processedWorkflowDefinition = json(stringTokensReplacement(
  string(logicAppConsumptionWorkflow),
  tokenReplacements
))

// ** Resources **
resource logicApp 'Microsoft.Logic/workflows@2023-12-01' = {
  name: 'my-dynamic-logic-app-${environment}'
  location: resourceGroup().location
  properties: {
    definition: processedWorkflowDefinition.definition
    parameters: processedWorkflowDefinition.parameters
  }
}

Key Benefits:

• Environment-specific values: Different intervals for dev/test/prod
• Centralized configuration: All replacements defined in one place
• Scalable: Easy to add new tokens as requirements grow
• Version control friendly: JSON templates remain clean and readable

Summary

Transforming static configuration into dynamic, reusable patterns is essential for maintainable Infrastructure as Code. Use the union() function when combining common configuration with resource-specific properties (like tags), and token replacement for complex JSON configurations that need dynamic values injected. Both approaches centralize configuration management, reduce duplication, and make your Bicep templates more maintainable across environments. The next time you find yourself copy-pasting configuration, choose the right pattern and eliminate that technical debt!

In late May this year, an exciting but semi overlooked feature was released, and I absolutely love it - Typed Variables!

Prior to this release, variable types were inferred through the value, which is fine for most statically defined content within a template, but there are cases that I will go through in this post where typing your variables really does make a big difference.

Why Use Typed Variables

Before I get going, let me walk through why you should consider using typed variables:

1. Fail-Fast Error Detection: Typed variables enable the Bicep compiler to validate assigned values against declared types during authoring and compilation. This helps catch mistakes early, reducing deployment failures.
2. Clearer Intent: Declaring types communicates your intent directly in the code, making it obvious how each variable should be used and what kind of data it should hold.
3. Enhanced IntelliSense Support: Editors like Visual Studio Code offer richer autocompletion and validation for typed variables, speeding up development and reducing errors.
4. Safer Refactoring: When you change variable values or types, the compiler immediately flags mismatches, making refactoring safer and more predictable.

Setup

Defining a typed variable is as simple as the following:

var <variable-name> <data-type> = <variable-value>

⚠️ Note: Requires Bicep version 0.36.X or later.

Typed variables support both the standard set of base data types - string, int, bool, object, array - or for the more advanced, User-defined data types and Resource-derived types.

My Top Two Use Cases

1. Clear Intent

The first major use case for typed variables is improving code clarity and maintainability, especially when working with functions that return complex objects. Without type declarations, it can be difficult to understand what a function returns or how to properly use the resulting variable.

Consider this example with a custom function:

Un-Typed Variable

// ** Functions **
// ***************

func myFunction(param1 string, param2 int) object => {
  property1: param1
  property2: param2
}

// ** Variables **
// ***************

// Un-typed - No IntelliSense on variable use or expectation of variable type.
var variable = myFunction('example', 42)

In this un-typed scenario, several issues arise:

• Unclear return type: The function returns a generic object, making it unclear what properties are available
• No IntelliSense support: When using variable., your editor can’t help you with autocompletion
• Hidden intent: Other developers (or future you) must examine the function implementation to understand what it returns
• Error-prone usage: Typos in property names won’t be caught until deployment time

Now let’s see how typed variables solve these problems:

Typed Variable

// User Defined-Types
// *********************

@sealed()
@description('Defines the structure for myFunction output.')
type myFunctionOutputType = {
  @description('The first property of the output.')
  property1: string
  @description('The second property of the output.')
  property2: int
}

// ** Functions **
// ***************

func myFunction(param1 string, param2 int) myFunctionOutputType => {
  property1: param1
  property2: param2
}

// ** Variables **
// ***************

// Typed - Includes IntelliSense, code clarity, and refactor safety on variable use.
var typedVariable myFunctionOutputType = myFunction('example', 42)

The typed approach delivers immediate improvements:

• Crystal clear intent: The type definition explicitly documents what the function returns and what each property represents
• Enhanced developer experience: Full IntelliSense support when working with the variable, including property names and descriptions
• Compile-time safety: Any mismatch between the function’s actual return value and the declared type will be caught during authoring and compilation
• Better maintainability: Changes to the function’s return structure must be reflected in the type definition, ensuring consistency across the codebase
• Team collaboration: New team members can quickly understand the data structure without diving into function implementations

This pattern is especially valuable in larger Bicep templates where functions might be defined in one section and used much later in the file, or using imported functions as discussed earlier in the series.

2. File functions

One of the most powerful applications of typed variables is when working with Bicep’s file functions such as loadJsonContent() and loadYamlContent(). Without typed variables, these functions return as an Any object, providing no compile-time validation for the loaded content.

Let’s look at a practical example where we’re loading configuration data from an external JSON file:

JSON config file

{
	"sku": {
		"name": "Standard",
		"tier": "Standard"
	},
	"kind": "StorageV2",
	"properties": {
		"supportsHttpsTrafficOnly": true
	}
}

Un-Typed Variable

// ** Variables **
// ***************

var resourceConfig = loadJsonContent('./Config/resource.config.json')

With the un-typed approach above, resourceConfig is treated as a generic object. This means:

• No compile-time validation of the JSON structure
• No documentation about what the configuration should contain

Now let’s see how typed variables transform this experience:

// User Defined-Types
// *********************

@sealed()
@description('Defines the structure for importing a JSON File resource with SKU, kind, and properties.')
type resourceImportType = {
  @description('The SKU details for the resource.')
  sku: {
    @description('The name of the SKU.')
    name: string
    @description('The tier of the SKU (e.g., Standard, Premium).')
    tier: string
  }
  @description('The kind of the resource.')
  kind: string
  @description('The properties of the resource.')
  properties: {
    @description('Indicates whether only HTTPS traffic is supported.')
    supportsHttpsTrafficOnly: bool
  }
}

// ** Variables **
// ***************

var typedResourceConfig resourceImportType = loadJsonContent('./Config/resource.config.json')

With the typed variable approach, we gain several significant benefits:

• Compile-time validation: If the JSON file doesn’t match the defined structure, Bicep will catch this during authoring and compilation
• Rich IntelliSense: When you type typedResourceConfig., your editor will show you the available properties with their descriptions
• Self-documenting code: The type definition serves as living documentation of the expected configuration structure
• Refactoring safety: If you change the type definition, all usages will be validated automatically

This approach is particularly valuable when working with complex configuration files or when multiple team members need to understand the expected data structure.

Summary

Typed variables are a game changer for Bicep development, offering compile-time validation, enhanced IntelliSense, and self-documenting code that makes your templates more robust and maintainable. Make sure to give them a try, and happy Bicep-ing!

In Bicep templates, we sometimes encounter scenarios where certain parameters should be mandatory based on the value of another parameter. For example, when deploying to production environments, you might require additional configuration parameters that are optional for development environments.

One of the common ways in which I have seen this handled is through documentation, which can lead to deployment failures and inconsistent configurations across environments. This post explores how to implement fail-fast validation using Bicep’s built-in capabilities to enforce these conditional requirements at deployment time.

Example of a Documentation-Only Approach

Handling conditional parameter requirements through documentation alone:

@description('Environment to deploy to')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string

@description('Resource configuration - REQUIRED for prod environment!')
param resourceConfig string = ''

// Additional parameters that should be required in prod
@description('Monitoring configuration - REQUIRED for prod environment!')
param monitoringConfig object = {}

@description('Backup configuration - REQUIRED for prod environment!')
param backupRetentionDays int = 0

Problems with this approach:

• No enforcement at deployment time
• Deployments can succeed with missing critical configuration
• Relies on human memory and documentation
• Inconsistent environments due to missing parameters
• Production issues from misconfiguration

Recommended Approach: Fail-Fast Validation

I would recommend using the Bicep fail() function combined with conditional logic to validate parameters early in the deployment process. This approach provides immediate feedback and prevents deployments with invalid configurations, such as in the following examples:

• Production environments - Storage deployments requiring backup retention settings for production
• Key Vault requiring network access rules when public access is disabled

@description('Environment to deploy to')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string

@description('''Resource Configuration:
                - **Optional** When environment is dev / test.
                - **Required** When environment is prod.''')
param resourceConfig string = ''

@description('Resource Configuration Validation Result')
var resourceConfig_Result = environment == 'prod' && empty(resourceConfig)
  ? fail('resourceConfig is required to deploy this template in the prod Environment.')
  : {
      value: resourceConfig
      valueProvided: !empty(resourceConfig)
    }

⚠️ Note: Make deployment failures informative and actionable, helping your team understand exactly what’s needed to fix the issue.

Why this approach is useful

• Enforces deployment rules: Prevents deployment in “prod” if critical configuration is missing, ensuring required configuration is provided before any resources are created.
• Fail-fast validation: Catches configuration errors at the start of deployment, saving time and preventing partial deployments.
• Conditional resource creation: You can use the valueProvided property to conditionally deploy resources or set properties only when configuration is supplied.
• Parameter validation: Centralizes validation logic, making it easier to maintain and extend checks for other environments or parameters in the future.
• Compliance requirements: Ensures production environments always meet security and operational standards.

Summary

Conditional mandatory parameters in Bicep templates are a powerful way to enforce deployment standards and prevent configuration errors. Remember to make deployment failures informative and actionable, helping your team understand exactly what’s needed to fix the issue. Hope this helps, and happy Bicep-ing!

This week is a simple one, but works wonders in maintainability and consistency.

There are often cases where you will need to define static values that don’t change frequently, if at all, and more importantly, you seem to be setting these up frequently for multiple templates. Here are some examples that I have seen:

1. Multi-Environment Deployments

   Different environments (dev, staging, prod) that share common configuration but need environment-specific values:

   var environmentConfig = {
     dev: {
       sku: 'Basic'
     }
     staging: {
       sku: 'Standard'
     }
     prod: {
       sku: 'Premium'
     }
   }
   

2. Organisational Standards

   When you need to enforce company-wide conventions and policies.

   var mandatoryTags = {
     costCenter: 'IT-001'
     dataClassification: 'internal'
     businessUnit: 'engineering'
     version: deployment().properties.template.contentVersion
   }
   

3. Object or Resource Configurations

   When you have configurations that would be repeated across multiple templates.

   var subnetConfigurations = [
     {
       name: 'web-subnet'
       addressPrefix: '10.0.1.0/24'
       serviceEndpoints: ['Microsoft.Storage', 'Microsoft.KeyVault']
     }
     {
       name: 'api-subnet'
       addressPrefix: '10.0.2.0/24'
       serviceEndpoints: ['Microsoft.Sql', 'Microsoft.KeyVault']
     }
   ]
   
   // OR
   
   var keyVaultSecretsUserRoleDefId = '4633458b-17de-408a-b874-0445c86b69e6'
   

You might think, “Hey, the values don’t change very often, so what’s the big deal? So what if I set them up many times across my templates?” Not to be a pessimist, but it’s usually at this point that Murphy’s Law comes into effect and the values will need to change! Would you not rather there be a single point where you can update these values and they ripple through your templates like a stone hitting water?

Well, you can. Simply put, Shared Variables.

Recommended Approach

My recommended approach is to leverage Bicep Imports. Create a Common folder within your IaC directory, and then a variables.bicep file within:

IaC
  ↳ Common
    ↳ variables.bicep
  ↳ main.bicep

This will form the basis of your shared variables that can be used across your deployment templates.

Then find all the relevant candidates and move these across to the shared variables template. Include the @export() decorator to each variable; this is used to allow the variable to be imported into other Bicep files.

For Example

/**********************************
  Bicep Template: Shared Variables
  Author: Andrew Wilson
***********************************/

@export()
@description('Shared Variable for environment configurations')
var environmentConfig = {
  dev: {
    sku: 'Basic'
  }
  staging: {
    sku: 'Standard'
  }
  prod: {
    sku: 'Premium'
  }
}

@export()
@description('Shared Variable for tagging resources')
var mandatoryTags = {
  costCenter: 'IT-001'
  dataClassification: 'internal'
  businessUnit: 'engineering'
  version: deployment().properties.template.contentVersion
}

@export()
@description('Shared Variable for resource configuration')
var subnetConfigurations = [
  {
    name: 'web-subnet'
    addressPrefix: '10.0.1.0/24'
    serviceEndpoints: ['Microsoft.Storage', 'Microsoft.KeyVault']
  }
  {
    name: 'api-subnet'
    addressPrefix: '10.0.2.0/24'
    serviceEndpoints: ['Microsoft.Sql', 'Microsoft.KeyVault']
  }
]

@export()
@description('Shared Variable for Key Vault Secrets User Role Definition ID')
var keyVaultSecretsUserRoleDefId = '4633458b-17de-408a-b874-0445c86b69e6'

These can then be used in your deployment templates as follows:

/***************************************
Bicep Template: Main Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { keyVaultSecretsUserRoleDefId } from './Common/variables.bicep'

// ** Parameters **
// ****************

...

// ** Variables **
// ***************

...

// ** Resources **
// ***************

resource roleassignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(logicAppName, keyVaultSecretsUserRoleDefId)
  properties: {
    roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', keyVaultSecretsUserRoleDefId)
    ...
  }
}

Best Practices for Using Shared Variables

1. Keep it Simple: Only share variables that are common and stable.
2. Tight Control: Treat shared variables as critical infrastructure code.
3. Documentation: Clearly document and describe what each variable represents or is used for.
4. Selective Imports: Don’t import everything with *; be selective about what needs to be imported into deployment templates.

When NOT to Use Shared Variables

• For values that change frequently or are deployment-specific
• For simple, one-off configurations
• For sensitive values (use parameters or Key Vault references instead)

Summary

Shared variables help eliminate duplication and improve consistency across your Bicep templates. This simple approach gives you a single point of truth for common configurations, making updates easier and reducing the risk of inconsistencies across environments. Hope this helps, and happy Bicep-ing!

One of my bugbears is seeing either a complete lack of naming conventions or manual naming mechanisms that introduce human error through mistakes and misunderstandings. Naming conventions are incredibly important, but equally critical is how they’re implemented and maintained. Let’s explore a better approach.

What is a Naming Convention and Why Do We Need One?

A naming convention is a set of rules for naming Resource Groups and Resources (among other Azure components). These rules define the structure and composition of names, ensuring clarity, consistency, and compliance with Azure naming requirements such as length limits, valid characters, and scope uniqueness.

Common components that make up resource names include:

• Location
• Environment
• Project Prefix
• Resource Abbreviation

Naming conventions aren’t one-size-fits-all and require tailoring to your specific needs. Any changes should be considered across all systems to maintain a single source of truth. Well-defined naming conventions significantly improve the readability and maintainability of your Azure estate, aligning with best practices outlined in the Cloud Adoption Framework.

Example convention: {Resource Type}-{Project}-{Environment}-{Location}
Result: LogicAppName: logic-btt-dev-ukwest

Anti-patterns to Avoid

Hard-coded resource names:

name: 'MyLogicApp'

Issues: Poor maintainability, readability, consistency, and convention adherence

Hard-coded naming variables:

var lgName = 'MyLogicApp'

Issues: Poor maintainability across templates, inconsistency, and no convention

Hard-coded naming convention:

var lgName = 'logic-${project}-${environment}-${location}'

Issues: Poor maintainability across templates, template inconsistency, and scattered convention logic

Recommended Approach

My recommended approach leverages User-defined functions to provide consistent and maintainable naming conventions. Combined with Bicep Imports, this ensures consistency across all templates.

For enhanced maintainability, I also recommend implementing centralized core parameters with types and constructors. This approach significantly reduces the number of function parameters needed for each naming operation.

Implementation Structure

Create a Common folder within your IaC directory:

IaC
  ↳ Common
    ↳ types.bicep
    ↳ nameConventionFunctions.bicep
  ↳ main.bicep

• types.bicep - Contains core parameter user-defined types and constructor functions
• nameConventionFunctions.bicep - Contains naming convention functions

Core Types Setup

/**********************************
  Bicep Template: Shared Types
  Author: Andrew Wilson
***********************************/

// ** User Defined Types and Constructors **
// *****************************************

// TYPE: Core Parameters
// *********************

@export()
@description('Core Parameters Definition for Bicep Templates')
@sealed()
type coreParams = {
  @description('Location to deploy resources to')
  location: string
  @description('Location Short Name for resource naming')
  locationShortName: string
  @description('Environment to deploy to')
  environment: string
  @description('Project Prefix for resource naming')
  projectPrefix: string
}

@export()
@description('Core Parameters Constructor')
func newCoreParams(
  location string,
  locationShortName string,
  environment string,
  projectPrefix string
) coreParams => {
  location: location
  locationShortName: locationShortName
  environment: environment
  projectPrefix: projectPrefix
}

Naming Convention Functions

I’ve structured my naming conventions using these key parameters:

• Resource Abbreviation - Identifies the resource type (Azure abbreviations reference)
• Project Prefix - Identifies the project
• Environment - Identifies the deployment environment
• Location - Identifies the deployment location (optional for global resources)
• Context - Describes the resource’s purpose (optional)

The following functions cover some common naming scenarios:

/*******************************************
  Bicep Template: Name Constructor Functions
  Author: Andrew Wilson
*******************************************/

// ** Shared Imports **
// ********************

import { coreParams } from './types.bicep'

// Resource Name Constructors
//***************************

// Basic
@export()
@description('Generates a resource name based on the provided parameters (used for common usage resources)')
func basicResource(resourceAbbreviation string, coreParameters coreParams) string =>
  '${resourceAbbreviation}-${coreParameters.projectPrefix}-${coreParameters.environment}-${coreParameters.location}'

@export()
@description('Generates a resource name based on the provided parameters but ignoring the location (used for common usage resources that are not location specific)')
func unlocalisedBasicResource(resourceAbbreviation string, coreParameters coreParams) string =>
  '${resourceAbbreviation}-${coreParameters.projectPrefix}-${coreParameters.environment}'

// Context Specific
@export()
@description('Generates a Context Specific Resource Name based on the provided parameters')
func csResource(resourceAbbreviation string, coreParameters coreParams, contextName string) string =>
  '${resourceAbbreviation}-${coreParameters.projectPrefix}-${contextName}-${coreParameters.environment}-${coreParameters.location}'

// Resource Group
@export()
@description('Generates a Resource Group name based on the provided parameters')
func resourceGroup(contextName string, coreParameters coreParams) string =>
  'rg-${coreParameters.projectPrefix}-${contextName}-${coreParameters.environment}-${coreParameters.location}'

@export()
@description('Generates a Resource Group name based on the provided parameters but without an env specified')
func resourceGroupNonEnvSpecific(contextName string, coreParameters coreParams) string =>
  'rg-${coreParameters.projectPrefix}-${contextName}-${coreParameters.location}-shared'

// Storage Account
@export()
@description('Generates a Storage Account Resource Name based on the provided parameters')
func storageAccountResource(coreParameters coreParams, contextName string?) string =>
  empty(contextName)
    ? 'st${coreParameters.projectPrefix}${coreParameters.environment}${coreParameters.locationShortName}'
    : 'st${coreParameters.projectPrefix}${contextName}${coreParameters.environment}${coreParameters.locationShortName}'

Usage Example

Here’s how to use these functions in your main deployment template:

/***************************************
Bicep Template: Main Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { newCoreParams } from './Common/types.bicep'
import * as newName from './Common/nameConventionFunctions.bicep'

// ** Parameters **
// ****************

@description('Location to deploy resources to')
param location string

@description('Location Short Name for resource naming')
param locationShortName string

@description('Environment to deploy to')
param environment string = 'dev'

@description('Project Prefix for resource naming')
param projectPrefix string = 'myproject'

// ** Variables **
// ***************

var coreParameters = newCoreParams(location, locationShortName, environment, projectPrefix)

// Standard Logic App Resource Names
var logicAppName = newName.basicResource('logic', coreParameters)
var appServicePlanName = newName.csResource('asp', coreParameters, 'lg')
var storageAccountName = newName.storageAccountResource(coreParameters, 'lg')

// ** Resources **
// ***************

...

Generated Names:

• Logic App: logic-myproject-dev-ukwest
• App Service Plan: asp-myproject-lg-dev-ukwest
• Storage Account: stmyprojectlgdevukw

Summary

Implementing a robust naming convention is crucial for Azure resource management, but the mechanism matters just as much as the convention itself. By using Bicep user-defined functions combined with centralized core parameters, you can:

• Eliminate human error from manual naming processes
• Ensure consistency across all templates and environments
• Improve maintainability with centralized naming logic
• Enhance readability of your Infrastructure as Code
• Align with best practices from the Cloud Adoption Framework

This approach transforms naming from a scattered, error-prone process into a centralized, reliable system that scales with your infrastructure needs. The initial setup investment pays dividends in reduced maintenance overhead and improved deployment reliability. Happy Bicep-ing!

When building IaC templates we strive to enable them to be environment agnostic, configurable even. One of the mechanisms that we do this is through lots of “Core Parameters” that disseminate the fundamental details of our deployment and resources. The number of core parameters is often variable but the verdict is always true, three or more usually does the trick. These Core Parameters are passed into the main deployment template and any other sub deployment template (Module) too. These may include but are not limited to:

• Environment
• Location/Region
• Project/Application Prefix

But why am I going on about this, why is it a problem. Well it’s not a problem as much as it’s a readability and maintainability issue. Think about it, every template now requires three or more core parameters defined, with every module call having to define them as parameters to be passed in. Following this, if there is a change, the change will need to occur everywhere, and let’s hope that the descriptions/metadata has been kept up to date too!

My recommendation to resolve this issue involves three Bicep concepts:

1. User-defined data types
2. User-defined functions
3. Imports

Recommendation broken down

1. Define our source of truth Core Parameters | User-defined data type

User-defined data types provide us a way to define our own data object containing all the core parameters that we use throughout such as the following:

// Bicep

@description('Core Parameters Definition for Bicep Templates')
@sealed()
type coreParams = {
  @description('Location to deploy resources to')
  location: string
  @description('Environment to deploy to')
  environment: string
  @description('Project Prefix for resource naming')
  projectPrefix: string
}

The decorator @sealed() means that you are only permitting the use of properties specifically included in the type definition. This helps with making sure there is only one single source of truth for the coreParams definition.

The type definition means that we can pass through a single parameter to our deployment templates, and manage change in a single place.

2. Create a Constructor to setup our Core Parameters | User-defined function

To aid in the initialization of the coreParams type, I typically create a user-defined function (Constructor) which sets up the initial state by assigning values to the respective properties. This ensures the Core Params object starts in a valid, predictable state. The function would look like this:

// Bicep

@description('Core Parameters Constructor')
func newCoreParams(
  location string,
  environment string,
  projectPrefix string
) coreParams => {
  location: location
  environment: environment
  projectPrefix: projectPrefix
}

3. Promote Shared Use of the Type and Constructor | Imports

The user defined type and function alone would not make this an effective recommendation due to the duplication of both the type and function definition on all templates. However, due to the recent introduction of exports and imports, we can continue on the path of a single and reusable single source of truth.

To make this work, what I would suggest is to create a new folder in your IaC location called Common, in this folder create a new bicep file called types.bicep. This is the shared bicep file that we are going to use for our new type and constructor.

An example of this setup is as follows:

• IaC → Common → types.bicep

Shared Types Template

// Bicep

/**********************************
  Bicep Template: Shared Types
  Author: Andrew Wilson
***********************************/

// ** User Defined Types and Constructors **
// *****************************************

// TYPE: Core Parameters
// *********************

@export()
@description('Core Parameters Definition for Bicep Templates')
@sealed()
type coreParams = {
  @description('Location to deploy resources to')
  location: string
  @description('Environment to deploy to')
  environment: string
  @description('Project Prefix for resource naming')
  projectPrefix: string
}

@export()
@description('Core Parameters Constructor')
func newCoreParams(
  location string,
  environment string,
  projectPrefix string
) coreParams => {
  location: location
  environment: environment
  projectPrefix: projectPrefix
}

The @export() decorator is used to allow the type and function to be imported into other Bicep files.

Now we can use the import syntax in our main and sub deployment (module) templates, allowing use of the single defined type and function. In the main template we import the constructor and assign the initialized object to our coreParameters variable. For our sub deployment (module) templates we import the coreParams type so we can use it as a parameter definition. Both combined allow simplified module reference definitions and assignments. This can be seen in the following example templates:

Main Deployment Template

// Bicep

/***************************************
Bicep Template: Main Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { newCoreParams } from './Common/types.bicep'

// ** Parameters **
// ****************

@description('Location to deploy resources to')
param location string = resourceGroup().location

@description('Environment to deploy to')
param environment string = 'dev'

@description('Project Prefix for resource naming')
param projectPrefix string = 'myProject'

// ** Variables **
// ***************

var coreParameters = newCoreParams(location, environment, projectPrefix)

// ** Resources **
// ***************

@description('Demonstration of the core parameters being passed to a submodule')
module subDeploy './subDeploy.bicep' = {
  name: 'subDeploy'
  params: {
    coreParameters: coreParameters
  }
}

Sub Deployment (Module) Template

// Bicep

/***************************************
Bicep Template: Resources Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { coreParams } from './Common/types.bicep'

// ** Parameters **
// ****************

@description('Core Parameters for the deployment')
param coreParameters coreParams

// ** Variables **
// ****************

@description('The name of the resource to deploy')
var resourceName = '${coreParameters.projectPrefix}-${coreParameters.environment}-resource'

Summary

Managing core parameters in Bicep templates can quickly become unwieldy as your infrastructure grows. By leveraging user-defined types, constructors, and imports, you can centralize your parameter definitions, improve readability, and simplify maintenance. This approach ensures consistency across your deployments and makes future changes easier to manage. Happy Bicep-ing!

For those who know me well, starting a bicep tips and tricks series would not be a surprise to them. The moment the Bicep language was introduced, I knew I would be completely obsessed. I love writing bicep templates and even more the clever refinement to make them reusable, configurable, manageable, readable… I really enjoy sharing my experiences with Bicep, so here it begins on the wider front. From one Bicep nerd to another, I hope you find these tips useful, happy templating!

Why is versioning important

Versioning is a fundamental practice in software development that helps us manage change effectively. It provides a structured way to track and communicate updates, ensuring clarity and consistency throughout the development lifecycle.

• Why apply a version to your templates?

  Applying versioning to templates ensures you can track changes, maintain consistency, and know exactly which version of your infrastructure code was used for any deployment. It supports best practices like binary promotion, simplifies troubleshooting, and helps teams coordinate updates and rollbacks with confidence.

• Why apply the version as a tag to Azure Resources?

  Tagging Azure resources with the template version gives you direct visibility into what was deployed, right from the Azure portal or API. This makes audits, governance, and troubleshooting much easier, as you can instantly see which template version created or updated a resource. It also helps correlate infrastructure changes with application releases and supports compliance requirements for traceability.

ARM templates have a Json property right at the top of the file underneath $schema called contentVersion. By default and if never changed, this will always be 1.0.0.0. As part of our versioning practice we can make sure that the templates that we deploy make use of the same version that is applied to other built artifacts. This allows us to track deployments and their respective templates through versions.

How to version templates using Azure DevOps

As part of a YAML CI/CD pipeline I typically have a build stage, with a inner Test and Version ARM Templates Job. The focus of the job is to do two things:

1. Using the az cli - Build the Bicep templates
   • I also include the Bicep linting file, this means that as the templates are being transpiled into ARM I am also getting any build errors and warnings. I output these as logissues to the Azure DevOps Pipeline for visibility.
2. Version the built ARM JSON artifacts to support Binary promotion and align with versioning practices.

I use the following tasks to complete the tasks:

1. AzureCLI@2 - used to build the Bicep templates (transpile into ARM) and log any warnings or errors.
2. VersionJSONFile@3 - used to version stamp the ARM templates.
3. CopyFiles@2 - Used to copy the versioned ARM artifacts to the staging directory.
4. PublishPipelineArtifact@1 - used to publish the ARM artifacts to the pipeline so they can be downloaded in future deployment stages.

Here is a sample YAML template:

# Yaml

...

- task: AzureCLI@2
  displayName: 'Build Bicep Files'
  inputs:
    azureSubscription: 'xxyyzz'
    scriptType: 'ps'
    scriptLocation: 'inlineScript'
    useGlobalConfig: true
    powershellerrorActionPreference: 'continue'
    inlineScript: |
      # create folder if it doesn't exist
      if (!(Test-Path -Path $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput)) {
        New-Item -ItemType Directory -Path $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput
      }
      write-host "Build the Bicep file"
      $output = az bicep build --file $(Build.SourcesDirectory)\{YourPath}\IAC\template.azuredeploy.bicep --outdir $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput 2>&1
  
      write-host "Process the output"
      $output | foreach-object {
         if ($_ -match 'Error') {
            Write-Host "##vso[task.logissue type=error]$_"
         } 
         if ($_ -match 'Warning') {
             Write-Host "##vso[task.logissue type=warning]$_"
         }
      }

- task: VersionJSONFile@3
  displayName: 'Version stamp ARM templates'
  inputs:
    Path: '$(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput'
    recursion: True
    VersionNumber: $(Build.BuildNumber) # an example versioning option but can also be options like gitversion
    useBuildNumberDirectly: False
    VersionRegex: \d+\.\d+\.\d+\.\d+
    versionForJSONFileFormat: '{1}.{2}.{3}.{4}'
    FilenamePattern: '\w+.json'
    Field: 'contentVersion' # Versioning is applied to the templates contentVersion field
    OutputVersion: OutputedVersion

- task: CopyFiles@2
  displayName: 'Copy ARMOutput to Artifact Staging Directory'
  inputs:
    SourceFolder: '$(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput'
    Contents: '**/*.json'
    TargetFolder: '$(Build.ArtifactStagingDirectory)/templates'
    flattenFolders: true

- task: PublishPipelineArtifact@1
  displayName: 'Publish ARMOutput as template build artifact'
  inputs:
    targetPath: '$(Build.ArtifactStagingDirectory)/templates'
    publishLocation: 'pipeline'
    artifactName: 'ARMtemplates'

This setup ensures your ARM templates are built, versioned, and published as pipeline artifacts in a repeatable, traceable way. By stamping each template with a version number and making it available as an artifact, you enable binary promotion through environments and make it easy to track exactly which template version was used for each deployment. This improves auditability, supports rollback scenarios, and aligns with best practices for infrastructure as code in CI/CD pipelines.

How to apply the template version as a tag to Azure Resources

Versioning our ARM templates is one part of the transparency and traceability. But it would also be nice to be able to see which template version deployed the Azure Resources from the Azure Resources themselves. We can do this by applying a tag onto our resources and tying it back to our ARM contentVersion property field. We can do this by using the deployment() function as such deployment().properties.template.contentVersion.

On a resource it would look like the following:

// Bicep

resource AppService 'Microsoft.Web/sites@2024-11-01' = {
  name: appServiceName
  location: location
  tags: {
	...
    version: deployment().properties.template.contentVersion
  }
  ...
}

Applying template versioning and tagging resources with the deployed template’s version brings transparency and traceability to your Azure infrastructure. You’ll always know which version of your code and templates are running in each environment, making troubleshooting and governance much easier. These small practices help teams stay organised, reduce deployment risks, and build confidence in their automation. Happy Bicep-ing!

Modernising legacy applications is always a journey, and recently I tackled moving an existing WCF web service into Azure App Service. If you’ve worked with WCF, you’ll know the web.config file is the nerve centre, handling everything from parameters to connection strings.

But here’s the catch, this service needs to run in multiple environments (Development, Test, and Production) each with its own unique settings. That means multiple config files:

• Web.Dev.Config
• Web.Test.Config
• Web.Production.Config

The challenge

I didn’t want to build and maintain three separate web packages, one for each environment. That’s a recipe for drift and deployment headaches. Instead, I wanted a single build artifact that could be promoted through environments, swapping out only the environment-specific config as needed.

Enter web.config transformations. With these, you can:

• Keep a base web.config
• Layer on environment-specific transforms (Web.Dev.Config, etc.)

But when should the transformation happen? There are two main options, each with its own pros and cons:

1. At build time (using MSBuild):

   • The transformation is applied as part of the build process, so the output artifact already contains the environment-specific configuration.
   • This approach is simple if you only ever deploy to one environment per build, but it means you need to build a separate artifact for each environment. This breaks the principle of binary promotion, where the same artifact is promoted through Dev, Test, and Production. It also increases the risk of inconsistencies between builds.

2. At deployment (using the AzureRMWebAppDeployment@4 Azure DevOps Task):

   • The transformation is applied as part of the deployment process, allowing you to use a single, environment-agnostic build artifact and inject the correct configuration at deploy time.
   • This is the preferred approach for most modern pipelines, as it enables true binary promotion, reduces build times, and ensures that what you test is exactly what you deploy to production. It also aligns with best practices for repeatable, reliable deployments.

Solution: deploy-time transforms

Here’s how I set it up:

Build pipeline

# YAML
...

stages:
- stage: 'Build_Packages'
  jobs:
    - job: 'Build_WCFService'
      steps:

        - checkout: self
          fetchDepth: 0

        - task: VSBuild@1
          displayName: 'Build the WCF Service Solution'
          inputs:
            solution: '$(Build.SourcesDirectory)\*.sln'
            msbuildArgs: '/p:OutputPath=$(Build.ArtifactStagingDirectory)\WCFService /p:IsTransformWebConfigDisabled=true'
            platform: 'any cpu'
            vsVersion: 'latest'
            configuration: 'Release'
            clean: true

        - task: ArchiveFiles@2
          displayName: 'Archive WCF Service Build Output'
          inputs:
            rootFolderOrFile: '$(Build.ArtifactStagingDirectory)\WCFService\_PublishedWebsites\WCFService.Web'
            includeRootFolder: false
            archiveType: 'zip'
            archiveFile: '$(Build.ArtifactStagingDirectory)\WCFService\WCFService.zip'
            replaceExistingArchive: true

        - task: PublishPipelineArtifact@1
          displayName: 'Publish WCF Service Build Artifact'
          inputs:
            targetPath: '$(Build.ArtifactStagingDirectory)\WCFService\WCFService.zip'
            publishLocation: 'pipeline'
            artifactName: 'WCFService'

Release pipeline

Each environment (Dev, Test, Production) will get its own stage. The key is to ensure the correct environment name is set so the right transform is applied.

# YAML
...
- stage: 'Dev'
  displayName: 'Deploy to Dev Environment'
  variables:
  - group: 'Dev'
  dependsOn: 'Build_Packages'
  condition: succeeded()
  jobs:
    - deployment: Deploy_to_Dev
      environment: WCFServiceDev
      strategy:
        runOnce:
          deploy:
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                parameters:
                  ARMConn: 'Dev'

- stage: 'Test'
  displayName: 'Deploy to Test Environment'
  variables:
  - group: 'Test'
  dependsOn: 'Dev'
  condition: succeeded()
  jobs:
    - deployment: Deploy_to_Test
      environment: WCFServiceTest
      strategy:
        runOnce:
          deploy:
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                parameters:
                  ARMConn: 'Test'

- stage: 'Production'
  displayName: 'Deploy to Production Environment'
  variables:
  - group: 'Prod'
  dependsOn: 'Test'
  condition: succeeded()
  jobs:
    - deployment: Deploy_to_Production
      environment: WCFServiceProd
      strategy:
        runOnce:
          deploy:
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                parameters:
                  ARMConn: 'Production'

Deployment template

#YAML

steps:

  - download: current
    displayName: 'Download the wcf Service Web package'
    artifact: WCFService

  ...

  - task: AzureRMWebAppDeployment@4
    displayName: 'Deploy WCF Service Web App'
    inputs:
      ConnectionType: 'AzureRM'
      azureSubscription: ${{ parameters.ARMConn }}
      appType: 'webApp'
      WebAppName: '$(armOutput.AppServiceName)'
      Package: '$(Pipeline.Workspace)/WCFService/WCFService.zip'
      enableXmlTransform: true

Here’s the bit that tripped me up: in multi-stage pipelines, the Release.EnvironmentName variable isn’t set by default. Without it, Azure DevOps doesn’t know which transform to apply. The fix? Explicitly set the variable in each stage:

# YAML
- stage: 'Dev'
  displayName: 'Deploy to Dev Environment'
  variables:
  ...
  - name: 'Release.EnvironmentName'
    value: 'Dev'
  ...

- stage: 'Test'
  displayName: 'Deploy to Test Environment'
  variables:
  ...
  - name: 'Release.EnvironmentName'
    value: 'Test'
  ...

- stage: 'Production'
  displayName: 'Deploy to Production Environment'
  variables:
  ...
  - name: 'Release.EnvironmentName'
    value: 'Production'
  ...

Troubleshooting and tips

Common pitfalls:

• Ensure your transform files (e.g., Web.Dev.config) are included in your build artifacts. If they’re missing, check your .csproj or project file to confirm they’re marked as Content and set to Copy to Output Directory if needed.
• File names are case-sensitive on some systems, double-check spelling and casing.
• If transforms aren’t being applied, verify that the Release.EnvironmentName variable is set correctly and matches your transform file naming.

Security note: Avoid storing secrets or sensitive values directly in your config files. Use Azure Key Vault or pipeline secrets for sensitive data, and reference them via environment variables or pipeline variables where possible.

Wrapping up

With this approach, you get a single, reusable build artifact and environment-specific configuration at deployment, no more juggling multiple packages. It’s a small change that makes your pipeline cleaner and your deployments more reliable.

Hope this helps, happy deploying!

Deploying updates to production environments demands both speed and control. Azure App Service deployment slots, combined with Azure DevOps pipelines, offer a powerful way to manage releases, enabling teams to validate changes in a live-like environment before they go public. However, ensuring that only reviewed and approved changes reach your users is critical for maintaining reliability and compliance.

Azure App Service Slots unlock powerful advantages:

• Site Review. Preview and test your site before it goes live, ensuring everything works as expected.
• Warmed-up Instances. Swap with confidence. Your instances are pre-warmed, so there’s no downtime, seamless traffic redirection, and zero dropped requests.
• Instant Rollback. If something goes wrong after a swap, simply swap back to restore your last known good version in seconds.

Best of all, deployment slots come at no extra cost. Check the Azure App Service limits to see how many slots your App Service Tier supports.

Automatic vs. Manual Slot Swaps

When it comes to swapping slots, there are two main approaches: automatic and manual.

• Automatic swaps are ideal when you want to quickly promote changes without a review, while still benefiting from pre-warmed instances and instant rollback.
• Manual swaps give you the opportunity to review and verify your site before it goes live, adding an extra layer of confidence.

But how do you keep a manual swap process governed and controlled? That’s where Azure DevOps pipelines and approvals come in.

In this article, you’ll learn how to set up a robust, approval-driven slot swap process in Azure DevOps.

Defining Azure Resources with Bicep

First, we need to define the resources needed in Azure. To do this I am going to use Infrastructure as Code (IaC). The template shown below creates the following resources:

• App Service Plan.
• App Service linked to the App Service Plan
  • Sub Resource that defines the App Service App Settings
• App Service Deployment Slot. Only created for Production environments - this is enforced through a conditional on the resource

Bicep Template: App Service and Deployment Slot

// Bicep

/**********************************
Bicep Template: App Service Deploy
Author: Andrew Wilson
***********************************/

targetScope = 'resourceGroup'

// ** Parameters **
// ****************

@description('Org Project Name')
param projectName string

@description('Application Name sitting within the project')
param applicationName string

@description('location name')
param location string = resourceGroup().location

@description('Environment name')
param env string = 'dev'

@description('App Service Plan sku name')
param appServicePlanSkuName string

@description('App Service Plan sku tier')
param appServicePlanSkuTier string

@description('Name of the deployment slot')
param deploymentSlotName string = 'staging'

// ** Variables **
// ***************

var appServicePlanName string = 'asp-${applicationName}-${env}-${location}'
var appServiceName string = 'app-${applicationName}-${env}-${location}'

// ** Resources **
// ***************

@description('Deploy an Azure App Service Plan')
resource AppServicePlan 'Microsoft.Web/serverfarms@2024-11-01' = {
  name: appServicePlanName
  location: location
  tags: {
    project: projectName
    application: applicationName
    environment: env
    version: deployment().properties.template.contentVersion
  }
  sku: {
    name: appServicePlanSkuName
    tier: appServicePlanSkuTier
  }
}

@description('Deploy an Azure App Service')
resource AppService 'Microsoft.Web/sites@2024-11-01' = {
  name: appServiceName
  location: location
  tags: {
    project: projectName
    application: applicationName
    environment: env
    version: deployment().properties.template.contentVersion
  }
  properties: {
    serverFarmId: AppServicePlan.id
    httpsOnly: true
  }
  resource AppServiceAppSettings 'config@2024-11-01' = {
    name: 'appsettings'
    properties: {
      ...
    }
  }  
}

@description('Deploy a deployment slot for the App Service')
resource deploymentSlot 'Microsoft.Web/sites/slots@2024-11-01' = if (env == 'prod') {
  name: deploymentSlotName
  parent: AppService
  location: location
  tags: {
    project: projectName
    application: applicationName
    environment: env
    version: deployment().properties.template.contentVersion
  }
  properties: { }
}

// ** Outputs **
// *************

@description('Outputs the App Service Name')
output appServiceName string = appServiceName

Important Note: Avoiding AutoSwap for Manual Swaps

Make sure that the DeploymentSlot resource does not have AutoSwap setup as this will counteract when Manual Swap is used. Such that the following process would be observed:

1. Deploy to Staging slot.
2. AutoSwap kicks in and swaps Staging with Production.
3. After Manual Approval, Slots are swapped again
4. You are now in the originating position with the new site still in Staging and Production with the old.

Designing the Azure DevOps Pipeline

Next we will setup our Azure DevOps Yaml pipeline. The pipeline’s goal is to orchestrate artifact building and environment deployments while adhering to DevOps best practices, such as binary promotion.

Pipeline Stages Explained

The pipeline has the following stages:

1. Build_Packages. Build a single set of artifacts that have been tested and versioned. (Best practice of Binary Promotion)

   The stage has two jobs to handle both Azure Bicep Templates and the App Service Web Package.

2. Development. Deploy to the Development Environment using an environment agnostic pipeline template*.

3. Staging. Deploy to the Staging Environment using an environment agnostic pipeline template*.

4. Production. Deploy to the Production Environment using an environment agnostic pipeline template*.

*The environment agnostic pipeline template is a reusable template for all environments.

Pipeline YAML: Build and Environment Deployments

# Yaml
# Orchestrating Template: Build And Environment Deployments

...

stages:
- stage: 'Build_Packages'
  jobs:
    - job: 'Test_Build_And_Version_Bicep_Templates'
      steps:

        ...

        - task: PublishPipelineArtifact@1
          displayName: 'Publish ARMOutput as template build artifact'
          inputs:
            targetPath: '$(Build.ArtifactStagingDirectory)/templates'
            publishLocation: 'pipeline'
            artifactName: 'ARMtemplates'

    - job: 'Build_and_Version_AppService'
      steps:

		...

        - task: PublishPipelineArtifact@1
          displayName: 'Publish App Service Build Artifact'
          inputs:
            targetPath: '$(Build.ArtifactStagingDirectory)/AppService.zip'
            publishLocation: 'pipeline'
            artifactName: 'AppService'


- stage: 'Development'
  displayName: 'Deploy to Dev Environment'
  ...
  jobs:
    - deployment: Deploy_to_Dev
      ...
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                ...

- stage: 'Staging'
  displayName: 'Deploy to Staging Environment'
  ...
  jobs:
    - deployment: Deploy_to_Staging
      ...
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                ...

- stage: 'Production'
  displayName: 'Deploy to Production Environment'
  ...
  jobs:
    - deployment: Deploy_to_Production
      ...
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                ...

Once the Build_Packages stage has completed successfully, we now have two pipeline artifacts, ARMtemplates and AppService. In each environment deploy these two artifacts will be downloaded and used alongside environment specific Library Variable Groups to create specific environment deployments.

Environment-Agnostic Deployment Template

The environment agnostic template is shown below and has the following steps:

1. Artifact Downloads. Downloads the two pipeline artifacts, ARMtemplates and AppService.
2. Azure Resource Group Deployment. Using the built ARM template, specific environment library variable group and ARM Connection.
3. Custom PowerShell Script to Obtain Azure Deployment Outputs. Deployment output such as appServiceName will be created as job variables ready for future tasks to access.
4. Azure Web App Deploy (Specific for Dev and Staging). This task deploys straight to the production slot for non production environments.
5. Azure Web App Deploy (Specific for Prod). This task deploys to the staging slot ready for a manual slot swap.

Pipeline YAML Template: Reusable Environment-Agnostic Deployments

# Yaml
# Environment Deploy Template: Deploy Azure Resources and Obtain Outputs, Deploy App Service

steps:

  - download: current
    displayName: 'Download ARM templates'
    artifact: ARMtemplates

  - download: current
    displayName: 'Download the App Service Web package'
    artifact: AppService

  - task: AzureResourceManagerTemplateDeployment@3
    displayName: 'Deploy App Service ARM template'
    inputs:
      deploymentScope: 'Resource Group'
      azureResourceManagerConnection: ${{ parameters.ARMConn}}
      subscriptionId: '$(subscriptionId)'
      action: 'Create Or Update Resource Group'
      resourceGroupName: '$(resourceGroupName)'
      location: '$(location)'
      templateLocation: 'Linked artifact'
      csmFile: '$(Pipeline.Workspace)/ARMtemplates/AppService.azuredeploy.json'
      deploymentMode: 'Incremental'
      deploymentOutputs: deploymentOutputs
      overrideParameters: >-
        ...

  - task: PowerShell@2
    name: armOutput
    displayName: 'Obtain Azure Deployment outputs'
    inputs:
      targetType: 'inline'
      script: |
        if (![string]::IsNullOrEmpty( '$(deploymentOutputs)' )) {
          $DeploymentOutputs = convertfrom-json '$(deploymentOutputs)'

          $DeploymentOutputs.PSObject.Properties | ForEach-Object {
              $keyname = $_.Name
              $value = $_.Value.value
              Write-Host "The value of [$keyName] is [$value]"
              Write-Host "##vso[task.setvariable variable=$keyname;isOutput=true]$value"
          }
        }

  - task: AzureWebApp@1
    displayName: 'Deploy App Service - Dev and Staging Environment Only'
    condition: ne(variables['env'], 'prod')
    inputs:
      azureSubscription: ${{ parameters.ARMConn }}
      appType: 'webApp'
      appName: '$(armOutput.appServiceName)'
      package: '$(Pipeline.Workspace)/AppService/AppService.zip'

  - task: AzureWebApp@1
    displayName: 'Deploy App Service to Staging Slot - Prod Environment Only'
    condition: eq(variables['env'], 'prod')
    inputs:
      azureSubscription: ${{ parameters.ARMConn }}
      appType: 'webApp'
      appName: '$(armOutput.appServiceName)'
      deployToSlotOrASE: true
      resourceGroupName: '$(resourceGroupName)'
      slotName: '$(slotName)'
      package: '$(Pipeline.Workspace)/AppService/AppService.zip'

Accessing ARM Output Variables Across Jobs

Given that I will also need to access the appServiceName ARM Output that has been outputted from the armOutput task as a variable in future jobs, I have used the Output Variable for use in future jobs configuration.

Rather than job only:

##vso[task.setvariable variable=$keyname]$value

It uses the IsOutput so we can setup dependencies and access later:

##vso[task.setvariable variable=$keyname;isOutput=true]$value

Note: Accessing a Output Variable is different to a non-output variable:

Non-output Variable: '$(appServiceName)'

Output Variable: '$(armOutput.appServiceName)', you will need to reference the task name prior to the variable.

Manual Slot Swap with Azure DevOps Approvals

At this point, we now have our App Service resources deployed and the Site deployed to the production slots for Dev and Staging, and deployed to the Staging slot for Production.

But now down to the real question, how do I manually swap the slots using some Azure DevOps governance goodness?

To do this we are going to use the Azure DevOps Environment Approvals which will allow specific groups or users to approve the slot swap. Following this we will use the AzureAppServiceManage@0 task to conduct the slot swap.

Setting Up Azure DevOps Environments and Approvals

To setup an environment and approvals:

1. Sign in to your Azure DevOps organisation and open your project.
2. Select Pipelines > Environments > Create Environment.
3. Enter information for the environment, and then select Create. (For our purposes leave Resource as None)
4. In your Environment, Select Approvals and checks tab, and then select the + sign to add a new check.
5. Select Approvals, and then select Next.
6. Add users or groups as your designated Approvers, and if desired the following
   1. Instructions to approvers
   2. Allow approvers to approve their own runs
7. Make sure to Save.

Environments can be assigned to stages and jobs, but not to individual tasks. This means the slot swap task cannot reside within the environment-agnostic deployment template; it must be a separate, follow-on job.

To cater for the slot swap and environment approval, we are going to amend the orchestrating template to add another Job after the deployment Job in the Production deploy stage. This is shown below.

Adding the Slot Swap Job to the Pipeline

# Yaml
# Orchestrating Template: Build And Environment Deployments

...

- stage: 'Production'
  ...
  jobs:
    - deployment: Deploy_to_Production
      ...
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                ...
    
    - deployment: Slot_Swap_to_Production
      dependsOn: Deploy_to_Production
      condition: succeeded()
      environment: ProductionEnv
      variables:
        appServiceName: $[ dependencies.Deploy_to_Production.outputs['Deploy_to_Production.armOutput.appServiceName'] ]
      strategy:
        runOnce:
          deploy:
            steps:
              - task: AzureAppServiceManage@0
                displayName: 'Swap App Service Staging Slot to Production'
                inputs:
                  azureSubscription: 'XXXYYYZZZ'
                  action: 'Swap Slots'
                  WebAppName: '$(appServiceName)'
                  ResourceGroupName: '$(resourceGroupName)'
                  SourceSlot: '$(slotName)'
                  SwapWithProduction: true

As can be seen in the amended template above, the Slot_Swap_to_Production job runs after the Deploy_to_Production job and expects it to have succeeded as a condition to running. The Slot_Swap_to_Production job also references the environment ProductionEnv for Approval prior to running.

Note: The first time the environment is used on the pipeline, the pipeline will ask for permission to use the resource.

Referencing Output Variables in the Slot Swap Job

The Azure App Service Manage task requires the WebAppName, which is set as an output variable in the environment-agnostic YAML pipeline template. To use this value in the Slot_Swap_to_Production job, define a new variable that references the output variable from the previous job. Once defined, you can use it within the current job as a standard variable (e.g., $(appServiceName)).

The variable reference uses the following syntax:

[dependencies.JobName.outputs[’JobName.TaskName.VariableName]]

You now have a pipeline that at the point of the slot swap job will wait for an appropriate approval prior to running and swapping your staging slot to production.

Summary

By combining Azure App Service deployment slots, Infrastructure as Code, and Azure DevOps environment approvals, you can create a robust, auditable deployment pipeline. This approach ensures that production releases are gated by manual approval, reducing risk and enabling rapid rollback if needed.

Ready to take your deployments to the next level? Try setting up manual slot swaps with approvals in your next release pipeline, and let your team experience stress-free, governed production launches.

Microsoft has just introduced something quite revolutionary into the world of integration: Agent Loop, a new capability in Azure Logic Apps that lets you build AI-powered agents directly into your workflows. On the surface, it might seem like another incremental feature. But dig a little deeper, and the implications are huge!

Let’s break it down.

What Is Agent Loop?

Agent Loop is Microsoft’s way of embedding advanced AI decision-making into Logic Apps workflows. Think of it like adding a smart co-pilot into your integration flows, an agent that can retain context, reason over time, and take meaningful actions. It uses an LLM like Azure OpenAI under the hood, paired with a memory store that persists throughout the workflow, allowing the agent to understand, adapt, and make decisions across multiple steps.

This isn’t just a chat feature bolted onto Logic Apps. This is a new integration pattern.

Why This Matters

1. From Orchestrators to Orchestrators-With-Brains

Traditionally, Logic Apps has been a powerful tool for orchestrating workflows, but each step is stateless and reactive. With Agent Loop, Microsoft is blurring the lines between workflow automation and autonomous decision-making. Your integration logic can now evolve based on prior inputs, contextual signals, or even unstructured content.

Imagine an agent that:

• Detects anomalies in data feeds and adjusts routing accordingly
• Analyses unstructured text (emails, tickets, PDFs) and initiates remediation
• Talks to legacy systems, interprets responses, and adapts its logic in real time

This isn’t just modernisation, it’s next-gen augmentation.

2. For BizTalk Migrations, This Changes the Equation

Many of the workflows built in BizTalk were complex not just because of their integration points, but because of the decision logic baked into orchestration layers. Until now, moving those workflows into Azure meant carefully untangling rulesets, mappings, and dependencies.

Agent Loop gives you a new option, wrap legacy logic in an AI reasoning layer, preserve existing behaviour where needed, and inject flexibility where it’s long overdue. That’s a big deal for organisations plotting their BizTalk to Azure Integration Services (AIS) migration.

3. Bridging Structured and Unstructured Worlds

In most enterprises, structured data lives in databases, but the real mess, the emails, PDFs, meeting notes, customer queries, is where value is trapped. Agent Loop lets you embed GPT-style agents that can process unstructured inputs, make sense of them, and act accordingly.

In effect, it bridges the gap between API-driven systems and human language interactions, a holy grail for integration architecture.

What Could This Enable?

Some early scenarios come to mind:

• Intelligent triage: Auto-routing support tickets based on nuanced analysis, not just keywords
• Contract processing: Reading legal documents and extracting obligations for ERP updates
• Integration self-healing: Agents that spot failed API calls and retry or switch endpoints contextually
• Customer 360 augmentation: Combining CRM data with email sentiment to tailor outreach strategies

What’s powerful here is not just the AI, it’s that the AI lives inside your governed, observable, enterprise-ready integration fabric. That’s the kind of maturity architects have been waiting for.

The Bigger Picture

This move by Microsoft is a signal, AI isn’t a separate strategy anymore, it’s becoming part of the plumbing. And for IT leaders, that means a shift in how we think about capability building.

Where before we asked, “What can be automated?”, now we ask, “What can be intelligently automated?” Where we once feared black-box AI, now we can build AI agents that live inside controlled workflows.

A Word of Caution

This is still early days. Agent Loop is in public preview, and like all AI features, there are concerns around predictability, testing, and operational risk. Governance, testing harnesses, and monitoring patterns will also need to be matured alongside adoption.

But make no mistake, this is a foundational shift.

Getting Started

Agent Loop is already available in Logic Apps Standard! Here are some Microsoft resources to help you begin:

• Documentation: Explore the agent loop concepts and detailed guide with step-by-step instructions on how to configure and use Agent Loop.
• Samples & Demos: Watch pre-recorded demos showcasing both conversational and autonomous agent scenarios built with Agent Loop. You’ll also get a preview of exciting features coming soon.

Final Thoughts

If you’re leading a modernisation initiative, working through a BizTalk migration, or trying to unify integration and automation under a future-proof architecture, Agent Loop deserves your attention.

It’s one of those moments where what looks like a feature is actually a new paradigm. The integration space just got a whole lot smarter,and that changes everything.

Further Reading:

Official Announcement – Microsoft Tech Community

With the context of software requirements, I regularly encounter an understood but often ignored scenario: the less detailed the initial requirements, the more expansive the client’s expectations become as the project progresses. It’s a phenomenon I refer to as the Requirements Ambiguity Paradox.

Imagine initiating a project with a brief requirements document, aiming for agility and speed. At first glance, this seems efficient.

However, this brevity often leads to divergent interpretations:

• Developers assume a minimal scope, focusing on core functionalities.
• Clients envision a comprehensive solution, expecting features beyond the initial outline.

This disconnect sets the stage for scope creep, misaligned expectations, and potential project overruns.

The Paradox in Action

Here’s how the paradox typically unfolds:

1. Minimal Requirements: To expedite the project kickoff, the team drafts a concise requirements document.
2. Divergent Assumptions: Stakeholders interpret the brief differently, leading to varying expectations.
3. Feature Requests Multiply: As development progresses, clients request additional features, believing they were implied.
4. Project Strain: The team faces increased workload, extended timelines, and potential budget overruns. This can lead to reduced morale, client dissatisfaction, and even jeopardise the project’s success.

Ironically, the initial attempt to streamline the process results in greater complexity and resource expenditure.

Navigating the Paradox

To mitigate this paradox, consider the following strategies:

• Define a Clear MVP: Establish a well-articulated Minimum Viable Product, outlining core functionalities and deliverables.
• Employ User Stories: Utilise user stories with explicit acceptance criteria to capture requirements comprehensively.
• Implement Agile Contracts: Adopt flexible contracts that accommodate evolving requirements while maintaining scope control.
• Foster Collaborative Requirement Gathering: Engage stakeholders in the requirements gathering process to ensure shared understanding and alignment.

Final Thoughts

The Requirements Ambiguity Paradox serves as a reminder that clarity at the project’s inception is paramount. While brevity may seem efficient, detailed and collaborative requirement documentation often leads to smoother project execution and stakeholder satisfaction.

Tighten up your requirements now, your future self, your team, and your client will thank you.

Versioning is the unsung hero of software development—often overlooked but absolutely essential. Imagine trying to manage a project without a clear way to track changes, communicate updates, or ensure compatibility. Chaos, right? That’s where versioning steps in, providing structure and clarity.

In this post, I’ll share how I streamline versioning in my projects by combining the power of Semantic Versioning (SemVer) with GitVersion, an automation tool that eliminates the manual effort of version management. Whether you’re just beginning your journey or tackling the complexities of feature-rich projects, this post will show you how to automate semantic versioning in Azure DevOps for consistency, traceability, and peace of mind.

Why Version?

Versioning is a fundamental practice in software development that helps us manage change effectively. It provides a structured way to track and communicate updates, ensuring clarity and consistency throughout the development lifecycle.

What is Semantic Versioning?

Semantic Versioning (often abbreviated as SemVer) is a versioning scheme that provides a standardised way to communicate the nature of changes in a software release. It uses a three-part version number format: MAJOR.MINOR.PATCH, where each part conveys specific information about the release.

Breakdown of Semantic Versioning:

1. MAJOR Version: Incremented when there are breaking changes that are incompatible with previous versions.

   • Example: 1.0.0 → 2.0.0

2. MINOR Version: Incremented when new features are added in a backward-compatible manner.

   • Example: 1.0.0 → 1.1.0

3. PATCH Version: Incremented when backward-compatible bug fixes or small improvements are made.

   • Example: 1.0.0 → 1.0.1

Benefits of Semantic Versioning:

• Clarity: It clearly communicates the scope and impact of changes to users and developers.
• Predictability: Helps teams and users understand what to expect from a new release.
• Dependency Management: Makes it easier to specify compatible versions of libraries or APIs.
• Automation: Tools like GitVersion can automate the generation of semantic versions in CI/CD pipelines, ensuring consistency and reducing manual effort.

Versioning with GitVersion

GitVersion is an open source tool that can be used to automate semantic versioning by analysing our Git repository’s history. It streamlines the versioning process, ensuring consistency and reducing manual errors.

GitVersion has the following key features:

• Semantic Versioning (SemVer): Automatically calculates version numbers based on Git history, adhering to SemVer principles.
• Branching Strategy Support: Compatible with Continuous Delivery, GitFlow, GitHub Flow, and Mainline development workflows.
• Continuous Integration (CI) Friendly: Integrates seamlessly with CI/CD pipelines, generating version numbers for builds and releases.
• Flexible Configuration: Highly configurable to suit various project needs and versioning schemes.

GitVersion Configuration

GitVersion uses a configuration file (GitVersion.yml) to define how version numbers are calculated based on your Git repository’s history and branching strategy. This file allows us to customise the behaviour of GitVersion to suit our project’s needs.

How I Branch and Configure GitVersion for Projects

My projects tend to use the following setup:

• Continuous Delivery Branch Model. This model has the following features:
  • Main branch as release-ready: The main branch is always in a deployable state.
  • Frequent Deployments: Changes are deployed to production or staging environments frequently, often automatically.
  • Short-Lived Feature Branches: Feature branches are merged into main after review and testing.
  • Automated Pipelines: CI/CD pipelines handle building, testing, and deploying changes seamlessly.
• SemVer is incremented using the following strategies:
  • TaggedCommit. This strategy uses Git tags to determine the version. If a commit is tagged with a semantic version (e.g., 1.0.0), GitVersion will use that tag as the base for calculating the next version.
  • Fallback. This strategy is used when no other versioning information (e.g., tags or branch-specific rules) is available. It serves as a default versioning mechanism, especially for newly initiated projects.
• Two defined branches for GitVersion increments:

GitConfig Setup

The described GitVersion configuration looks like the following:

## YAML
strategies:
- TaggedCommit
- Fallback
branches:
   main:
      increment: Minor
      prevent-increment:
         when-current-commit-tagged: true
   pull-request:
      increment: Patch
      prevent-increment:
         when-current-commit-tagged: true