Migrate to dynamic types in Bicep template files

There are two options for selecting your Microsoft Graph Bicep types "package":

• Built-in types: The Microsoft Graph Bicep types are built into the Bicep compiler NuGet package. This NuGet package contains Microsoft Graph type definitions for both Microsoft Graph beta and v1.0. Built-in types were the only option available before September.
• Dynamic types: A specific versioned Microsoft Graph Bicep types repo is referenced and fetched from the Microsoft Artifact Registry. These packages are decoupled from the Bicep compiler NuGet package. Dynamic types are only available for use from September.

The dynamic types feature enables semantic versioning for Microsoft Graph Bicep types for both beta and v1.0. Using dynamic types allows for future breaking changes in existing Microsoft Graph Bicep resource types without impacting the deployment of your existing Bicep files that use older versions of those resource types.

All examples and quickstarts in the public documentation and in the GitHub repo use dynamic types.

Prerequisites

• Have an Azure subscription. If you don't have one, you can create a free account.
• Have the least privileged permissions or roles to either read or update the existing resource, or be the owner of the resource. Consult Least privileged roles by task and Default user permissions to see what roles you need to be assigned.
• Install Bicep tools for authoring and deployment. This quickstart uses VS Code with the Bicep extension for authoring and Azure CLI for deployment. The minimum required Bicep version is v0.30.3.
• You can deploy the Bicep files interactively or via zero-touch (app-only) deployment.

Switch to using dynamic types

The following steps show how to update a Bicep file that is currently using built-in types from Microsoft Graph v1.0 only.

1. Launch VS Code and open the folder containing your main.bicep and bicepconfig.json files.

2. In the bicepconfig.json file, add a reference to the Microsoft Graph Bicep resource types in the Microsoft Artifact Registry. To find the latest or appropriate version, visit the Microsoft Artifact Registry and search for "Microsoft Graph Bicep Extension".

3. Open the bicepconfig.json file and add the following block:

   • microsoftGraphV1_0 is a user-defined friendly extension name for referencing the package version in the Microsoft Artifact Registry.
   • Replace <version> with the type version you want to use and that is supported for Microsoft Graph v1.0.

   {  
       "experimentalFeaturesEnabled": {  
           "extensibility": true  
       },
       "extensions": {  
           "microsoftGraphV1_0": "br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:<version>"  
       }  
   }
   

4. In main.bicep, update the extension declaration to use the extension version name you defined in the bicepconfig.json file.

   extension microsoftGraphV1_0
   
   @description('Group to use')
   param groupName string = 'TestGroup-20240816'
   
   // using v1.0
   resource group 'Microsoft.Graph/groups@v1.0' existing = {
       uniqueName: groupName
   }
   
   output groupId string = group.id
   

Use dynamic types for both beta and v1.0 Microsoft Graph resources

The built-in types for Microsoft Graph provides types for both Microsoft Graph beta and v1.0. If your Bicep file declares Microsoft Graph resources from both beta and v1.0, use the following steps to update a Bicep file that is currently using built-in types.

1. Launch VS Code and open the folder containing your main.bicep and bicepconfig.json files.

2. You need to add a reference, in the bicepconfig.json file, to the Microsoft Graph Bicep resources types package in the Microsoft Artifact Registry. To find the latest or appropriate package version, go to the Microsoft Artifact Registry and search for "Microsoft Graph Bicep Extension".

3. Open the bicepconfig.json file and add the following, replacing the <v1.0-version> and <beta-version> placeholders with the type versions you want to use, for Microsoft Graph v1.0 and beta respectively.

   {  
       "experimentalFeaturesEnabled": {  
           "extensibility": true  
       },
       "extensions": {
           "microsoftGraphBeta": "br:mcr.microsoft.com/bicep/extensions/microsoftgraph/beta:<beta-version>",
           "microsoftGraphV1_0": "br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:<v1.0-version>"   
       }
   }
   

4. In main.bicep, update the extension microsoftGraph declaration to use the extension version names you defined in the bicepconfig.json file.

   // Use both extension version declarations, to declare Microsoft Graph resources from beta and v1.0, in the same Bicep file 
   extension microsoftGraphV1_0
   extension microsoftGraphBeta
   
   @description('Group to use')
   param groupName string = 'TestGroup-20240816'
   
   @description('Apps to use')
   param appName string = 'TestApp-20240816'
   
   // using v1.0
   resource group 'Microsoft.Graph/groups@v1.0' existing = {
       uniqueName: groupName
   }
   
   // using beta
   resource app 'Microsoft.Graph/applications@beta' existing = {
       uniqueName: appName
   }
   
   output groupId string = group.id
   output appId string = app.id